====== Tagging Plugin ======

---- plugin ----
description: Allows users to annotate pages with tags, search for tags and show all tags one user has used
author     : Adrian Lang 
email      : dokuwiki@cosmocode.de 
type       : action, helper, syntax
lastupdate : 2023-09-27
compatible : Frusterick Manners, Elenor of Tsort, Detritus, Hrun, Greebo, Hogfather
depends    : sqlite
conflicts  : 
similar    : labeled, tag
tags       : tags, cloud, tagcloud, annotations

downloadurl: https://github.com/cosmocode/tagging/zipball/master
bugtracker : https://github.com/cosmocode/tagging/issues
sourcerepo : https://github.com/cosmocode/tagging/
donationurl: 

screenshot_img : https://trello.com/1/cards/64480d827040b1c58e250341/attachments/64480df5c8d392fbdbfe8bee/download/dokuwiki-plugin-tagging.png
----

[[https://www.cosmocode.de/en/open-source/dokuwiki-plugins/|{{ https://www.cosmocode.de/static/img/dokuwiki/dwplugins.png?recache|A CosmoCode Plugin}}]]


===== Installation =====

:!: This plugin requires the following additional plugin that must be installed separately:

  * [[plugin:sqlite|SQLite plugin]]

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

Several templates (like e.g., [[template:sprintdoc]]) support this plugin right out of the box.

In other cases after installation you need to add the component to display and edit a page's tags to your wiki. There are two ways.

==== Use in Sidebar ====

If your template supports a [[faq:sidebar]] you can add the following syntax to its contents to display the tagging component:

<code>
{{tagging::input}}
</code>

Please note that this will disable caching for the sidebar page.

==== Embed in Template ====

Alternatively you can add the tagging component directly into your template's main.php:

<code php>
<?php
    //show tagging only if user has access to page. Works on wikis with disabled acl too.
    if (auth_quickaclcheck(getID()) >= AUTH_READ ) {
        //check if sqlite plugin exists, tagging plugin requires it.
        if (!plugin_isdisabled('sqlite')) {
            //Tagging
            $tagging = plugin_load('helper','tagging');
            if ($tagging) {
                $tagging->tpl_tags();
            }
        }
    }
?>
</code>

Users of the [[template:dokuwiki]] template could also put above code in a newly created file ''conf/sidebarfooter.html''.

=== Using with Vector Template ===

Users of the [[template:vector]] template could also put following to ''dokuwiki/lib/tpl/vector/**user**/boxes.php'' (**NOT** ''dokuwiki/lib/tpl/vector/**conf**/boxes.php''):

<code php>
//show tagging only if user has access to page. Works on wikis with disabled acl too.
if (auth_quickaclcheck(getID()) >= AUTH_READ ) {
    //check if sqlite plugin exists, tagging plugin requires it. if it doesn't exist or is disabled, vector template won't render
    if (!plugin_isdisabled('sqlite')) {
        $tagging = plugin_load('helper','tagging');
        if ($tagging) {
    	    $_vector_boxes["tagging"]["headline"] = "Tagging";
	    $_vector_boxes["tagging"]["xhtml"] = $tagging->tpl_tags(false);  //set $print to false
        }
    }
}
</code>

The first param of ''tpl_tags($print = true)'' is set to ''false'' to prevent direct printing.

===== Usage =====

Tags can be assigned to pages by any logged in user with write permissions for the page in question. Anonymous users can never tag pages, even if they have write permissions.

Once the code mentioned in the install section is inserted into your template, each page will show the current page's tags and allows to edit them. Each tag is linked to a search for that tag.

==== Single-User vs. Multi-User mode ====

By default the tag plugin will record tags separately for each user. Each user can add their own tag to a page. Users may only edit the tags they added themselves.

If you want all your users to maintain a single tag corpus, you can switch the plugin to 'single user mode' in the config. All tags will be saved under the username ''auto'' and can be edited by all users.

==== Embedding Clouds in Pages ====

A syntax component allows to embed tag clouds in pages. A tag cloud displays a list of tags where more often used tags are shown larger than less frequently used ones.

To list all tags used by pages in the current namespace (and below) use the following syntax:
<code>
{{tagging::ns}}
</code>

To specify a certain namespace (other than the current one) add it like this:
<code>
{{tagging::ns>NAMESPACE}}
</code>

To list all tags used by pages of whole wiki, independent of current namespace use the following syntax:
<code>
{{tagging::ns>*}}
</code>

To list all tags that were used by the currently logged in user use the following syntax:
<code>
{{tagging::user}}
</code>

To show the tags of a specific user, add the user name like this:
<code>
{{tagging::user>USERNAME}}
</code>

==== List Tagged Pages ====

List all pages tagged with a specific tag:

<code>
{{tagging::tag>TAGNAME}}
</code>
==== Hidden Tags ====

You can configure a prefix for tags that should not be shown to users who can't add tags themselves. By default it's set to the ''@'' character.

Hidden Tags are useful as shortcuts to be used with the jump function below.

==== Jump to Tagged Page ====

It's possible to directly jump to a page tagged with a certain keyword using the URL ''%%http://yourwiki/doku.php?do=tagjmp&tag=mytag%%'' where //mytag// is the tag you used on that page.

You can also specify multiple tags to try using the Array syntax in the URL: ''%%http://yourwiki/doku.php?do=tagjmp&tag[]=mytag1&tag[]=mytag2&tag[]=mytag3%%''. Each tag is tried until an existing one is found.

This is useful to assign shortcuts for pages and jump to them from external programs for example. When the content moves you can change the tag and don't need to adjust your external tool.

Please note: if you tagged multiple pages with the same tag, this functionality will simply jump to one of those pages.

When the [[translation]] plugin is installed, the language of each tagged page is recorded. You can then specify the language in the jump action: ''%%http://yourwiki/doku.php?do=tagjmp&tag=mytag&lang=en%%''. If you just recently upgraded the tagging plugin, note that languages will only be recorded for newly added tags.
==== Tag Management ====

An **admin** page allows you to find, rename and delete tags.

In order to include tag management on regular pages to allow **non-admin users** to edit tags, use the syntax below:

<code>
{{tagging::manage}}
</code>

or if you want to limit the initial overview to a certain namespace:

<code>
{{tagging::manage>namespace}}
</code>

All ACL rules are respected, so non-admin users will not be able to view or modify tags if they do not have sufficient privileges for the tagged page.

==== Tag search ====

The plugin integrates with regular search and [[plugin:elasticsearch]]. Use the syntax ''#sometag'' in addition to, or as a standalone search term.

The advanced search tools contain a tag filter. If any of the found pages are tagged, a dropdown list of available tags will let you narrow down the results.

===== Development =====

=== Change Log ===

{{rss>https://github.com/cosmocode/tagging/commits/master.atom date}}

**Releases:**

{{rss>https://github.com/cosmocode/tagging/releases.atom description author}}


=== Known Bugs and Issues ===

Please report bugs and issues at: https://github.com/cosmocode/tagging/issues