ClassificationPlugin

A topic classification plugin and application

Description

ClassificationPlugin is a taxonomy and folksonomy extension for Foswiki that allows you to manage knowledge assets stored in your wiki. Users can organize their content by filing topics into categories and by adding offhand tags. Classifying content using categories and tags are the key factors to foster sustainable knowledge management. This becomes even more important in a wiki environment where content is created quickly but has to be made available for a longer period of time.

Categories become the backbone spanning all of your content. Content can then be retrieved by browsing categories narrowing down search results interactively in addition to the normal full-text search.

Key features

Multilevel facet navigation: Wiki content is displayed dynamically by browsing a category tree or by means of interactive tag clouds.

Managing taxonomies the wiki way: Categories in a taxonomy are first-class wiki citizens that can be created, renamed, managed and reused as easily as normal wiki topics.

Expressive knowledge models: Categories may form poly-hierarchies where categories can have multiple parent categories. Wiki documents can be filed into multiple categories at the same time.

Multidimensional classification: A wiki document may participate in multiple taxonomies and folksonomies at the same time. Different facets of a document can be separated in a clean way.

Reusing and merging taxonomies: A category tree once defined in one web space can be imported into another web space effortless. You are free to chose which part of a tree you want to import. Multiple category trees from a number of web spaces can be merged and reassembled differently in a new web. That way predefined taxonomies can be managed in a centralized way and reused as needed in different webs. Any change to a taxonomy in one place will automatically show up in all webs that imported it.

Tagging for corporate intranets: While categories establish a predefined vocabulary, tags are a way to assign keywords to wiki content in an ad hoc fashion. This completes category knowledge management in a natural and fruitful way.

Standardized WikiApplicatons: ClassificationPlugin conforms to the WikiWorkbench application framework that grants for scalable and long-term maintainable WikiApplications.

Extensibility: ClassificationPlugin serves as a building block for further WikiApplications to be integrated in an overall knowledge management infrastructure. It serves as a middleware for a couple of higher order applications, like blogging, forums and skills management available separately.

Document types: ClassificationPlugin adds a couple of document types to the standard set that come with the WikiWorkbench. This gives you maximum flexibility in your knowledge management initiative. Further document types can be derived with ease. These will automatically participate in the overall knowledge management framework.

Facetted Search: ClassificationPlugin integrates well into SolrPlugin using tags and categories to drill down into search results.

Screenshots

ClassificationPluginSnap1.pngClassificationPluginSnap2.pngClassificationPluginSnap3.pngClassificationPluginSnap4.pngClassificationPluginSnap5.pngClassificationPluginSnap6.pngClassificationPluginSnap7.png

Getting started

The easiest way to get started is to create a new web by using the _ClassificationTemplate web as a template. For this

  1. go to WebCreateNewWeb (or ManagingWebs in case you are not using NatSkin)
  2. enter the name of your new web, e.g. "Knowledge"
  3. select _ClassificationTemplate as a template web
  4. click Submit

This will create a new web called "Knowledge" which has got all the means preinstalled to create content under the control of the ClassificationPlugin such as:

  • create new categories on the Knowledge.Category topic
  • create new categorizable and taggable content either using the Knowledge.ClassifiedTopic form or by hitting the "New" button on the top of each button

Customize the frontpage of the new "Knowledge" web by describing the key content and thematic fields stored in it as well as their use. Note that for best findability it is recommended to install SolrPlugin along with ClassificationPlugin. SolrPlugin will be able to automatically generate recommended links to similar content in your "Knowledge" web based on category and tagging meta data. It also lets you filter and trim down search results selecting tags and categories in use.

For further information please contact foswiki@michaeldaumconsulting.com.

The ClassificationApp

ClassificationPlugin is based on the WikiWorkbench application framework as well as being a base for further wiki applications build with ClassificationPlugin itself. It has been used to build more specific apps such as

  • contacts management
  • skills management
  • invoicing
  • data center management

where categories and tags play a gluing role to extract and link together TopicTypes from various domains. In all of these cases custom TopicTypes have been implemented by extending the types coming with the ClassificationPlugin. By standardizing these applications using the WikiWorkbench approach and using the ClassificationApp as a building block, developing wiki apps has reached a new level being long-term maintainable, reusable, extensible and flexible as proven in many real-live corporate intranets.

ClassificationPlugin plays a central role in rolling out a unified knowledge management undertaking that covers very different kinds of content with varying data models.

For more details see the ClassificationApp itself.

Macros

HIERARCHY

