The [CategoryAndArchiveExtensions] allow using categories and archives in a Wiki.

! Download
[wikiarchive-0_3.zip|http://www.jensgulden.de/download/wikiarchive-0_3.zip]

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 {{''~CategoryName''Initial}}, 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 {{''~CategoryName''~EditInfo}}, 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

[screenshot1.png]

[screenshot2.png]

! 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|http://mozart.flp.cs.tu-berlin.de/wiki/attach/Gulden06e/Gulden06e-ScienceInTheWiki-slides.PDF] shown on the [WikiSym06|http://www.wikisym.org/ws2006/] / [Hypertext06|http://www.ht06.org/] conference in Odense, DK, 2006-08-23
* [OOoBibSync|http://mozart.flp.cs.tu-berlin.de/wiki/Wiki.jsp?page=OOoBibSync]

-- [JensGulden]