The CategoryAndArchiveExtensions allow using categories and archives in a Wiki.

Download

Note that in order to provide the extensions, JSPWiki's template-files require a few additions. The wikiarchive distribution contains patch-files and a script for applying these patches to the original default-templates shipped with JSPWiki 2.4.102. In order to apply the changes to other templates or different versions of the default templates, manual editing might be necessary.

Categories

A category is a page which contains other pages in the sense that

• each page belonging to the category contains at least one link to the category-page
• each page belonging to the category contains one of the member-phrases, as stored in the wiki page CategoriesMemberPhrases (or as configured via jspwiki.categories.memberPhrases.page)
• the category-page includes the plugin de.tuberlin.cs.flp.jspwiki.plugin.Category (and usually nothing more, i.e. the category-page does not contain links to its members in wiki markup, but links are displayed by the plugin)
• the category-page is linked from the central Categories page (or as configured via jspwiki.categories.page)

With each category, 2 helper pages are associated: a page CategoryNameInitial, which may contain an initial empty page template that will be preset in the editor when a new page is added as member to the corresponding category, and CategoryNameEditInfo, which may contain a category-specific help text to be displayed in an additional "edit info"-tab when a category member page is edited. See pages BibliographyArchiveInitial and BibliographyArchiveEditInfo from the examples in the distribution archive.

Archives

Archives are categories with additional features. For example, an archive may be able to

• export itself in some specific data format (e.g. the BibliographyArchive example can export itself as a BibTeX-file for later processing with a TeX-compatible application)
• display itself in some special form (e.g. the ImageGalleryArchive example displays its members by images)

Additonally, archives come with a menu integrated in the Wiki-page that makes it easier to add new entries, and optionally import or export entries.

Screenshots

Configuration

See additional configuration in jspwiki.properties:

# Administrative page linking to all available categories. This page registers all
# categories used in the wiki.
jspwiki.categories.page = Categories

# Administrative page containing valid category-member-phrases. (A category-
# member-phrase is needed to mark a page as being an element of a category
# and not just simply linking to the category-page.)
jspwiki.categories.memberPhrases.page = CategoriesMemberPhrases

# Enables availability of a menu for deleting all member-pages of a category,
# if the archive-page is invoked with the additional parameter "delete=yes".
# ! THIS IS A SECURITY RISK. ONLY SET TO TRUE IF YOU KNOW WHAT YOU'RE DOING ! 
# @see de.tuberlin.cs.flp.jspwiki.plugin.WikiArchive
jspwiki.archive.enableDelete = true

# Temporary directory used to receive uploaded archive-imports.
# @see de.tuberlin.cs.flp.jspwiki.plugin.WikiArchive
jspwiki.archive.uploadTempDir = /tmp

# Registration of different archive-types.
# @see de.tuberlin.cs.flp.jspwiki.plugin.WikiArchive
jspwiki.archive.handler.txt = de.tuberlin.cs.flp.jspwiki.plugin.wikiarchive.ArchiveHandlerPlaintext
jspwiki.archive.handler.txt.label = Text
jspwiki.archive.handler.xml = de.tuberlin.cs.flp.jspwiki.plugin.wikiarchive.ArchiveHandlerXML
jspwiki.archive.handler.xml.label = XML
jspwiki.archive.handler.bib = de.tuberlin.cs.flp.jspwiki.plugin.wikiarchive.ArchiveHandlerBibTeX
jspwiki.archive.handler.bib.label = BibTeX
jspwiki.archive.handler.bib.entries = /var/www/wiki/conf/bibliography-entries.properties
jspwiki.archive.handler.bib.types = /var/www/wiki/conf/bibliography-types.properties
jspwiki.archive.handler.bib.formats = /var/www/wiki/conf/bibliography-formats.properties

By default, the page Categories is intended to link to any page that is considered to be a category.

The page CategoriesMemberPhrases contains textual phrases which are required as being part of the content of any category member's page, together with a link back to the category page. By requiring the occurrence of a category-member-phrase, it remains possible to link to the category-page like to any other page without making the linking page a member of the category (unless the category-member-phrase will be added). This is the major advantage of the wikiarchive extension mechanism in comparison to the more simple approach of treating any page linking to a category-page as a member of that category, which causes confusion if one wants to link to the category-page from another context.

Plugins in the package

A category-page itself just contains an invocation of the CategoryPlugin:

[{Category}]

or

[{Category categoryMarker='This is a string which identifies the page as member of the [CategoryMusic].'}]

Accordingly, an archive-page contains an invocation of the WikiArchivePlugin:

[{WikiArchive headlines=alphabetic io='bib' categoryMarker='----\nThis is a bibliography entry in the [BibliographyArchive].'}]

Besides these two main plugins, the package additionally comes with three tool-plugins:

• CommentPlugin for adding invisible comments inside the Wiki markup
• FileIconPlugin for including file-icon images into a page
• PicturePlugin for including pictures with symbolic size-names ('small', 'medium', 'large') and auto-title into a page

Tags in the package

The additions to the templates are implemented on top of a few additional JSP-tags that are added to the set of tags making up JSPWiki:

• CategoryIteratorTag
• FileIconTag
• IsCategoryTag
• PageReferredByTag

See also

• Presentation slides shown on the WikiSym06 / Hypertext06 conference in Odense, DK, 2006-08-23
• OOoBibSync

-- JensGulden