Parameter Description Default
[web] web for which to render the hierarchy for base web
top category within the hierarchy to start decending down the hierarchy TopCategory
sort sort categories on each step of the hierarchy according to the given property; possible values: order, name, title, ordertitle; order refers to the Order formfield of a category that can be used to influence sorting manually; sorting categories by order ignores their lexical order as would be the case using title; sorting by ordertitle first reads the Order property of a category and then falls back to lexical order ordertitle
header string to be prepended to categories  
format string to be used to render a category
<ul>
  <li>
    <img src="$icon" /> 
    <a href="$url">$title</a> 
    $children
  </li>
</ul>
topformat format to be used by the top category same as format
nullformat format to be used when no category was found in the web  
separator string to be inserted between categories rendered using format  
footer footer string appended to categories  
placeholder string to be used for the $children variable when a category has no children (empty string)
indent indentation string used for the $indent variable ' ' (three spaces)
mindepth minimum depth from which to start rendering categories 0
depth maximum depth traversing the hierarchy 0 (infinite)
matchattr which attribute of a category to be used sorting the hierarchy; possible values: name, title name
matchcase case sensitivity sorting categories reading matchattr on
exclude regular expression to filter out categories reading matchattr  
include regular expression to filter out non-matching categories  
filter filter expression when counting topics subsumed by a category  
unique if switched on a category will only be listed once if found in multiple places within the hierarchy off
open list of category names to be considered open and which are traversed further down the hierarchy by default all categories are considered "open"
hideclosed if switched on all "closed" categories, i.e. those not listed in open are hidden/not rendered off
hidenull if switched on categories with no topis in them will be hidden off
nrleafs counts of leaf nodes of a category; this value is normally computed automatically; you might use this parameter when counts for are available using different means; format: cat:count, cat:count, ... ; (computed automatically)
nrtopics counts of all topics subsumed by a category; like nrleafs this value is normally compuited automatically; format: cat:count, cat:count, ...  

Format strings such as header, footer, and format may contain the following variables:

Variable Description
$breadcrumbs comma separated list of categories from the top category down to the current one; note that this is a simplified linear representation of the category's location not taking multile parents into account
$call number of iteration steps performed while expanding the %HIERARCHY macro
$count number of topics subsumed by a category; see nrtopics above
$cyclic boolean flag indicating whether the current category is part of a cycle in the hierarchy, which normally indicates a configuration error
$depth distance of the current category to the top category
$icon image url of the icon of the current category
$id id of the category within the hierarchy
$indent indentation string; this variable expands to the indent parameter times the depth of the current category
$index index of the current category among its siblings
$isexpanded boolean flag indicating whether the current category is "open" or "closed"; see the open and hideclosed parameter above
$leafs number of leaf nodes of the current category; see also the nrleafs parameter
$link render anchor markup to render a link to the current category; see also $url
$name topic name of the current category; this value is unique within a hierarchy
$order Order property of a category
$origweb originating web where the category was defined; this value might differ from $web in case the hierarchy has been (partially) imported from another web
$parents comma separated list of parent categories
$siblings number of sibling nodes
$subcats number of subordinated categories
$summary Summary property of a category
$tags Tag property of a category
$title TopicTitle property
$topic topic name of a category (alias for $name)
$trunctitle title of a category with the parent topic's title removed from the prefix if found
$url url to the current category
$web web of the current hierarchy; see also $origweb

ISA

Predicate that checks if a topic is filed in a specific category or one of its subcategories and either returns 1 or 0.

Parameter Description Default
[topic] the topic to look up current base topic
web the web that holds the hierarchy of categories to use current base web
cat a category or a comma separated list of multiple categories TopCategory

Categories listed in the cat parameter are checked in the given order. %ISA returns 1 for the first category found that "contains" topic.

SUBSUMES

Predicate that checks if a category is a parent category of another and either returns 1 or 0.

Parameter Description Default
[_anonymous] a category name at an upper level of the hierarchy current base topic
cat a category or a comma separated list of multiple categories  
web the web that holds the hierarchy of categories to use current base web

The macro tests all categories listed in cat and returns 1 if at least one of them is being subsumbed.

Example:

%SUBSUMES{"CorporateCategory" cat="CustomerCategory, HumanResourcesCategory"}%

Hierarchy:

  • CorporateCategory
    • ...
    • ProductsCategory
    • CustomerCategory
    • ...
  • DepartmentsCategory
    • ...
    • HumanResourcesCategory
    • ...

The result is 1 because CorporateCategory subsumes CustomerCategory even though it doesn subsume HumanResourcesCategory.

DISTANCE

A function that returns the numerical distance of two categories or topics being located in a shared hierarchy. This macro reads the distance matrix being calculated internally that caches the network topology of the hierarchy. Both, the %ISA as well as %SUBSUMES macro are based on distance properties of the items being compared.

