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