>>recipeinfo<<
Summary: Easy tagging into multiple category groups.
Version: 20110729
Prerequisites: PmWiki version 2.2-beta65
Status: beta
Maintainer: [[~Kathryn Andersen]]
Categories: [[!Links]], [[!Markup]], [[!CMS]]
File: Attach:tagger.php
(:if exists {$Name}-Talk:)Discussion: [[{$Name}-Talk]](:ifend:)
>><<
!! Questions answered by this recipe

How can I tag a page with multiple tags, for multiple category groups?
How can I tag pages without having to type in link markup?

!!Description
(:Description Tag a page with multiple tags in multiple category groups.:){$Description}

The tagger script uses a subset of page-text-variable markup to "tag" pages; that is, to link the page
to the corresponding page (that matches the value of the tag) in another group.  This is done by associating a "tag name" page-text-variable
with a "tag-group" to be linked to.

!!!Example

For example, suppose you're gathering information about fiction, with a page for each story, and you want to collate authors and genres.

With Tagger, you can associate "Author" with the "Authors" group, and "Genre" with the "Genres" group.

[@
$TaggerGroups['Author'] = 'Authors';
$TaggerGroups['Genre'] = 'Genres';
@]

Then when you type

[@
Author:Fred Nurk
Genre:Historical
@]

it will be interpreted as links, as if you had typed

[@
Author:[[Authors/Fred Nurk]]
Genre:[[Genres/Historical]]
@]

But wait, there's more!

What if Fred Nurk's epic work wasn't just historical, but a historical romance?  And rather than making a separate genre for historical romance, you wanted it to be counted as Historical and Romance both?  Tagger allows you to do this, by defining certain characters (such as a comma) as "separators".

[@
Author:Fred Nurk
Genre:Historical, Romance
@]

This will give links as if you had typed this:

[@
Author:[[Authors/Fred Nurk]]
Genre:[[Genres/Historical]], [[Genres/Romance]]
@]

Likewise, if Fred Nurk co-authored his epic with Barbara Cartland, then you could do this (since '&' is also a separator character by default):

[@
Author:Fred Nurk & Barbara Cartland
Genre:Historical, Romance
@]

giving links as if you had typed this:

[@
Author:[[Authors/Fred Nurk]] & [[Authors/Barbara Cartland]]
Genre:[[Genres/Historical]], [[Genres/Romance]]
@]

!!!Markup

Tagger accepts two forms of markup: the Tag:Value markup and the [@(:Tag:Value:)@] markup.

[@
Tag:Value
(:Tag:Value:)
@]

The "Value" can contain multiple "values", separated by a separator.  The default separators are comma ',', slash '/' and ampersand '&'.  However, you cannot mix different separators in the same Value.

The [@(:Tag:Value:)@] markup will be hidden as a hidden page-text-variable.  Note, however, that Tagger will ignore hidden PTVs which span multiple lines; it must all be on one line.

!!!Page Variables

For each Tagger "tag", there are a few Page Variables.  These can be useful in pagelist templates.

|| border=1
||'''Name'''||'''Description'''||
||''Tag''Linked||Contains links to all the tag-pages, with their labels being the title of the page linked to.||
||''Tag''LinkedName||Contains links to all the tag-pages, with their labels being the name of the page linked to.||
||''Tag''Name||The tags munged together into one word, as if it was a page-name||

!!!Configuration Variables

|| border=1
||'''Name'''||'''Description'''||'''Default'''||
||$TaggerGroups|| tag => group-name ||empty||
||$TaggerTagSeparators||What characters can be used to separate tags.||[@$TaggerTagSeparators = array(',','/','&'));@]


!!!Activation

To activate this script, copy it into the cookbook/ directory, then add
the following lines, for example, to your local/config.php:

[@
$TaggerGroups['MyTag'] = 'MyTagGroup';
$TaggerGroups['MyOtherTag'] = 'MyOtherTagGroup';
include_once("$FarmD/cookbook/tagger.php");
@]

!! Notes

IWFM (it works for me).  It works with [[Cluster]].

!! Release Notes

%comment% If the recipe has multiple releases, then release notes can be placed here.  Note that it's often easier for people to work with "release dates" instead of "version numbers".
* (2008-01-27) Initial version
* (2011-07-29) Minor bug correction in output

!! Comments
(:if false:)
This space is for User-contributed commentary and notes.
Please include your name and a date along with your comment.
Optional alternative:  create a new page with a name like "ThisRecipe-Talk" (e.g. PmCalendar-Talk).
(:if exists {$Name}-Talk:)See Discussion at [[{$Name}-Talk]](:ifend:)

!! See Also

*[[PmWiki/Categories]]
*[[(Cookbook:)Automatic Links]]
*[[(Cookbook:)List Categories]]
*[[(Cookbook:)Tags]]
*[[(Cookbook:)WPCategories]]
*[[(Cookbook:)Media Categories]]

!! Contributors

* [[~DaveG]] for suggesting the name "Tagger".
* [[~AntonyTemplier]] Bug correction