Parameter Description Default
[from] the starting point where to start measuring from; this can be a category or a topic current base topic
to the end point to measure the distance; this can be a category or a topic TopCategory
abs boolean flag to switch on/off absolute distances; if switched off results can be negative as well given the order endpoints are specified in from and top off
web the web that holds the hierarchy to use current base web
format format string $dist
undef format string that will be returned in case from or to weren't found or aren't connected at all (empty string)

The distance is defined as follows:

  • return 0 if from equals to
  • returns the minimum number of nodes including the to node to get from category from to category to
  • if from is a topic (not a category) the result is decreased by one
  • if to is a topic (not a category) the result is increased by one
  • if from and to are not connected the result is undef
  • if from is located "higher" in the hierarchy than to the result is negative unless abs has been set to on

When either from or to are topics (not a category) then the set of categories they are filed into are taken into consideration to compute the minimum distance.

CATINFO

Render category information for a given category or topic.

The macro either operates in "cat mode" or "topic mode" when either the topic or the cat parameter has been specified. In "cat mode" the macro returns information about this one category. In "topic mode" it returns information about all categories the topic is filed into.

Parameter Description Default
[topic] the topic to return category information for  
cat a category to return information for; note that topic and cat are exclusive; you can only specify one of them  
format format string to render category information; see the list of possible variables below $link
separator format string used to separate list items =, = (coma + blank)
header header string prepended to the result (empty string)
footer footer string appended to the result (empty string)
web the web that holds the hierarchy to use current base web
subsumes only return info about categories subsumed by this category TopCategory
parentsubsumes only return info about parent categories subsumbed by this category TopCategory
sortchildren switch on/off sorting of returned childdren off
maxchildren maximum number of children to return info about; 0 means no limit 0
morechildren in case more than maxchildren items have been found, insert this format string to indicate that there are more (empty string)
hidenull hide children that have no leafs off
null format string to be returned in case the category or topic wasn't found (empty string)
exclude regular expression to filter out non-matching categories  
include regular expression to that matching categories must match  
matchattr attribute of a category to test exclude and include against; possible values are name and title name
matchcase boolean flag indicating the case sensitivity of the include and exclude match operation on
truncate regular expression to be removed from from the $title variable and stored in the $trunctitle variable to be used in the format string  
limit maximum number of categories to process; 0 means all 0
skip number of categories to skip while rendering results; this parameter allows to implement paging together with limit 0

The format, header and footer parameter know the following variables:

Variable Description
$breadcrumb, $breadcrumbs breadcrumb list of links to parent categories
$breadcrumbnames breadcrumb list of parent category names
$breadcrumbtitles breadcrumb list of parent category titles
$children, childrenlinks list links to children
$childrenname list of child names
$childrentitle list of child titles
$childrenurls list of child urls
$count number of categories found
$cyclic returns 0 or 1 depending on the category being part of a cycle or not
$icon url to icon representing the category
$index running number of all categories being formated
$leafs number of leaf nodes of the current category
$link link to the current category as an html anchor
$more expands to the morechildren parameter in case maxchildren has been reached
$name, $topic name of the current category
$order order of the current category
$origweb original web where the current category has been defined; this might differ from $web when part of the hierarchy including this category has been imported from another web
$parentitles list of titles of the parent categories
$parentlinks, $parent, $parents list of links to the parent categories
$parentnames list of names of the parent categories
$parenturls list of urls of the parent categories
$summary summary property of the current category
$tags tags of the current category
$title title of the current category
$trunctitle title of a category with the parent topic's title removed from the prefix if found
$url url to the currrent category
$web web where this category is being located (see also $origweb)

TAGINFO

Render tag information for a given category or topic.

Parameter Description Default
[topic] topic for which to render tag information %!BASETOPIC%
format format string to render tag information; see the list of possible variables below $title
separator format string used to separate list items =, = (coma + blank)
header header string prepended to the result (empty string)
footer footer string appended to the result (empty string)
web web of the topic, note that this might also be specified in the topic parameter %!BASEWEB%
exclude regular expressions to filter out tags  
include regular expression that tags must match to be rendered  
limit maximum number of tags to show  
skip number of tags to skip in the list of tags to be rendered  

SIMILARTOPICS

Warning: You are strongly encouraged to use %SOLRSIMILAR feature of SolrPlugin for better performance and flexibility.

Returns a list of topics that are similar to the current one. Similarity between two topics is a value expressed in percentage, where 100% means that the topics are extremely similar and 0% means that the compared topics aren't corelated at all. The similarity is computed on the base of the categorization and tagging information using a weighted matching coefficient.

Integration into query language

