Changing Annotate's look and feel

Output modes

Annotate can display annotations in different ways. The administrator can choose a default output mode (using the DefaultOutputMode option). Additionally, the visitor can change the output mode for a document.

Currently, the following output modes are available:

  • Using the inline mode, Annotate displays annotations within the annotated document, right after the annotated part.

  • In link mode, Annotate generates links after annotated parts. Annotations are displayed in a pop-up window after a click on these links.

  • In hide mode, Annotate hides annotations completely, thus only showing the DocBook document itself.

Templates

The output produced by Annotate consists of two parts: the HTML document (i.e., the output of the XSLT processor) and the additional parts generated by Annotate (i.e., annotations, control elements, and entry forms). While former can be configured by changing options in the DocBook XSL style sheets, the latter can be customized by changing templates. There are a number of control elements which can be changed, each of which is configured by a different template. Annotate looks for templates in the directory given by TemplateRoot (default: templates/).

Table 2.1. Annotate HTML templates

template name in annotate.confdefault filepurpose
NavigationTemplatenavigation.tplgenerates Annotate's navigation elements such as the output mode selector
LinkTemplatelinks.tplgenerates links for each annotatable element (to view, delete and add annotations)
AnnotateTemplateannotate.tplgenerates an annotation form for a new annotation
ViewTemplateview.tpldisplays the annotations for an annotated element
MailTemplatemail.tplgenerates a notification mail, see the section called “eMail notification”
LoginTemplatelogin.tplgenerates the login page to the administration mode

The templates contain the HTML code needed to generate certain parts of Annotate's output (e.g., the list of annotations for a paragraph). Although HTML code should be well-formed (in XML terms), a template should not be a valid HMTL document (i.e., it does not need <html> and <body> tags).

Within the templates, there are some variables (or placeholders) which Annotate fills with dynamically computed values. Annotate uses the HTML::Template module to process templates, therefore they have to conform to the syntax documented in the documentation of HTML::Template. The following table describes the valid placeholders for every template:

Table 2.2. Annotate template placeholders

placeholder namevalid for templatespurpose
CONTENTAnnotateTemplateThe annotatable part selected for a new annotation (i.e., the HTML code enclosed by <annotate> and </annotate>).
NAMEAnnotateTemplate, MailTemplate, ViewTemplateThe name of the visitor
EMAILAnnotateTemplate, MailTemplate, ViewTemplateThe mail address of the visitor
COMMENTMailTemplate, ViewTemplateThe visitor's annotation
NODE_IDAnnotateTemplate, MailTemplateThe annotated (current) Node-ID
NUM_COMMENTSLinkTemplateThe number of annotations for the current node
MORETHANONELinkTemplateThis placeholder evaluates to true if there are at least two annotations for the current node
ANNOTATE_URLLinkTemplateThe address of a new entry form for the current node
VIEW_URLLinkTemplateThe address to view the annotations of the current node (in "Link" mode)
HIDENavigationTemplateThe address to switch to "Hide" mode
LINKNavigationTemplateThe address to switch to "Link" mode
INLINENavigationTemplateThe address to switch to "Inline" mode
ADMIN_MODEViewTemplateEvaluates to true if Annotate is working in administration mode

eMail notification

Annotate is able to send an eMail whenever a visitor adds a new annotation to your document. If you set the eMailAddress option to a valid mail address, Annotate will send mails to this address. You can enter more than one address, separated by comma. You can also configure the subject of the notification mail with the eMailSubject option.

Furthermore, you can customize the contents of the notification mail by changing the MailTemplate template. By default, it can be found in mail.tpl which resides in the templates subdirectory. The placeholders valid for this template can be found in Table 2.2, “Annotate template placeholders”.

The mail template uses the same HTML::Template syntax as Annotate's HTML templates (see the section called “Templates” for details).

In order to send out mail, Annotate uses the MIME::Lite module with default settings. These should work "out of the box" on most systems.