Comments can be used to mark content within a template that should be ignored and therefore won’t appear in the generated document.
Comments are useful for:
- Embedding notes and explanations in a template.
- Disabling sections of templates temporarily to assist development.
Comment basics
Comment syntax and behaviour
A comment is created using one of the following pairs of delimiters:
- <<## ##>>
- <</* */>>
If a comment appears anywhere within a paragraph, even if there is preceding or trailing static content, the entire paragraph including all static content is removed.
Formatting comments
Comments can be formatted to appear less prominent than surrounding elements so they do not distract from the document's overall look and feel.
In the example template the second comment uses a smaller light grey font.
Using comments
The primary reason to use comments is to include notes and explanations in a template that will be helpful to future template authors, but they can also be use in other ways.
Debugging templates
Comments can be used to temporarily disable parts of a template, making them useful for debugging during template development.
Any content wrapped within the opening and closing comment delimiters, including static text and fields, is ignored and excluded from the final document.
Docmosis provides two distinct comment delimiters pairs, which making it is possible to put a comment around a section of a template which already contains other comments.
TIP: This final comment block contains a broken conditional section that Docmosis would normally consider an error. However, because it appears inside a pair of comment delimiters, all the content is ignored.
Creating a declarations page
A declarations page can be created at the start of a template. This page can be used to add explanations for future template authors, perform calculations and define variables that can be used later in the template.
If the page is structured correctly none of the declarations will appear in the generated document, and the document will effectively start from the second page of the template.
To create a declarations page:
- Ensure that all content on the first page of a template is made up of comments, logic/calculations and variable declarations.
- Insert an opening comment delimiter at the end of the declarations page.
- Insert a page break.
- Insert a closing comment delimiter.
The page break will be removed along with all the other content on the first page.
The Example Template - Insurance Certificate discusses creating a declarations page.
