====== Tag Plugin ======

===== Beispiel (dt.) =====

==== Tag-Label setzen ====
:!: Funktioniert mit Umlauten und ''ß'' nicht zuverlässig, daher lieber auf ''ae'', ''oe'', ''ue'' und ''ss'' ausweichen.\\ \\

<code>{{tag>Kategorie1 Kategorie2}}</code>\\
ergibt //(siehe ganz rechts)//
{{tag>Kategorie1 Kategorie2}}

==== Link zu einer automatisch erstellten Tag-Index-Seite ====
<code>{{tagpage>Gebraeuche&dynamic}}</code>
ergibt\\
{{tagpage>Gebraeuche&dynamic}}

===== Components =====

==== Tag ====

  {{tag>[list of tags]}}
  
^ [list of tags]  | a space separated list of tags that describe the content of the current page  | required  |

Allows you to categorize your wiki pages. The resulting links either point to the corresponding page in the specified tag namespace (only if it exists). If you want a link to point to a page in another namespace, you have to indicate the namespace before the tag name. If this page doesn't exist, just the list of pages with the same tag is shown when you follow one of those links.

Examples:
  * ''%%{{tag>tag1 tag2 tag3}}%%'' 
  * with namespaces: ''%%{{tag>ns1:tag1 ns1:tag2 ns2:subns1:tag3}}%%''
  * mutiple word tags: ''%%{{tag>tag1_with_multiple_words tag2 tag3_part}}%%''


==== Topic ====

  {{topic>[tag]&[flags]}}

^ [tag]    | the category tag for which you want a list of pages        | required  |
^ [flags]  | pagelist flags delimited by ''&'', see [[pagelist#flags]]  | optional  |

This displays a list of all pages that contain the given category tag. The list is sorted alphabetically by page ID. You can also prepend the modifiers ''+'' and ''-''. ''+'' creates an intersection between the list of pages created by the already defined tags and the pages matching the tag following the ''+'' (AND), ''-'' removes all pages tagged with the given tag from the list of already found pages.

Example: 
  * ''%%{{topic>tag1 -tag2}}%%'' -- Lists all pages tagged with tag1 but not with tag2.
  * ''%%{{topic>tag1 +tag2}}%%'' -- Lists all pages tagged with tag1 and tag2.
  * ''%%{{topic>tag1 tag2}}%%'' -- Lists all pages tagged with either tag1 or tag2 or both.
  * ''%%{{topic>ns1?tag1 tag2}}%%'' -- List all pages inside namespace ns1 tagged with either tag1 or tag2 
  * ''%%{{topic>.?tag1 tag2}}%%'' -- List all pages inside the current namespace tagged with either tag1 or tag2 
  * ''%%{{topic>tag1 tag2 tag3&nodate&desc&sort}}%%'' (Adding [[:plugin:pagelist|pagelist]] options to change the design)

==== Searchtags ====

   {{searchtags&[flags]}}

^ [flags] | pagelist flags delimited by ''&'', see [[pagelist#flags]] | optional |

This displays a search form with the possibility to select a namespace and to select tags from a table of all tags that should either be in- or excluded with the option to choose if the tags should be associated with AND or OR. The results are displayed as in the topic component.

This is a great feature which you should not miss. Please add a screenshot of this cool feature. FIXME

And you might check out [[plugin:tagfilter|TagFilter Plugin]] for similar purpose but in different scenarios.

Example:
  * ''%%{{searchtags}}%%'' -- The basic syntax
  * ''%%{{searchtags&nodate&desc&sort}}%%'' -- with [[:plugin:pagelist|pagelist]] options to change the design
==== Count ====

  {{count>[tag]}}

^ [tag] | the category tag for which you want the list the occurrence | required |

This part allows you to display an overview of your current used tags. It prints the tag and the related occurrence (how often is the tag used?) in your wiki. Either you can specify a ''+'' as tag-name, which results in a list of all used tags or just specify some tags separated by spaces.

Example:
  * ''%%{{count>+}}%%'' -- List all tags with related occurrences.
  * ''%%{{count>tag1 tag2}}%%'' -- List the occurrence of tag1 and tag2.
  * ''%%{{count>tag1 tag2 tag3&. ns1 ns2}}%%'' -- List all occurrences for the given tags inside the namespaces (the dot specifies the root namespace)
  
==== Tagpage ====

   {{tagpage>[tag][&dynamic][|title]}}

This displays a link to the listing of all tags as it is done by the [[#Tag]] syntax but without tagging the page with that tag. With the optional ''dynamic'' flag the link becomes red when the listing of all pages with that tag is empty for the current user. The ''dynamic'' flag automatically disables the cache of the current page in order to ensure that the link color is always correct. Optionally a title can be specified that will be used as link name.

Example:
  * ''%%{{tagpage>test_foo}}%%'' -- The basic syntax
  * ''%%{{tagpage>test_foo&dynamic}}%%'' -- A link with dynamic link color
  * ''%%{{tagpage>test_foo|my title}}%%'' -- A link with custom title
  * ''%%{{tagpage>test_foo&dynamic|my | title}}%%'' -- A link with dynamic link color and custom title (that can also contain ''%%|%%'')

===== Configuration =====

The plugin can be configured with the DokuWiki configuration manager available in the admin menu.

^ ''namespace'' | Namespace where the tag plugin looks for existing tag pages and links to them instead of the default tag overview. You could use the topic component to display the list of tags on such a page for example. (default ''tag'') |
^ ''sortkey'' | Order in which tagged pages are sorted in the topic overview; available options are ''cdate'' as creation date, ''mdate'' as modification date, ''pagename'', ''id'' as page ID, ''ns'' as namespace and ''title'' |
^ ''sortorder'' | Sort order of the topic overview. |
^ ''pagelist_flags'' | Comma separated [[plugin:pagelist#Flags]] of the [[plugin:pagelist]] plugin which is used to display the topic overview |
^ ''toolbar_icon'' | Show icon in page editor toolbar to add tags. |
^ ''list_tags_of_subns'' | When counting tags in specified namespaces include also tags in subnamespaces. |
^ ''tags_list_css'' | Choose tags list style between standard or optimised for top of page position. |
