version=pmwiki-2.2.4 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Macintosh; U; PPC Mac OS X 10_4_11; en) AppleWebKit/530.19.2 (KHTML, like Gecko) Version/4.0.2 Safari/530.19
author=Scott Connard
charset=ISO-8859-1
csum=Category.GroupFooter is now part of the PmWiki release
host=68.38.68.7
keywords=categories, tags
name=PmWiki.Categories
rev=67
targets=Category.GroupFooter,Category.Category,PmWiki.EditVariables
text=(:Summary:Categories are a way to organize and find related pages:)%0a(:keywords categories, tags:)%0a(:Audience: authors (intermediate) :)%0a%0a!!Purpose of categories%0aCategories (also known as "tags") are a way to organize and find related pages.  Categories are implemented by default in PmWiki 2, and in most wikis they don't require any special code or markup, they're just a useful convention.  The idea is that every page that falls into a particular subject area should have a link to a shared page containing links to other pages on that subject.  These pages are created in the ''Category'' group, and thus these subject areas are called "categories".%0a%0a!!Using categories%0aGetting categories to work requires a single step: adding links to each category.  A category named Subject is created by adding a link to [=Category.Subject=] on any page.  When you add the link to a page, the page can be described as being ''in'' the category "Subject".  %0a%0aThere is a special markup for creating these links which makes categories work more smoothly: [=[[!Subject]]=] will create a link to Category.Subject. So [=[[!Subject]]=] is a kind of shortcut to the page Subject in the category group.%0a%0aA [[Category.GroupFooter]] file is included in the PmWiki release that contains the line [@(:pagelist link={*$FullName} list=normal:)@] so that whenever a category page is displayed, it will show a list of links to pages that reference that page in the category group.  Like any other page in [@wikilib.d@] you can modify this page and it will not get overwritten by another release.%0a%0aIt is worth noting that rather than using Category.GroupFooter, the pagelist directive can be added to Category.GroupHeader to similar effect; it just depends on whether you'd prefer to have the list of pages appear before or after any text that you add to the individual category pages (which can be edited just like normal pages).%0a%0aBecause we use the normal [[Cookbook:PagelistExplained|PageList]] @@link=@@ markup, you can use it not only in the category group. If you want to show all pages belonging to the category Subject you can use on any wiki page [@(:pagelist link=Category.Subject list=normal:)@].%0a%0aSimilarly, there's no requirement that a "category page" has to be in the ''Category'' group -- any page can define a "category" of pages that link to it.%0a%0aAn administrator can override the default category group name of "Category" by setting the $CategoryGroup variable in ''config.php'' to another group name.%0a%0aA page author can also link to a category list without adding the linking page to the category by using [=[[ {Category.Subject$PageUrl} | Subject ]]=].  This will create a link that looks like [=[[!Subject]]=] without adding the linking page to the category listing.%0a%0a!!!Recap%0aSo, by adding the link [=[[!Subject]]=] to a page, a link to that page will automatically appear on the page ''Category.Subject'', as long as  ''Category.GroupFooter'' has been tweaked appropriately.  Thus, you can create a page that automatically creates an alphabetized list of all movies discussed on your wiki by creating links to [=[[!Movies]]=] on each film's page; the resulting automatic list would be on the page ''Category.Movies'' .  %0a%0a%25audience%25 authors (advanced)%0a[[#CategoryNesting]]%0a!!Category nesting%0aCategories have the potential for even greater usefulness because [@Category.*@] pages can themselves be placed into categories!  To follow an excellent example from John Rankin, let's suppose we have the following film pages in the categories listed to the right:%0a%0a-> [@%0aFilm.ShaunOfTheDead   [[!Horror]] [[!Comedy]] [[!2003]]%0aFilm.InMyFathersDen   [[!Drama]] [[!2004]]%0aFilm.TheCorporation   [[!Documentary]] [[!2003]]%0a@]%0a%0aNow then, we can create [@Category.Horror@], [@Category.Comedy@], [@Category.Drama@], and [@Category.Documentary@], and in each one of those pages we put [@[[!Genre]]@].  In [@Category.2003@] and [@Category.2004@], we put [@[[!Year]]@].%0a%0aSo, what happens when we display [@Category.Genre@] ?  We see links to "Comedy", "Drama", "Documentary", and "Horror", because they're in the Genre category.  When we click on one of those links, we see all of the films listed in one of those categories.  Similarly, if we click on [@Category.Year@], we see links to "2003" and "2004", each of which in turn displays the list of films for that year.%0a%0aFinally, in [@Category.Genre@] and [@Category.Year@] we can put [@[[!Category]]@], which makes them "top-level" categories reachable from the [@Category.Category@] page.  Voila, we now have an instant "hierarchy":%0a%0a-> [@%0aCategory.Category%0a    Category.Genre%0a        Category.Comedy%0a            Film.ShaunOfTheDead%0a        Category.Drama%0a            Film.InMyFathersDen%0a        Category.Documentary%0a            Film.TheCorporation%0a        Category.Horror%0a            Film.ShaunOfTheDead%0a    Category.Year%0a        Category.2003%0a            Film.ShaunOfTheDead%0a            Film.TheCorporation%0a        Category.2004%0a            Film.InMyFathersDen%0a@]%0a%0aNote however that this isn't a "strict" hierarchy--i.e., any page or category can appear simultaneously in multiple categories.  For example, [@Category.Documentary@] could be a member of both the Genre and top-level category listings.%0a%0aEach category page can have content text before the generated list, e.g., to give a generic description of things in the category. (Or it can be empty, which works fine.) It can also contain associations to related categories ("see also" references). For example, in a tourism wiki, the ''bed and breakfast" category might contain a see-also reference to the "self-catering" category.%0a%0a%25audience%25 administrators (intermediate)%0a!!The guts of the category markup%0aAs mentioned, all of the necessary markup features for Categories are enabled by default in current releases of PmWiki 2.0, but here's how they work for those who are interested.  The use of the Category group as the repository for all categories is determined by setting the $CategoryGroup variable, and the special [=[[!Subject]]=] markup is activated by a call to the Markup() function:%0a %0a-> [@SDV($CategoryGroup,'Category');%0aMarkup('[[!','%3clinks','/\[\[!([^\|\]] ?)\]\]/',%0a  "%3cspan class='category'>[[$CategoryGroup/$1]]%3c/span>");%0a@]%0a%0a%0a!!Coming up with good category schemes%0aThe hard part about using categories is choosing a good vocabulary. Site content managers may wish to follow the Guidelines for the establishment and development of monolingual thesauri (ISO 2788-1986) and the Guidelines for the establishment and development of multilingual thesauri (ISO 5964-1985). Questions to think about include:%0a* whether a scheme already exists and can be reused%0a* number of levels in a multilevel scheme (not too shallow, not too deep -- e.g. 3)%0a* number of categories per page (not too many, not too few -- e.g. 3)%0a* consistent use of singular ([@[[Mercury]] is a [[!planet]]@]) or plural ([@[[Mercury]] is in the [[!planets]] category@])%0a* disambiguation and use of phrases ([@[[!musical instruments]]@] and [@[[!medical instruments]]@])  or [[Cookbook:Subpage Markup]] ([@[[!Instruments*Musical]]@] and [@[[!Instruments*Medical]]@])%0a%0aOr you can just let people use whatever category terms they find meaningful. A vocabulary (or "folksonomy") will emerge over time.%0a%0a!!Showing a list of categories%0a%0aTo show a list of categories we can use a pagelist for the pages in the category group. %0aFor instance the following will list pages in the Category group, put it on page [[Category.Category]] for convenience, or on any other page:%0a%0a->[@(:pagelist group=Category list=normal fmt=#title:)@]%0a%0aBut there is a problem: Just adding a category markup to a page will not create a corresponding category page, even though following the link will show the page with a list of pages linking to it!\\%0aTo have category pages automatically created in group 'Category'  add the following to config.php:%0a%0a->[@$AutoCreate['/^Category\./'] = array('ctime' => $Now, 'text' => $page['text']);@]%0a%0aChange 'Category' to the name of your category group. You can also add more definitions for more category groups, useful if you use a recipe like Cookbook:Tagger which allows multiple category groups.%0a%0aSee also [[PmWiki/EditVariables#AutoCreate]]%0a
time=1248048308