Differences

This shows you the differences between two versions of the page.

--- plugin:tagfilter [2018-10-04 21:37] – peterfromearth
+++ plugin:tagfilter [2023-10-21 19:55] (current) – Klap-in
@@ Line 3: / Line 3: @@
 ---- plugin ----
 description: Allows to create custom dropdown fields to easily filter pages based on tags
-author     : lisps, coder@peterfromearth
+author     : lisps, peterfromearth
 email      : coder@peterfromearth.de
-type       : syntax,action,helper
+type       : syntax,action,helper, remote
-lastupdate : 2018-10-04
+lastupdate : 2023-10-21
-compatible : Hrun
+compatible : Jack Jackrum, Igor, Hogfather, Greebo, Frusterick Manners, Elenor Of Tsort, Detritus
 depends    : tag, pagelist
 conflicts  :
@@ Line 20: / Line 20: @@
 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 =====
@@ Line 26: / Line 33: @@
   * [[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.
-:!: **New code is there:** I fixed the download url, please update.
 ===== 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}}
@@ Line 49: / Line 79: @@
 {{ https://github.com/lisps/tagfilter/raw/master/example/example3.png }}
-==== NEW TAGCOMPARE ====
+==== Tagcompare ====
-Use tagcompare to compare tags between pages
+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 =====
@@ Line 66: / Line 100: @@
     * ''multi'' enables multiselect of tags
     * ''chosen'' enables the chosen plugin for tag searching
-    * ''cache=<seconds>'' optional caching time
+    * ''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.
-    * pagelist flags
+    * ''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 =====
@@ Line 76: / Line 122: @@
 | ''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 |
-=== Change Log ===
-  * **2013-10-25**
-    * Initial release
-  * **2013-11-27**
-    * add some performance improvements
-    * add cache option
-    * remember selected tags on browser back-action
@@ Line 96: / Line 132: @@
 ===== 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 =====
@@ Line 139: / Line 183: @@
 >>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? ====
@@ Line 200: / Line 246: @@
 >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//