====== TagFilter Plugin ======

---- plugin ----
description: Allows to create custom dropdown fields to easily filter pages based on tags
author     : lisps, peterfromearth
email      : coder@peterfromearth.de
type       : syntax,action,helper, remote
lastupdate : 2023-10-21
compatible : Jack Jackrum, Igor, Hogfather, Greebo, Frusterick Manners, Elenor Of Tsort, Detritus
depends    : tag, pagelist
conflicts  : 
similar    : 
tags       : ajax, filter, tags

downloadurl: https://github.com/lisps/tagfilter/archive/master.zip
bugtracker : https://github.com/lisps/tagfilter/issues
sourcerepo : https://github.com/lisps/tagfilter/
donationurl: 

screenshot_img : https://github.com/lisps/tagfilter/raw/master/example/example1.png
----

===== What it Does =====

This plugin takes tags that you have added with a tag category, using the tag plugin, and allows you to filter by the category, displaying the results ...

  * as links, using the [[plugin:pagelist]] plugin to control formatting,
  * or optionally rendering the pages in-place using the [[plugin:include]] plugin.

===== Installation =====

:!: **External requirements:** This plugin requires the following additional components that must be installed separately: 
  * [[plugin:tag]]
  * [[plugin:pagelist]]
  * [[plugin:pageimage]] (optional)
  * [[plugin:include]] (optional)

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.


===== Examples/Usage =====

**The Basics**

You must have added some tags with tag categories, see the [[plugin:tag]] plugin. There are formatted as follows:

<code>{{tag>category1:tag1 category2:tag2}}</code>

In the following examples there are two pages tagged as follows:
  * Page 1 ''<nowiki>{{tag>status:ready version:weatherwax}}</nowiki>''
  * Page 2 ''<nowiki>{{tag>status:start version:Angua}}</nowiki>''

==== Tagfilter ====

Tagfilter uses the tag categories to specify what to show as filters and you can also default the values. 

This tag filter defaults the status to 'Ready', which is only used on Page 1, and the user can only select one value in the dropdown:

  {{tagfilter>Status=status:.*=status:ready|Version=version:.*&nouser&nodate}}
  
