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 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. comments, 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 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 comments) |
AnnotateTemplate | annotate.tpl | generates an annotation form for a new comment |
ViewTemplate | view.tpl | displays the comments 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 comments 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 comment (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 comment |
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 comments 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.