Note, Feb. 2007: I, the author of this template have multiwiki installations based on this template and JSPWiki 2.2. running. However, since the JSPWiki development has broken compatibility with 2.2 templates, this template is no longer in sync with current development. Unfortunately, while version 2.2 is not fully stable and requires nightly rebooting the server to run at all in our experience, the later versions seem even less stable under load. I am watching development and hope the problems will be fixed, to upgrade this template then.

Overview: The focus of this template is functionality, not CSS design. This template allows settings in a configuration file, so that is can be easily customized without sacrificing collaboration in fixing problems and adding new functionality. Intended as a functionally revised template, providing only minimal new CSS layout!
Please collaborate! Adding new CSS layout styles or adding more options that you need is welcome.
Authors: G. Hagedorn, A. Kohlbecker. Based on JSPWiki 2.2.28 default template, inheriting GPL of JSPWiki.
Last update 2005-09-08, tested with JSPWiki 2.2.28 under IE 6, Firefox 1.0.5.

Introduction#

The template system of JSPWiki is a great tool to customize JSPWiki. However, templates depend on the development of JSPWiki. Realistically, even old templates may no longer work, due to changes. Even in an ideal world where this is not the case (and necessary reworking/refactoring of code is sacrificed to compatibility) new features will not be supported in the old templates. Given that JSPWiki is still relatively young, incomplete, and under active development, this is a serious concern.

Many people have contributed wonderful templates but it is already rather hard to find those still usable with the current version of JSPWiki. Many templates implement great ideas, but it seems most of this effort is lost again as the main JSPWiki engine itself continues to mature.

In our own work I found that the templates lack some features we consider essential, especially support for copyright and metadata notices in view, additional help and submission notices in edit, a short header toolbox next to the search box, etc. Over time many minor fixes and enhancements were added (see ConfigurableTemplateFixedProblemsIn2228).

After a while it became clear that ultimately the template development needs to become a collaborative process to be able to pull together the best of the contributed templates. At the same time, having identified so many requirements that differ from the JSPWiki default template, it was clear that the current default template is an imperfect platform for this.

We came to the conclusion that a more flexible layout is required to support different uses and still allow collaboration in development. This design should be configurable with or without left menu, if without with added support for features currently only available through left menu, with Wiki name displayed or not, with icon/logo available in both variants, with a more flexible submission note and help system, with or without direct version comparison support of standard view, etc.

Based on the JSPWiki 2.2.28 default template, we developed the current configurable template. In addition to making the display options configurable, we found it also necessary to make page names configurable, see ConfigurableTemplatePageNaming for further discussion. See also ConfigurableTemplateDefaultPages for a proposal of pages for a clean JSPWiki install.

It is our hope that this template may find its way into the standard distribution of JSPWiki and that it may be used as a collaboration platform to continue to improve the layout and user interface options of JSPWiki.

See if you like it!

Features#

• General
  • Both a left menu and a short header tool menu (to the left of the search box) have been implemented. If left menu is disabled, the layout table implementing it is also disabled, leaving the Wiki content directly in the html body.
  • If not desired, the left menu footer source page may be disabled in the template settings.
  • The new "header tools" is intended for 1-5 short items, examples are "Home | Index | Changes | Search". Similar to the left menu, it is driven by a Wiki page and configurable by Wiki authors.
  • The following layouts are supported using a table layout:
    • Conventional left menu/right content
    • Header (image, title, tools, search) spanning full width, left menu / right content below
    • No left menu, header with content below
    • In addition, the table layout may be disabled, generating the same elements to be positioned through CSS (not tested, provided as an option for those preferring this layout).

