Customize Documentation Templates

Colectica provides a powerful template engine that lets you completely customize the content and style of your generated documentation. The Generate Documentation dialog lets you choose a custom template in its Formats tab.

The templates you can choose from are located on your file system in %programdata%\Algenta\Colectica\Templates.

If you paste the above path into Windows Explorer, it will expand to something like C:\ProgramData\Algenta\Colectica\Templates.

Colectica automatically installs a template named Sample for you. You can copy the Sample directory to make your own template. The name of the directory is the name that will be displayed in the Generate Documentation dialog when selecting a template.

Template Files

Within each template directory is one or more text files that define the template.

File Description
Master.txt The overall layout of the documentation in HTML format. Includes the opening and closing <html> and <body> tags.
Helpers.txt Includes a number of reusable helper methods that can be used in any of the files below.
Item Name.txt Each of these files provides a template for the item type indicated by the file’s name.
Questionnaire.txt The template used for a survey instrument’s Generate Paper Form command.

These files override the default template that Colectica uses when no custom templates are provided. You do not need to provide every file to make your own template. If you omit any of the files, Colectica’s default template will be used. This means if you only want to change the format of a Variable’s documentation, for example, you would only need to provide the Variable.txt file in your template directory.

If you include a subdirectory named files/ within your template directory, all the files in the subdirectory can be referenced in your template and will be copied to the documentation output location if HTML documentation is generated. This means you can include custom CSS and images in your custom templates.

Template Format

Each template file uses Microsoft’s Razor template format, which is a combination of HTML and C#.

A master.txt template may look like this sample:

<!DOCTYPE html>

<html>
    <head>
        <title>Documentation</title>
        <link rel="stylesheet" title="Default" href="files/styles.css" type="text/css" />
    </head>
    <body>
        <div class="page">
            <div id="content">@AddMainContent()</div>
        </div>
    </body>
</html>

This is basically just HTML, but with some special items added. For example, the @AddMainContent() indicates that the main information being generated will be placed in that location. In Razor, when something begins with the “@” symbol, it indicates a transition to C# code.

Helper Methods

Colectica provides the following helper methods that you can call from your templates using the @ syntax.

Add Items

Method Description
@AddMainContent() Adds the main content for the documentation. Only useful in master.txt.
@AddItem(item) Adds documentation for the provided item using the template with the same name as the item type. For example, @__AddItem(variable)__ will add the content for the variable using the _Variable.txt_ template.
@AddItem(templateName, item) Adds documentation for the provided item, using a custom template. For example, _@AddItem(variable, “Custom”)_ will add the content for the variable using the _custom.txt_ template.

Formatting

Method Description
@AddBodyText(text) Adds text to the documentation. This method takes care of formatting any XHTML and other processing.
@AddKeyValue(key, value) Adds a key and value to the documentation. If no value is present, nothing will be written.
@AddHeaderedText(header, text) Adds text with a header on top. If no text is present, nothing will be written.

Content Helpers

Method Description
@AddCitation(citation) Adds Dublin Core citation information to the documentation.
@AddDescriptiveInformation(item) Adds general descriptive information to the documentation. This includes the item’s name, label, and description.
@AddVersionableInformation(item) Adds an item’s UserIDs, CustomFields, and OtherMaterials to the documentation.
@AddOtherMaterials(otherMaterialsList, header) Adds a list of OtherMaterials to the documentation.
@AddCoverage(coverage) Adds Coverage information to the documentation. Coverage can be found in StudyUnits, Series, DataCollection, and elsewhere.

Headers and Indentation

Method Description
@AddHeaderWithImage(item) Adds a header for the item, and includes the item type’s image in the header.
@AddHeader(header) Adds a header to the documentation.
@IncreaseHeaderLevel() Increases the header level of any subsequent headers. This should generally be called after __@AddHeader__, so any subsequent headers are written as children of the last header. This helps create a document hierarchy.
@DecreaseHeaderLevel() Decreases the current header level. A call to this should match every _@IncreaseHeaderLevel()_ call.
@IncreaseIndentLevel() Increases the indent level of any subsequent text.
@DecreaseIndentLevel() Decreases the indent level of any subsequent text.
@AddPageBreak() Inserts a page break in PDF or RTF output

Custom Styles with CSS

To adjust the style of your documentation, you can include custom Cascading Style Sheets (CSS) files. CSS is the standard way to provide styles on the Web.

The first step Colectica takes when generating your documentation is to create an HTML document by processing your template. The HTML documentation can use all features of CSS.

After HTML documentation is generated, it is converted to PDF and RTF, if desired. These formats use a subset of the information in your CSS files. The CSS properties used for PDF and RTF formats include:

  • font-family
  • font-size
  • color
  • weight
  • font-style
  • text-decoration

To specify font sizes, use pixels (e.g., “12px”).

To specify colors, use RGB (e.g., “#00FF00” instead of “Green”).

Conditional Statements, Loops, and Other Code

In addition to the helper methods described above, the Razor template system allows you to perform any action that is possible from general C# code. This includes conditional statements, looping, and much more.

See also

For a general introduction to Razor, please see http://www.w3schools.com/aspnet/razor_intro.asp