{{ https://github.com/lisps/tagfilter/raw/master/example/example1.png }}

This tag filter defaults the status to 'Ready', which is only used on Page 1, but the user the user can only select multiple values in the dropdown:

  {{tagfilter>Status=status:.*=status:ready|Version=version:.*&nouser&nodate&multi}}
  
{{ https://github.com/lisps/tagfilter/raw/master/example/example2.png }}  

This tag filter defaults the status to 'Ready', which is only used on Page 1, but uses the chosen parameter (not clear what this does):

  {{tagfilter>Status=status:.*=status:ready|Version=version:.*&nouser&nodate&chosen}}
  
{{ https://github.com/lisps/tagfilter/raw/master/example/example4.png }} 

This tag filter defaults the status to 'Ready', which is only used on Page 1, but uses the chosen (not clear what this does) and multiple parameters:

  {{tagfilter>Status=status:.*=status:ready|Version=version:.*&nouser&nodate&multi&chosen}}
  
{{ https://github.com/lisps/tagfilter/raw/master/example/example3.png }}

==== Tagcompare ====
Use tagcompare to compare tags between pages. 
You can select the page in columns and for each tag expression there will be a row.

  {{tagcompare>Status=status:.*=status:ready|Version=version:.*}}

{{:plugin:plugin:tagfilter:tagcompare.png|Example of the tagcompare}}
[[https://drive.google.com/file/d/1Pa07W0Ez62Z-JSO2cT5y-rNdSMY05fYg/view|Example Link]]

===== Syntax =====

Basic syntax:
<code>{{tagfilter>(namespace)?(tags-filter-groups)&(flags)}}</code>
  * **(namespace)** defines the namespace of the filtered pages
  * **(tags-filter-groups)** defines the different dropdown fields: Syntax (Label)=(RegExpr)=(Standard) seperated by a ''|''
    * //(Label)// the dropdown-field label
    * //(RegExpr)// a regular expression with which you can select the options for the select
    * //(Standard)// a standard value to be selected
  * **(flags)**
    * ''multi'' enables multiselect of tags
    * ''chosen'' enables the chosen plugin for tag searching
    * ''tagimage'' show image next to tagname in dropdown boxes. Needs ''chosen'' tag. If image is ''status:a'' image needs to be ''tags:status_a.[png|jpg|gif|jpeg]''. Namespace ''tags'' (where the images needs to be placed) is a admin setting (''nsTagImage'') Needs the [[plugin:pageimage]] plugin.
    * ''pagesearch'' add an extra dropdown field at the beginning to search for the page itself.
    * ''sortbypageid'' sort by page id rather than title
    * ''rsort'' enable reverse sort of pages
    * ''nolabels'' do not show labels
    * ''noneonclear'' show no pages when nothing is selected
    * ''excludeNs=<comma seperated list of namespaces>'' exclude specific namespaces
    * ''withTags=<comma seperated list of tags>'' these tags must be present on all pages
    * ''excludeTags=<comma seperated list of tags>'' these tags must not be present on all pages
    * ''tagintersect'' a page needs all selected tags (//>2020-02-21//)
    * ''count'' show the numbers of found pages
    * ''tagcolumn=<tagexpr>'' show an additional column in pagelist reslut with the selected tags of the page (e.g. ''status:.*'')
    * ''tagimagecolumn=<tagexpr>=<imagenamespace>'' show an additional column in pagelist result with an image defined through the tag. (e.g. with ''&tagimagecolumn=status:.*=tags'' and the page has version:example as a tag, the image tags:example.[png|jpg|gif] will be used). Needs the [[plugin:pageimage]] plugin.
    * [[plugin:pagelist]] flags 
    * ''include'' or ''include=option1;option2;option3'': Use the [[plugin:include]] plugin to render the pages in-place.

===== Configuration and Settings =====
==== Admin Configuration ====

^ Option ^ Description ^
| ''cache_age'' | How long should pages with tagfilter be cached (in seconds), 0 for no caching|
| ''DropDownList_size'' | Number of items to show in classic multiple dropdown mode |


=== Known Bugs and Issues ===


=== ToDo/Wish List ===


===== FAQ =====

===== Development =====

=== Change Log ===


[[https://travis-ci.org/lisps/tagfilter|{{  https://travis-ci.org/lisps/tagfilter.png?nocache|Build Status}}]]

{{rss>https://github.com/lisps/tagfilter/commits/master.atom date}}

===== Discussion =====

==== Set header title? ====
Is it possible to specify the header to be something other than "tagfilter"? \\

==== Make multi search AND instead of OR ====
Is it possible to have the multi search be AND instead of OR?  \\
IE, I have the following tagfilter on a page \\
<code>{{tagfilter>Type=tag:typ\..*|Ethnicity=tag:eth\..*|Ingredients=tag:ing\..*&chosen&multi}}</code>
I want to be able to select specific ingredients and only see recipes that include ALL those ingredients.
Also, even though I'm using chosen, I am still getting a dropdown menu instead of a search box.


>> This documentation needs some serious improvement, it's not clear at all what this plugin does and how.
> Can you say where exactly your problem is? 
> First, the plugin heavily relies on the [[plugin:tag]] plugin. 
> To give an example: lets say you have the three pages 
> **task:task1**
> <file>
==== Task1 ====
{{tag>version:v1 status:done year:2013}}
</file>
> and **task:task2**
> <file>
==== Task1 ====
{{tag>version:v2 status:open year:2013}}
</file>
> and **task:task3**
> <file>
==== Task1 ====
{{tag>version:v3 status:open year:2014}}
</file>
> and define the tagfilter as followed
>  <code>{{tagfilter>task:?Status=status:.*=status:open|Version=version:.*|Year=year:.*}} </code>
> now you can filter the three pages with the version, status and year tags (where the tag status:open is set on page load)
>>I think the use of tags that have colons in your examples are confusing (to me, a noob anyway). I first was confused because I thought the colons had something to do with DokuWiki page syntax. I use a dash so my tag examples would look like: version-v3 status-open, etc. \\ 
>>And so my code would look like 
>><code>{{tagfilter>task:?Status=status-.*=status-open|Version=version-.*|Year=year-.*}} </code>
>>.. which brings me to **my** question & comment, which is where does a noob find the explanation of the dot (.) before the asterisk (*) syntax? .. And, 
> As I described in the documentation it is a [[wp>Regular_expression|Regular Expression]].

>>I'm afraid I have to agree that the documentation needs improvement.  First you need a clear opening statement as to what the plugin does.  Then you should have a list of the options and flags with clear statements about how each works.  Then after explaining the options and flags give your examples.--- [[user>turnermm|Myron Turner]] //2015-12-18 12:39//

>> I come back to this three years later, because of a question someone had on the forum, and I find that the documentation still is not clear enough. This looks like it could be useful but it shouldn't be a struggle to learn how to use it. For improvements I refer to my previous comment. --- [[user>turnermm|Myron Turner]] //2018-10-17 17:58//

==== Can you please provide an update for the latest DokuWiki release? ====

==== Is it possible to do a count of the returned pages? ====
Not in this version, but feel free to open a request on github - with a description how you would like to have it implemented and with example images.

==== Which plugin is the 'chosen' one? ====

Thanks for the great plugin!

I have trouble understanding the following instruction:
> ''chosen'' enables the chosen plugin for tag searching
Where have I chosen a plugin? Is it the "tagfilter" plugin? Or is "chosen" the name of another plugin, and where can I find it?

Apart from that, is it possible to apply 'chosen' and 'multi' only to some of the search field, not all?

**Answer:**\\
''chosen'' enables the so called [[http://harvesthq.github.io/chosen/|Chosen Plugin]], which is delivered within the tagfilter plugin. Actually it is not possible to set separate select fields as ''multi'' or ''chosen''. 

==== About RegExp support ====
How can I set a filter showing only certain tags ?
For example, I've tried to make a filter combo showing only *HowTo* and *Faq* tags.
The regexp for that would be

  Filter=(howto|faq)

But that's not working. The page shows 'faq' as another filter...
How could make it work ?

as ''|'' is the seperator for the different filters it is not possible with this version of tagfilter.
Possibilities: 
  - rename your tags to page:howto and page:faq and work with filter Filter=page:.*
  - change the separator in syntax.php
==== No search results ==== 
How to debug why I get no search results?
I added the following line to show all tags. However, bevore and after selecting one entry, no search results are shown.

<file>{{tagfilter>Hersteller=.*=&nouser&nodate&multi&chosen}}</file>

What is wrong?

EDIT: I looked a bit around in the PHP Files and found, that adding the following line in ajax.php gives me a somehow running solution. I am not sure about the Namespaces, but I get results...

<file php ajax.php>
$page_names = array();
foreach($tag_list_r as $key=>$tag_list){ 
	$tags_parsed = $Htag->_parseTagList($tag_list, true);
	$pages_lookup = $Htag->_tagIndexLookup($tags_parsed);
	foreach($pages_lookup as  $page_lookup){
		// filter by namespace, root namespace is identified with a dot // root namespace is specified, discard all pages who lay outside the root namespace
		if(($ns == '.' && (getNS($page_lookup) == false)) || ($ns && (strpos(':'.getNS($page_lookup).':', ':'.$ns.':') === 0))) {
			$perm = auth_quickaclcheck($page_lookup);
            if (!($perm < AUTH_READ))
				$page_names[$key][] = $page_lookup;
		}
		$page_names[$key][] = $page_lookup; // This line was added +++++++++++++++++++++
	}
}
</file>

>Thanks for sharing, but your code seems bypass the ACL check, which might have security issue. The official new code's link was added in [[plugin:tagfilter#Installation| Installation]] section, which fixes the bug you mentioned to some degree, allowing you to filter tags without specifying namespace. But it still can not specify the root namespace, see [[https://github.com/lisps/tagfilter/issues/6 | this issue]].

--> There seems to be a problem showing filtering results for pages with id containing "_template" keyword at the end (see "Template nicht anzeigen" in helper/syntax.php), avoid using it (e.g. id=project_presentation_template or id=project_presentation_template_page won't appear, but id=project_presentation_templat2 will be present in filtering results).

==== Terminology & Description ====

It is confusing because you refer to tag categories and the Tag plugin also uses the word 'category' but to describe what a tag is i.e. a categorisation of a page. It would be clearer if you use the term TagGroup.

I also suggest that you change the syntax to remove the use of colon because this looks like a reference to a namespace. However, if you were to do this one would also need a way to apply a global edit for those that have implemented with colons.

--- [[user>lizat|Liz T]] //2020-10-14 13:41//