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.
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.
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.conf | default file | purpose |
---|---|---|
NavigationTemplate | navigation.tpl | generates Annotate's navigation elements such as the output mode selector |
LinkTemplate | links.tpl | generates links for each annotatable element (to view, delete and add annotations) |
AnnotateTemplate | annotate.tpl | generates an annotation form for a new annotation |
ViewTemplate | view.tpl | displays the annotations for an annotated element |
MailTemplate | mail.tpl | generates a notification mail, see the section called “eMail notification” |
LoginTemplate | login.tpl | generates 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 name | valid for templates | purpose |
---|---|---|
CONTENT | AnnotateTemplate | The annotatable part selected for a new annotation (i.e.,
the HTML code enclosed by
<annotate> and
</annotate> ). |
NAME | AnnotateTemplate, MailTemplate,
ViewTemplate | The name of the visitor |
EMAIL | AnnotateTemplate, MailTemplate,
ViewTemplate | The mail address of the visitor |
COMMENT | MailTemplate, ViewTemplate | The visitor's annotation |
NODE_ID | AnnotateTemplate,
MailTemplate | The annotated (current) Node-ID |
NUM_COMMENTS | LinkTemplate | The number of annotations for the current node |
MORETHANONE | LinkTemplate | This placeholder evaluates to true
if there are at least two annotations for the current node
|
ANNOTATE_URL | LinkTemplate | The address of a new entry form for the current node |
VIEW_URL | LinkTemplate | The address to view the annotations of the current node (in "Link" mode) |
HIDE | NavigationTemplate | The address to switch to "Hide" mode |
LINK | NavigationTemplate | The address to switch to "Link" mode |
INLINE | NavigationTemplate | The address to switch to "Inline" mode |
ADMIN_MODE | ViewTemplate | Evaluates to true if Annotate is
working in administration mode |
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.