• Page View
  • Breadcrumbs may be shown in the classical place (top of page), at the very bottom (preferred by us, because relatively rarely used tool), or not at all.
  • In page view the footer area has been expanded to two lines. The first contains on left revision, date, author, and on right a copyright and licensing statement. Both the short statement and the page to which it links are customizable Wiki pages.
  • The left part of the second view page footer line contains the customary Edit, Attach, and More info links.
  • In addition, a short cut to the page revision history (showing a configurable number of revisions with ">" between, the ">" linking to a diff of neighboring revisions. Example: "History: > 9 > 8 > 7". The feature can be completely disabled, of course.
  • The right side of the view footer line contains 0 to 4 customizable links intended for meta links (Contact, Privacy, Legal, Disclaimer, Impressum, JSPWiki version). For each of these links the label, the title (displayed as popup tool tip) and the page can be freely configured.
  • A parallel set of 4 meta links is implemented in the bottom of the left menu. The view meta items and the left menu meta items can be independently configured.
    • In our default setup, the JSPWiki version links to a modified WikiSystemInfo page, which also acknowledges the JSPWiki development and links to JSPWiki.org. Currently in JSPWiki 2.2.28, SystemInfo is linked behind the Wiki logo. This is appropriate on JSPWiki.org but not on content Wikis. In our setup, the Wiki title and logo link to an About page instead.

• Page Edit
  • The main text area height automatically scales to window height when opening an edit window. This is implemented through JavaScript in a way, that if it does not work or if JavaScript is disabled, no harm is done. Please report any problems with other browsers!
  • A signature template (user Name and editing date) is provided. This is considered a very important feature (note how difficult it is to assess the relevance of many discussions on JSPWiki because no dates or JSPWiki version numbers are indicated). The signature template may either be manually copied using clipboard functions, or, a JavaScript function inserts the text at the current position in the editor. The latter requires JavaScript to be enabled and works well only with IE or Gecko-based browser such as Mozilla or Firefox.
  • On the editor the current formatting help is replaced with a short text message and supplemented with a submission message, informing contributors about consequences of their submission (licensed und CC, GPL, etc.) Both pages are Wiki pages that may freely be edited. Both messages can be disabled.
  • On the bottom of editor, the footer contains 0 to 4 links opening in new windows. These links (again: label, title, page) can be used to provide help pages without luring the content editor away from the editing page.

• Preview
  • The Preview window now displays an edit area below the preview. The user may make additional changes (e.g. directly escape erroneous links or fix markup) before either saving finally, or returning to the main editor.
  • As a collateral, an additional "Refresh Preview" button is added.

• Page Info and Attachments
  • The missing functionality to display the list of referring pages if no left menu was used is added. Two options are implemented:
    • In the bottom of page view, REFBY_IN_PAGE_VIEW_MAX defines the number of back links shown, setting to 0 disables.
    • Referring pages have been added to PageInfo (link "More info ...).
    • A new action button Ref-By may be enabled in the bottom of page view. It leads to PageInfo shown in a special mode only showing attachments.
  • In general PageInfo has been reworked to show all available page information. That included adding attachments. Further the rename form from the next release has already been added (hoping for the implementation to arrive).
  • History table slightly changed to make available version comparisons more transparent to users.
  • The attachment list has been emended with date and author of attachment to the list. In the current setup it is very difficult to assess the relevance of an attachment, because no date is shown.
  • The attachment list is also added to editor; here often an attachment shall be included in the text and it is helpful to have the name available.

Screenshots#

Workbench layout without left menu#

Top: The Wiki name ("From Lias Glossary") may optionally displayed to identify the Wiki web (important in multi-Wikis), the header contains a short tool list of links (based on a Wiki page). Bottom: The Top of page link is displayed as graphic, next a full revision / authorship / date info. Right side of first line contains copyright and license info (based on two Wiki pages). The second line contains the conventional (here slightly abbreviated) links for "Edit", "Attach", "More", plus new links for "Ref-by" (displaying referring pages if not shown at bottom of page) and "History". Both revision numbers and ">" are links, pointing to version pages and diff-comparisons, respectively. History is automatically suppressed for first version, the max. number of directly shown revisions is configurable. The breadcrumbs trail is at the end here (configurable to be top, bottom, or none).

The display of the JSPWiki logo and displaying all four metadata links is shown only for this example, our actual setup is slightly smaller.

If desired (and in absence of a left menu), the list of referring pages may also be configured to be shown in bottom of page view. In our preferred setup it is visible only after clicking the "Ref-by" link.

The header tools and also the Find present in standard JSPWiki 2.2.28 default template are removed to avoid luring the user away from her/his editing. Buttons below editing area are standard. New is a signature template, with js enabled clicking on it automatically copies to current position in editor. Below a new submission notice and a reworked editing help. At the bottom 3 of 4 possible help links are displayed. These open in new windows, again to avoid disrupting editing process.

This is a standard view page. New is the ability to directly fix minor changes (and refresh the preview). The messages have been slightly modified.

This page is shown when clicking on the "History" link in page view. The display of the history table has been slightly changed to make the available version comparisons more transparent to users. Further suggestions are most welcome! Technically, the page is in fact a section of the PageInfo page, a parameter is passed to this page to limit display to one section. Similarly, PageInfo displays only referring pages when called from the "Ref-By" link on view. The full display of PageInfo is shown when opening it with the "More" link.

JSPWiki default layout, with left menu#

The configurable template, with settings that make it relatively similar to the classical JSPWiki 2.2 default template. The similarity could be increased even further by changing more CSS styles back to their original setting. The left menu has been turned on, Wiki name display turned off, Header tools turned off, Action link labels at the bottom reverted to their original values.

Known problems:#

• When a user starts with the Wiki, the Breadcrumbs feature displays "Your trail: " with nothing following. Does anybody have a solution to suppress the label if the trail is empty? My java knowledge is insufficient to obtain this information from looking at the code behind the custom tag. Problem is also present in the JSPWiki default template.
• The display of attachments on the primary view page may or may not be desirable (the latter especially for images used in a page). TWiki has an excellent solution, offering during upload an option to "hide" attachments. These are visible on page info and attachments pages, but not in normal page view. However, this is a major functionality addition to the Wiki engine, not solvable in the template.
  
  • One template idea is to use JavaScript. If js is disabled, the attachments are shown as currently. If it is enabled, they are initially hidden, and displayed only on request.
• Changing the settings file may not have an immediate effect and may require a restart of the JSP container (Tomcat, etc.). We experience this problem both with the JSPWiki.properties file and with files included into the primary (*Template.jsp) template files. Tomcat seems to recognize only certain changes. One change that is bound to initialize a template recompilation is to update the date of ViewTemplate.jsp, e.g. by adding/removing a blank in a comment and saving.

Note: As with any development, the testing has occurred in the context of our expected usage. We have no Left menu (but testing looks ok), and we have a separate user system, so login or preferences are not used. Please add your experience here:

-- Gregor Hagedorn and Andreas Kohlbecker, 2005-09-08

Discussion/Comments#

Making the template configurable makes it more complicated. However, we believe it could be a great collaboration platform. What do you think?

Much of the configuration is achieved with direct use of jsp-java code fragments. I actually find this quite useful, since the separation between productive code in html and custom wiki:tags and configuration code is nicely visible. I have no problems if others would like to rework this through new custom tags, though. (The current include ~i_HistoryFooter.jsp should, however, definitely ultimately be turned into a custom tag.)

Similarly, I am aware that the use of a flat list of variables is somewhat crude. It is however, relatively simple to understand and inserting the values in the actual templates is short and readable. Any insight on how to code this better is very welcome!

A general code review or proposals to replace unintuitive variable names is highly welcome!

Aside 1: the page names belong into the properties file, and are there. However, the template settings should not go into a properties file. It should be possible to share a single template by many Wikis. Furthermore, the design of ConfigurableTemplate is such that it is intended to be copied into multiple template folders with different settings. Maybe the template should be called PolymorphicTemplate?

Aside 2: With regard to property files: Any chance of giving us 2 property files for each Wiki, which are simply read one after another? This would allow us to keep the settings common to all Wiki Webs on our server in a single place (90% of property file!) and have separate files only for the specific settings.

One feature of the ConfigurableTemplate is that the JSP files are better commented, partly explicitly, partly simply through the expressions involving the settings variables. It is hoped that this somewhat offsets the added complexity - not for those knowing the current 2.2.28 default by heart, but for those new to them.

-- Gregor Hagedorn, 2005-09-08

Category: CategoryTemplates

Typo-Bug: in ConfigurableTemplage-2.2.2-beta symptom: file/page not found for SIDEMENUContent
solution: in file EditTemplate.jsp and ViewTemplate.jsp replace SIDEMENUContent.jsp with SideMenuContent.jsp

--Burkhard Buelte, 07-May-2006