ClassificationPlugins adds three new operators to the query language to make use of category information in wiki applications. Note however that for now only the %DBQUERY language is supported (see DBCachePlugin).

Operator Description
cat1 SUBSUMES cat2 returns true when cat1 subsumes cat2
topic ISA cat returns true when topic is covered by cat
catOrTopic DISTANCE catOrTopic returns the distance between two categories, a category and a topic or two topics within the context of the same hierarchy; see the above definition of the %DISTANCE macro

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Dependencies

NameVersionDescription
Foswiki::Contrib::JSTreeContrib>=2.00Required
Foswiki::Contrib::NatSkin>=4.00Optional
Foswiki::Contrib::WikiWorkbenchContrib>=5.00Required
Foswiki::Plugins::BreadCrumbsPlugin>=2.0Required
Foswiki::Plugins::DBCachePlugin>=4.10Required
Foswiki::Plugins::DigestPlugin>=2.00Required
Foswiki::Plugins::FilterPlugin>=1.40Required
Foswiki::Plugins::FlexFormPlugin>=2.61Required
Foswiki::Plugins::GridLayoutPlugin>=1.00Required
Foswiki::Plugins::JQueryPlugin>=7.00Required
Foswiki::Plugins::MoreFormfieldsPlugin>=0.11Required
Foswiki::Plugins::MultiLingualPlugin>=4.10Required
Foswiki::Plugins::NatEditPlugin>=7.11Required
Foswiki::Plugins::RedDotPlugin>=4Optional
Foswiki::Plugins::RenderPlugin>=3.1Required
Foswiki::Plugins::TagCloudPlugin>=4Required
Foswiki::Plugins::WorkflowPlugin>=1.44Optional
Foswiki::Plugins::LikePlugin>=2.00Optional
Foswiki::Plugins::TopicTitlePlugin>1.00Required for Foswiki < 2.2

Change History

02 May 2019: major rewrite based on latest WikiWorkbench framework
23 Jan 2017: added support for Foswiki:Extensions/LikePlugin; added "Responsible Person" to Category topics; replace css and js inline with proper files created by AttachContentPlugin; hide the sidebar on categories by default; improvements to ControlledTopics and ClassifiedControlledTopics; added quality checks to ClassifiedTopics: missing tags, missing categories, duplicate h1; improved view template for workflow history; removed old IconSet: now using icon formfield of MoreFormfieldsPlugin; improved visualization of workflows using GraphvizPlugin; fixed WebDAV view for categorized content; some fixes for cat and tag formfields; rewrite of core code to be more oo-ish ; new REST hander updateCache to refresh the classification cache occasionally; new notification handler that lets you subscribe to any changes within a category; auto-subscribe ResponsiblePerson to its category: may be switched on/off by AUTOSCUBSCRIBE_RESPONSIBLE_PERSON preference; fixed memory leaks; implemented special ACLs to control edit rights on categories
17 Aug 2016: add support for Foswiki:Extensions/MultiLingualPlugin to make categories translatable
17 Jul 2015: add support for WikiWorkbench-3.0er new-topic creator added support; integrate workflows into classification framework; improved Open Graph support for better SEO; added multi-lingual support
03 Nov 2014: don't init core with base-web and base-topic
28 Aug 2014: new "icon" formfield from MoreFormfieldsPlugin; added virtual filesystem for WebDAVContrib based on categories; new "redirect" feature for Categories to redirect to a portal page representing this category instead of rendering the plain category view
10 Jun 2014: added options to disable some parts of a category view template; added tool to list uncategorized topics; fully specify all security switches for rest handlers
22 May 2014: fixes to Category factory; initial work on a category-based virtual filesystem for webdav
23 Apr 2014: improved topic info layout; added WebTagList; added back Clear button to category editor
04 Apr 2014: fixed compatibility with foswiki >= 1.2.0; flag rest handlers that don't require authentication
18 Mar 2014: fixed syntax error in jstree combponent (Foswiki:Main/DanieleGondoni); added sort paramteter to HIERARCHY macro; sorting all categories by title now (was by order before); fixed infinite recursion on malformed category data ; fixed hierarchy not being properly refreshed using the jstree component; fixed jstree component's way of setting the category title for a new node
11 Feb 2014: implemented sort paramenter for %HIERARCHY; protect against possible infinite recursion on mal-formed category data
13 Nov 2013: implement drag&drop interface for hierarchy widget
07 Nov 2013: rewrite of hierarchy widget using Foswiki:Extensions/JSTreeContrib; new TopicType SeoTopic
07 Jan 2013: first public releaes
30 Oct 2007: first check-in to svn
30 Oct 2006: Initial version

Topic revision: r1 - 02 May 2019, ProjectContributor
This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback