Export Using Custom Templates

Documentation / Export

Table of Contents

You can create custom templates for exporting ReqView projects or documents into HTML, CSV, XML or any other structured text format.

Custom Export

To export a text file using a custom template, click File, mouseover Export and click Custom Template. In the Export Using Custom Template dialog, choose exported documents and other options. After confirmation of the dialog, select a destination for storing the exported files.

The exported files are named according to the project or document ID with the same extension as the template file (for example, SRS.html).

Note: In the WebApp, the exported files are saved in the browser download folder.

Export Options

Documents:

  • Current document — export the current document only
  • Open documents — export all open documents from the main project or loaded linked projects
  • All documents from the main project — export all documents from the main project
  • All documents from loaded projects — export all documents from the main project or loaded linked projects

Layout:

Chose an custom export template file specifying the layout and styling of exported data.

Options:

  • Export into a single file — if set then all exported documents will be merged into a single HTML file, otherwise a separate file will be created for each exported document (for Open documents and All documents options)
  • Export displayed custom attributes in a single column — if set then columns displaying custom attributes will be compacted into a single column
  • Preserve filter and sorting — if set then exported data will be filtered and sorted the same way as the table view
  • Preserve section folding — if set then content of collapsed sections will be ignored
  • Add custom export parameters – optionally add custom export parameters JSON file if used in your custom template, see exportParam helper below

Export CLI

You can export ReqView documents to HTML, CSV, XML files using reqview export custom command, see Command Line > Export Documents.

Object Model

The ReqView exporter passes an object model storing information about the exported project, documents and traceability links to the selected custom export template. Custom export templates describe how the object model is converted into a text format by means of markup text and custom helpers, see Template Helpers.

Document Properties

The exported object model contains document properties and a filtered collection of document objects sorted by the default or displayed order at the top-level:

  • docId — document identifier
  • createdOn — date of document creation
  • createdBy — document author record
    • name
    • email
    • company
  • lastChangedOn — date of the last modification
  • lastChangedBy — last modification author record
    • name
    • email
    • company
  • filter — collection of filtering criterions
    • criterion — filtering criterion definition
  • sort — document sort record
    • attribute — ID of the attributed used for sorting
    • descending — true if sort is descending
  • columns — collection of column records
    • id — the given column identifier, for example “description” or a custom attribute identifier
    • icon — icon name for the given column
    • userDefined — true if the given column is a custom attribute
    • sortAsc — true if the given column is sorted with ascending order
    • sortDesc — true if the given column is sorted with descending order

Document Objects

Each document object contains attributes, attachments, a discussion, and links:

  • id — a unique object identifier within the document
  • guid — a globally unique object identifier
  • heading — section heading
  • text — text description
  • deleted — flag set to true if object is marked as deleted
  • level — object level
  • parent — a unique identifier of the parent object within the document
  • attachments — collection of object attachments
    • name — attachment name
    • data — attachment data as base64 string
    • href — relative URL to the attachment file
    • isImage — flag if attachment is an image type
  • discussion — collection of object comments
    • date — comment date
    • author — comment author record
      • name
      • email
      • company
    • comment — comment text
  • link types — collection of object link types
    • linkTypeId — name of the link type
    • links — collection of object links with the given link type
      • id — an identifier of an object connected with the link
      • shortDescription — description of an object connected with the link
  • … and custom attributes

Template Helpers

Custom export templates have Handlebars syntax with {{ moustache }} form. You can customize templates using expressions or template helpers. Expressions are some contents enclosed by double curly braces – e.g. {{<expression>}}. Expressions in this form produce HTML escaped output. If you don’t want to escape the expression value, use the “triple-stash” form: {{{<expression>}}}.

For example, {{text}} outputs object text description with HTML escaped tags &lt;p&gt;User shall …&lt;/p&gt; while {{{text}}} outputs the object text description with the original HTML tags <p>User shall …</p>.

Whitespace (for example, line endings) in the template is preserved into the output text. If you want to trim whitespace from either side use a tilde (~) by the braces. For example, {{~expression}} removes all whitespace before the expression up to the first handlebars expression or non-whitespace character.

Handlebars define a rich set of built-in template helpers allowing you to conveniently iterate through an object structure and output object properties using expressions. The most useful of them is the predefined conditional block helper allowing you to render block content based on the result of the given expression:

{{#if expression}} … {{else}} … {{/if}}

To pass values to a helper with parameters, list the parameters after the helper name:

{{helper <value> <param>=<value> (otherHelper <value>)}}`

In addition to built-in template helpers, you can use ReqView custom template helpers (described below) that simplify access to the document data model.

Unlike the if helper mentioned above, most custom block helpers (usually named each… or with…) change the current evaluation context. Sometimes it is necessary to reach into parent context when nesting such helpers – this is done using the {{../<property>}} syntax, similar to how directory paths work.

You can reuse template code through Handlebars inline partials, see HTML Table and Book Layouts. See also HTML Traceability Matrix for an example template using inline partials recursively to output a traceability coverage across several levels.

Project Helpers

projectId

Syntax: {{projectId}}

Description: Outputs the project ID for the exported document.

eachDocument

Syntax: {{#eachDocument [separator=<string>]}} … {{/eachDocument}}

Description: Iterates all exported documents. You can optionally specify a custom separator string by separator parameter.

Example: Output list of all exported document names separated by a comma:

{{#eachDocument separator=", "}}{{docName}}{{/eachDocument}}

eachOpenDocument

Syntax: {{#eachOpenDocument [separator=<string>]}} … {{/eachOpenDocument}}

Description: Iterates all open documents when exporting into a single file. You can optionally specify a custom separator string by separator parameter.

Example: Output list of all open document names separated by a comma:

{{#eachOpenDocument separator=", "}}{{docName}}{{/eachOpenDocument}}

withDocument

Syntax: {{#withDocument <docId>}} … {{/withDocument}}

Description: Sets the child context to the document with the given ID when exporting into a single file.

Example: Output document name for ID "NEEDS":

{{#withDocument "NEEDS"}}{{docName}}{{/withDocument}}

exportOption

Syntax: {{exportOption <option>}}

Description:

  • {{exportOption "mergeDocuments"}} — outputs a non-empty string if export option Export into a single file is checked
  • {{exportOption "exportSection"}} — outputs the name of a MS Word DOCX export section, see Export Sections

exportParam

Syntax: {{exportParam <propertyPath>}}

Description: Get a value from the custom export parameters JSON file provided in the Export Options dialog or via CLI. The propertyPath argument can refer to any top-level property or a property in nested objects using the dot path notation.

Example Params File:

{
    "textParam": "foobar",
    "number": 12345,
    "boolean": true,
    "nested": {
        "abc": "foo",
        "deep": {
            "def": "bar"
        }
    },
    "array": [1, 2, "baz"]
}

Example: Get value of textParam property (“foobar“):

{{exportParam "textParam"}}

Example: Get value of deeply nested def property (“bar“):

{{exportParam "nested.deep.def"}}

Example: Get value of array property at index 2 (“baz“):

{{exportParam "array[2]"}}

Example: Iterate over the array property using the Handlebars built-in #each helper:

<ul>
{{#each (exportParam "array")}}
  <li>{{this}}</li>
{{/each}}
</ul>

Document Helpers

docName

Syntax: {{docName [docId=<string>]}}

Description: Outputs document name of the current document or a document with the given document ID.

Example: Output name of SRS document:

{{docName docId="SRS"}}

eachDocumentObject

Syntax: {{#eachDocumentObject [separator=<string>]}} … {{/eachDocumentObject}}

Description: Iterates all document objects in the exported document. You can optionally specify a custom separator string by separator parameter.

Example: Output list of document object IDs separated by a comma:

{{#eachDocumentObject separator=","}}{{id}}{{/eachDocumentObject}}

isRTL

Syntax: {{isRTL}}

Description: Check if the default text direction for the current document is RTL (right-to-left).

Example: Add appropriate dir attribute and text-align style to a heading tag containing the document name:

<h1{{#if (isRTL)}} dir="rtl" style="text-align: start;"{{/if}}>{{docName}}</h1>

Document Object Helpers

docObjId

Syntax: {{docObjId}}

Description: Outputs the object ID prefixed by the document ID.

shortDescription

Syntax: {{shortDescription [attribute=<attrId>] [maxLength=<number>]}}

Description: Outputs short text description (with stripped HTML) of a given object attribute or heading / text if attribute parameter is not provided. You can specify the maximum number of characters by optional maxLength parameter.

Example: Output object description from heading and text attributes shortened to 80 characters:

{{{shortDescription maxLength=80}}}

sectionNumber

Syntax: {{sectionNumber}}

Description: Outputs section number as a plain text, for example “1.2.3”.

isSection

Syntax: {{isSection}}

Description: Returns true if the current document object has section, i.e. has the sectionNumber.

Example:

{{#if (isSection)}}
  Section: {{sectionNumber}}
{{/if}}

section

Syntax: {{#section [numbering=<bool>] [shiftLevel=<number>]}} … {{/section}}

Description: Generates a section heading block with proper style. If its optional parameter numbering is true, then it also outputs the section number. Optional parameter shiftLevel denotes the number of heading level shift.

Example: Output the section number followed by section heading and shift level by 1 to use <h2> tag for the top level:

{{#section numbering=true shiftLevel=1}}{{heading}}{{/section}}

indentation

Syntax: {{indentation <number>}}

Description: Calculates indentation space from the object level in the document hierarchy. The argument provides the number of pixels per level.

Example: Indent a div HTML tag by 10px per level:

<div style="padding-left:{{indentation 10}}">{{shortDescription}}</div>

attributeValue

Syntax: {{attributeValue <attrId> [format="string"|"xhtml"] [inherit=true]}}

Description: Formats the value of the given document object attribute. You can optionally provide output format (default is "xhtml") and enable inheritance of attribute value from its nearest parent if it is not set.

Example: Output the text value (for example, “Implemented”) of the status custom enumeration attribute:

{{attributeValue "status"}}

Example: Output value of the text attribute converted to a plain string:

{{attributeValue "text" format="string"}}

Tip: To check if an enumeration attribute (both single- and multi-valued) value matches, use the includes helper.

lastChangedOn

Syntax: {{lastChangedOn [attrId]}}

Description: Returns the date and time of the last change of any of the document object’s attributes, or of a specified attribute when attrId is present.

Example: Output the date and time of the last attribute change of a document object:

{{lastChangedOn}}

Example: Mark an object whose status attribute was last changed on or after 18 June 2019:

{{#if (eval (lastChangedOn "status") ">=" "2019-06-18")}}<b>Changed</b>{{/if}}

eachChild

Syntax: {{#eachChild [separator=<string>]}} … {{/eachChild}}

Description: Iterates the immediate children of the current document object.

Example: Output a comma separated list of child object IDs:

{{#eachChild separator=", "~}}
  {{id}}
{{~/eachChild}}

eachAttachment

Syntax: {{#eachAttachment}} … {{/eachAttachment}}

Description: Iterates the attachments of the current document object. The child context has name, data, href and isImage properties.

Example:

{{#eachAttachment}}
  {{#if isImage}}
    <img src="{{data}}">
    <div><em>Image attachment:</em> {{name}}</div>
  {{else}}
    <div><em>File attachment:</em> {{name}}</div>
  {{/if}}
{{/eachAttachment}}

hasInlinks / hasOutlinks

Syntax: {{hasInlinks [linkTypeId]}}

Description: Returns true if the current document object has an inlink (resp. outlink). You can optionally provide a link type ID.

Example:

{{#if (hasInlinks "satisfaction")}}
  <span>OK.</span>
{{else}}
  <span>Missing satisfaction link!</span>
{{/if}}

ifHasInlinks / ifHasOutlinks

Syntax: {{#ifHasInlinks <linkTypeId>}} … {{/ifHasInlinks}}

Description: Outputs the given block if the current document object has an inlink (resp. outlink) of the given link type ID. An else block can be optionally provided.

Example:

{{#ifHasInlinks "satisfaction"}}
  <span>OK.</span>
{{else}}
  <span>Missing satisfaction link!</span>
{{/ifHasInlinks}}

countInlinks / countOutlinks

Syntax: {{countInlinks [linkTypeId]}}

Description: Returns the number of inlinks (resp. outlinks) of the current document object. You can optionally provide a link type ID.

Example:

{{countInlinks "satisfaction"}}

eachInlinkType / eachOutlinkType

Syntax: {{#eachInlinkType}} … {{/eachInlinkType}}

Description: Iterates incoming (resp. outgoing) traceability link types for the current document object.

Example:

{{#eachInlinkType}}
  <div>{{{linkTypeName}}}:</div>
  {{#eachLink}}
    <div>{{docObjId}} {{shortDescription maxLength=40}}</div>
  {{/eachLink}}
{{/eachInlinkType}}

eachInlinkWith / eachOutlinkWith

Syntax: {{#eachInlinkWith type=<typeId> [separator=<string>]}} … {{/eachInlinkWith}}

Description: Iterates incoming (resp. outgoing) traceability links of type given by type parameter. You can optionally specify a custom separator string by separator parameter. Links are sorted the same way as in the displayed table view.

Example:

{{#eachInlinkWith type="verification" separator=", "}}
  <span>{{{docObjId}}}</span>
{{/eachInlinkWith}}

withParent

Syntax: {{#withParent}} … {{/withParent}}

Description: Renders the given block with the parent document object context. The parent context is accessed even if the parent or the link to it is not visible.

Example: Get the ID of the object’s parent:

{{#withParent}}
  <div><em>Parent ID:</em> {{docObjId}}</div>
{{/withParent}}

Example: Get IDs of parents of linked objects:

{{#eachInlinkWith type="verification"}}
  {{#withParent}}
    <div><em>Parent ID of linked object:</em> {{docObjId}}</div>
  {{/withParent}}
{{/eachInlinkWith}}

withParentLink

Syntax: {{#withParentLink}} … {{/withParentLink}}

Description: Renders the given block with the parent document object context if parent links are displayed (Edit > Preferences > Show parent links).

Example:

{{#withParentLink}}
  <div><em>Parent:</em> {{docObjId}} {{shortDescription maxLength=40}}</div>
{{/withParentLink}}

hasOriginInlink / hasOriginOutlink

Syntax: {{hasOriginInlink}}

Description: Returns true if origin links are displayed (Edit > Preferences > Show origin and inherited links) and if the given document object has an incoming (resp. outgoing) origin link.

Example:

{{#if (hasOriginInlink)}}Has Copies{{/if}}
{{#if (hasOriginOutlink)}}Is Copy{{/if}}

eachOriginInlink

Syntax: {{#eachOriginInlink}} … {{/eachOriginInlink}}

Description: If origin links are displayed (Edit > Preferences > Show origin and inherited links), it iterates object’s copies.

Example:

{{#eachOriginInlink}}
  <div><em>Copy:</em> {{docObjId}} {{shortDescription maxLength=40}}</div>
{{/eachOriginInlink}}

withOriginOutlink

Syntax: {{#withOriginOutlink}} … {{/withOriginOutlink}}

Description: If origin links are displayed (Edit > Preferences > Show origin and inherited links) and the given document object is a copy, it sets child context to the original object.

Example:

{{#withOriginOutlink}}
  <div><em>Origin:</em> {{docObjId}} {{shortDescription maxLength=40}}</div>
{{/withOriginOutlink}}

Attachment Helpers

imageSize

Syntax: {{imageSize [maxWidth=<number>] [maxHeight=<number>]}}

Description: Outputs width and height attributes of <img> HTML tag describing current attachment image size. You can optionally provide maxWidth or maxHeight parameters to rescale the image.

Example:

<img alt="{{{name}}}" src="{{{data}}}" {{imageSize maxWidth=500}}/>

linkTypeName

Syntax: {{linkTypeName}}

Description: Outputs the name string of the current link type, for example “Satisfies”.

eachLink

Syntax: {{#eachInlink}} … {{/eachInlink}}

Description: Iterates traceability links of the current traceability link type for the current document object. Links are sorted the same way as in the displayed table view.

Example:

{{#eachInlinkType}}
  <div>{{{linkTypeName}}}:</div>
  {{#eachLink}}
    <div>{{docObjId}} {{shortDescription maxLength=40}}</div>
  {{/eachLink}}
{{/eachInlinkType}}

hyperlink

Syntax: {{#hyperlink}} … {{/hyperlink}}

Description: If the link source (resp. target) document is included in the HTML export, then it creates an HTML a tag around the inner block pointing to the link source (resp. target) object.

Example:

{{#hyperlink}}{{docObjId}}{{/hyperlink}}

ifSuspect

Syntax: {{#ifSuspect}} … {{/ifSuspect}}

Description: Outputs the given block if the link is suspect.

Example:

{{#ifSuspect}}!{{/ifSuspect}}

Column Helpers

eachColumn

Syntax: {{#eachColumn}} … {{/eachColumn}}

Description: Iterates displayed columns of the Requirements Table.

eachDisplayedCustomAttribute

Syntax: {{#eachDisplayedCustomAttribute}} … {{/eachDisplayedCustomAttribute}}

Description: Iterates attributes displayed in the Custom Attributes column and sets context id, name, value, and rawValue properties to attribute ID, name, and formatted (resp. unformatted) value.

Example:

{{#eachDisplayedCustomAttribute}}
  {{#if value}}
  <div class="attribute">
    <span>{{{name}}}:</span> <span>{{{value}}}</span>
  </div>
  {{/if}}
{{/eachDisplayedCustomAttribute}}

columnId

Syntax: {{columnId}}

Description: Outputs column ID, for example “description”.

Example:

<tr>
{{#eachColumn}}
  <th>{{columnId}}</th>
{{/eachColumn}}
</tr>

columnName

Syntax: {{columnName [<colId>]}}

Description: Outputs column name of the current column in eachColumn context or name of the given column if colId argument is provided.

Example:

<tr>
{{#each columns}}
  <th><strong>{{columnName id}}{{#if sortAsc}}&#x25B2;{{/if}}{{#if sortDesc}}&#x25BC;{{/if}}</strong></th>
{{/each}}
</tr>

isColumn

Syntax: {{isColumn <colId>}}

Description: Returns true if the current column matches the given column ID.

Example:

<tr>
{{#eachColumn}}
  {{#if (isColumn "id")}}
    <td><a id="{{id}}"></a>{{docObjId}}</td>
  {{/if}}
{{/eachColumn}}
</tr>

isTemplateColumn

Syntax: {{isTemplateColumn}}

Description: Returns true if the current column is a template column.

columnAttributeValue

Syntax: {{columnAttributeValue [format="string"|"xhtml"]}}

Description: Outputs value of the attribute corresponding to the current column. You can optionally provide output format (default is "xhtml").

Example: Output the value of the current attribute in XHTML format:

{{columnAttributeValue}}

Example: Output the value of the current attribute converted to a plain string:

{{columnAttributeValue format="string"}}

templateColumnValue

Syntax: {{templateColumnValue}}

Description: Outputs value of the current template column.

Note: Scope of variables declared inside the template column is limited to this helper.

Example:

<tr>
{{#eachColumn}}
  {{#if (isTemplateColumn)}}
    <td>{{{templateColumnValue (columnId)}}}</td>
  {{/if}}
{{/eachColumn}}
</tr>

Formatting Helpers

formatString

Syntax: {{formatString <string> [maxLength=<number>] [newlines=<bool>] [case="firstLower"|"allLower"|"firstUpper"|"allUpper"] [locale=<string>]}}

Description: Formats a value as a string (strips HTML tags). You can optionally provide the maxLength parameter with a maximum number of string characters. If the optional parameter newlines is true, then all p, li and br end tags are replaced by line feed (\n, 0x0A) characters. The optional case parameter allows case conversion of the first or all characters in the string to lower or upper case. To get the correct lower or upper case of language-specific characters, you can optionally use a IETF BCP 47 language tag as the locale argument.

Example: Strip HTML from the text attribute and limit the result’s length to 20 characters:

{{{formatString text maxLength=20}}}

Example: Convert the first letter of “istanbul” to upper case, passing in the Turkish locale to get the correct output “İstanbul”:

{{formatString "istanbul" case="firstUpper" locale="tr"}}

formatJSONString

Syntax: {{formatJSONString <string>}}

Description: Formats a string value as a JSON string.

formatXHTML

Syntax: {{formatXHTML <string> [paragraphClass=<string>] [charClass=<string>]}}

Description: Formats a value as XHTML. You can optionally provide paragraphClass parameter with a paragraph class name for p or div tags or charClass parameter with an inline class name for span tag.

Example:

<div><b>Description</b>:</div>
<div>{{{formatXHTML text charClass="attrValueChar" paragraphClass="attrValuePar"}}}</div>

formatPrefixedXHTML

Syntax: {{#formatPrefixedXHTML <string> [paragraphClass=<string>] [charClass=<string>]}} … {{/formatPrefixedXHTML}}

Description: Formats a value as XHTML with a custom prefix given by the child block. You can optionally provide paragraphClass parameter with a paragraph class name for p or div tags or charClass parameter with an inline class name for span tag.

Example: Output value of text attribute of the current document object. If heading attribute is not set, then insert the document object ID at the start of the first paragraph.

{{#formatPrefixedXHTML text paragraphClass="text"}}
  {{#unless heading}}<span>[{{docObjId}}]</span>{{/unless}}
{{/formatPrefixedXHTML}}

formatDate

Syntax: {{formatDate [<date>]}}

Description: Formats a date value (ISO 8601) using “YYYY-MM-DD” format, for example “2015-09-01”. Outputs the current date if no parameter is provided.

formatTime

Syntax: {{formatTime [<date>]}}

Description: Formats a time value (ISO 8601) using "hh:mm" format, for example "16:00". Outputs the current time if no parameter is provided.

formatDateTime

Syntax: {{formatDateTime [<date>]}}

Description: Formats a date/time value (ISO 8601) using "YYYY-MM-DD hh:mm" format, for example "2015-09-01 16:00". Outputs the current date and time if no parameter is provided.

formatURIComponent

Syntax: {{formatURIComponent <string>}}

Description: Formats a URI by escaping reserved characters their UTF-8 encoding.

CSV Output Helpers

csvSeparator

Syntax: {{csvSeparator}}

Description: Outputs CSV separator set in the Preferences dialog.

formatCSVColumn

Syntax: {{formatCSVColumn <value>}}

Description: Formats given value as a CSV column (escapes double quotes, line ends, etc.).

Example:

{{formatCSVColumn id}}{{csvSeparator}}{{formatCSVColumn text}}

formatBlockCSVColumn

Syntax: {{#formatBlockCSVColumn}} … {{/formatBlockCSVColumn}}

Description: Formats given value as a CSV column (escapes double quotes, line ends, etc.).

Example: Output IDs of all document objects linked to the current document object with verification link type.

{{~#formatBlockCSVColumn}}
{{~#eachInlinkWith type="verification" separator=" "}}{{docObjId}}{{/eachInlinkWith}}
{{~/formatBlockCSVColumn}}

formatAttributeCSVColumn

Syntax: {{formatAttributeCSVColumn <attrId>}}

Description: Formats value of the given document object attribute as a CSV column.

Example: Output CSV value of heading system attribute:

{{formatAttributeCSVColumn "heading"}}

formatSystemAttributeCSVColumn

Syntax: {{formatSystemAttributeCSVColumn <attrId>}}

Description: Formats value of the given document object system attribute as a CSV column.

formatCustomAttributeCSVColumn

Syntax: {{formatCustomAttributeCSVColumn <attrId>}}

Description: Formats value of the given document object custom attribute as a CSV column.

Expressions Helpers

Binary Operators

eval

Syntax: {{eval <lvalue> <operator> <rvalue>}}

Description: Evaluates an expression given by three arguments — left value, binary operator and right value. The binary operator can be + (add), - (subtract), * (multiply), / (divide), == (equal), != (not equal), < (less), <= (less or equal), > (greater), >= (greater or equal), && (logical and), || (logical or).

Example: Multiply value of severity, probability and detectability attributes in project risks document:

{{eval (eval severity "*" probability) "*" detectability}}

Example: Display warning if document object type attribute is set to “Req” and the document object has no incoming link:

{{#if (eval type "==" "Req") }}
  {{#unless (hasInlinks)}}
    <div><b>Warning:</b> Missing incoming link!</div>
  {{/unless}}
{{/if}}

Logical Expressions

and

Syntax: {{and <value 1> <value 2> … }}

Description: Evaluates logical and for two or more given arguments.

Example: Display names of all document object attachments. For each image attachments with href property set display also the image.

{{#eachAttachment}}
  <p><em>Attachment:</em> {{{name}}}</p>
  {{#if (and isImage href)}}<img src="{{href}}" {{imageSize maxWidth=600}}>{{/if}}
{{/eachAttachment}}

or

Syntax: {{or <value 1> <value 2> … }}

Description: Evaluates logical or for two or more given arguments.

Example: Output the full user story text created from asAn, iWant and soThat custom attributes for all document objects, which are user stories or constraints.

{{#if (or (eval type "==" "STORY") (eval type "==" "CON"))}}
<p>
  <strong>[{{docObjId}}]</strong>
  <em>As a(n)</em> {{asAn}}
  <em>I want to</em> {{formatString iWant}}
  <em>so that</em> {{formatString soThat}}.
</p>
{{/if}}

not

Syntax: {{not <value>}}

Description: Evaluates logical not for the given argument.

Example: Output the document object ID as the prefix of the text description for all document objects with text attribute set or without any children.

{{#formatPrefixedXHTML text}}
{{#if (or text (not child))}}[{{docObjId}}]{{/if}}
{{/formatPrefixedXHTML}}

ifEqual

Syntax: {{#ifEqual <value> <value>}} … {{/ifEqual}}

Description: Compares two arguments and outputs the block only if both arguments are equal.

Example: Output document object ID only if value of type attribute equals to “Req” string:

{{#ifEqual type "Req"}}<span>{{docObjId}}</span>{{/ifEqual}}

Variables

var

Syntax: {{var <varId> <value>}}

Description: Declares a variable with the given ID and sets its initial value.

Example:

{{var "x" 0}}

set

Syntax: {{set <varId> <value>}}

Description: Sets the given variable to the given value. The value should be of the same type as the initial value.

Example: Set value of variable x to the value of custom attribute estimate:

{{set "x" estimate}}

get

Syntax: {{get <varId>}}

Description: Outputs value of the variable with the given name. The helper can also be used to retrieve array contents when using the #each block helper, see push helper for an example.

Example: Output the initial value of variable x which is 0:

{{var "x" 0}}
<div>x={{get "x"}}</div>

incr

Syntax: {{incr <varId>}}

Description: Increments value of the given number variable.

Example: Count number of document objects in c variable:

{{var "c" 0}}
{{eachDocumentObject}}{{incr "c"}}{{/eachDocumentObject}}
<div><b>Count:</b> {{get "c"}}</div>

decr

Syntax: {{decr <varId>}}

Description: Decrements value of the given number variable.

Arrays and Maps

array

Syntax: {{array <arrayId>}}

Description: Declares an array with the given ID.

Example:

{{array "x"}}

map

Syntax: {{map <mapId>}}

Description: Declares a map (key-value store) with the given ID. Maps can also be used to emulate sets (collections of unique elements).

Example:

{{map "x"}}

setElement

Syntax: {{setElement <arrayOrMapId> <element> <value>}}

Description: Sets the value of an element of an array or a map with the given name to the given value; element must be a string or a number and arrayOrMapId must be an array or map variable.

Example: Add/set the value of map x element with the key given by output of docObjId helper (e.g. "SRS-123") to the value of document object attribute text:

{{setElement "x" (docObjId) text}}

Note that docObjId is a template helper and must be enclosed in brackets.

Example: Add/set the element at index 0 of array x to the value of document object attribute text:

{{setElement "x" 0 text}}

getElement

Syntax: {{getElement <arrayOrMapId> <element>}}

Description: Outputs the value of an element of an array or a map with the given name; element must be a string or a number and arrayOrMapId must be an array or map variable.

Example: Set the element of map x with key “id” to string “NEEDS-123” and then output the formatted value string:

{{map "x"}}
{{setElement "x" "id" "NEEDS-123"}}
<div>x.id={{getElement "x" "id"}}</div>

Example: Set the element of array x at index 0 to string “NEEDS-123” and then output the formatted value string:

{{array "x"}}
{{setElement "x" 0 "NEEDS-123"}}
<div>x[0]={{getElement "x" 0}}</div>

deleteElement

Syntax: {{deleteElement <arrayOrMapId> <element>}}

Description: Deletes the given element of the given array or map. When used with a map, the element must be a valid key of the map. When used with an array, the element can also be negative to allow indexing from the end of the array (the last element is at index -1).

Example: Delete the element with key docObjId from map x:

{{deleteElement "x" (docObjId)}}

Example: Delete the first element from array x:

{{deleteElement "x" 0}}

Example: Delete the last element from array x:

{{deleteElement "x" -1}}

push

Syntax: {{push <arrayId> <value>}}

Description: Adds the given value to the end of the given array.

Example: Output all elements of array x together with their indices:

{{array "x"}}
{{push "x" "value"}}{{push "x" "value 2"}}
<div>{{#each (get "x")}}{{@index}}: {{this}}<br />{{/each}}</div>

pop

Syntax: {{pop <arrayId>}}

Description: Removes the last element from an array and returns that element.

Example: Remove and output the last element from array x:

{{pop "x"}}

Tip: To delete the last element without output, use the deleteElement helper with -1 as the element parameter.

size

Syntax: {{size <arrayOrMapId>}}

Description: Retrieves the size of the given array or map variable.

Example: Output the length of array or map x:

{{size "x"}}

clear

Syntax: {{clear <arrayOrMapId>}}

Description: Clears the contents of the given array or map variable.

Example: Clear map or array x:

{{clear "x"}}

includes

Syntax: {{includes <name> <value>}}

Description: Checks if an array includes a value, a map has a key or if an enumeration attribute (both single- and multi-valued) value matches. The name argument must be a name of an array or a map variable, or a name of an enum attribute in the current context.

Example: Print a note if multi-valued enumeration attribute components value includes “Server” component:

{{#if (includes "components" "Server")}}
  Server component supported
{{/if}}

Example: Output a warning if map verLinks does not contain an element with the key given by output of docObjId helper:

{{#unless (includes "verLinks" (docObjId))}}
  <div><b>Warning:</b> Missing verification link!</div>
{{/unless}}

sort

Syntax: {{sort <arrayOrMapId> [sortByValue=<bool>] [locale=<string>]}}

Description: Returns a sorted copy of an array or map. The sorting algorithm is case-insensitive, diacritics-sensitive and sorts by numerical values of integers (decimal numbers must have fixed precision for the sorting to work). Maps are sorted by element keys unless sortByValue=true parameter is provided. Optionally, to get the correct sort order of a specific language, you can use a IETF BCP 47 language tag as the locale argument.

Example: Output sorted elements stored in array x:

{{array "x"}}
{{push "x" "value 12"}}
{{push "x" "value 8"}}
<div>{{#each (sort "x")}}{{@index}}: {{this}}<br />{{/each}}</div>

Example: Output key-value pairs stored in map x sorted by key:

{{map "x"}}
{{setElement "x" "key.foo" "value 12"}}
{{setElement "x" "key.bar" "value 8"}}
{{#eachOfMap (sort "x")}}{{@key}}: {{@value}};{{/eachOfMap}}

Example: Output key-value pairs stored in map x sorted by value:

{{map "x"}}
{{setElement "x" "key.foo" "value 12"}}
{{setElement "x" "key.bar" "value 8"}}
{{#eachOfMap (sort "x" sortByValue=true)}}{{@key}}: {{@value}};{{/eachOfMap}}

Example: Sort array x using the Swedish locale, where “ä” sorts after “z”:

{{array "x"}}{{push "x" "z"}}{{push "x" "ä"}}
<div>{{#each (sort "x" locale="sv")}}{{@index}}: {{this}}<br />{{/each}}</div>

eachOfMap

Syntax: {{#eachOfMap <mapId>}} … {{@key}} … {{@value}} … {{/eachOfMap}}

Description: Iterates all elements of the given map in the original insertion order of the keys.

Example: Output all elements of map x in “<key>: <value>” format:

{{#eachOfMap "x"}}{{@key}}: {{@value}};{{/eachOfMap}}

Example: List 3rd level requirements (e.g. software requirements) associated with the current 1st level requirement (e.g. a stakeholder need) while preventing duplicate entries:

{{map "satLinks"}}
{{#eachInlinkWith type="satisfaction"}}
  {{#eachInlinkWith type="satisfaction"}}
    {{setElement "satLinks" (docObjId) (shortDescription)}}
  {{/eachInlinkWith}}
{{/eachInlinkWith}}


{{#eachOfMap (sort "satLinks")}}
  <div><em>{{@key}}:</em> {{@value}}</div>
{{/eachOfMap}}

Note that you may need to clear the satLinks map by {{clear "satLinks"}} before it is reused in the context of another document object.

Search & Replace

searchString

Syntax: {{searchString <string> <string>}}

Description: Searches a string given by the first argument if it contains a substring given by the second argument.

Example: Returns true if text attribute of a document object contains “shall” substring:

{{searchString text "shall"}}

searchRegexp

Syntax: {{searchRegexp <string> <pattern> [flags=<string>]}}

Description: Searches a string given by the first argument if it matches a regular expression pattern given by the second argument. You can optionally provide flags parameter for the regular expression.

Example: Returns true if text attribute of a document object matches “shall” keyword with ignoring case:

{{searchRegexp text "\Wshall\W" flags="i"}}

replaceString

Syntax: {{replaceString <string> <string> <string>}}

Description: Returns a string given by the first argument with replaced substring given by the second argument by a string given by the third argument.

Example: Output a string with replaced “shall” substring in text document object attribute by "<b>shall</b>":

<div>{{{replaceString text "shall" "<b>shall</b>"}}}</div>

replaceRegexp

Syntax: {{replaceRegexp <string> <pattern> <string> [flags=<string>]}}

Description: Returns a string given by the first argument with pattern given by the second argument replaced by a string given by the third argument. You can optionally provide flags parameter for the regular expression.

Example: Output a string with replaced all occurrences of the keyword “shall” in text document object attribute content by "<b>shall</b>":

<div>{{{replaceRegexp text "(\W)(shall)(\W)" "$1<b>$2</b>$3" flags="g"}}}</div>

Debug

debug

Syntax: {{debug}}

Description: Outputs information about properties available in the current context.

Example: Output debug information about all set document object attributes (heading, text, …):

<!-- {{{debug}}} -->

Other Helpers

user

Syntax: {{#user}} … {{/user}}

Description: Outputs the name, email or company of the current user.

Example:

{{#user}}<a href="mailto:{{email}}">{{name}}, {{company}} {{/user}}</a>

repeat

Syntax: {{#repeat <number>}} … {{/repeat}}

Description: Repeats the block content a specified number of times. Provides @index, @first and @last variables.

Example: Output all array elements in reverse order:

{{#repeat (size "arr")}}
  {{pop "arr"}}
{{/repeat}}

Example: Output sequence [1, 2, …, 5] using @… variables:

{{#repeat 5}}
  {{#if @first}}
    [
  {{/if}}
  {{eval @index "+" 1}}
  {{#if @last}}
    ]
  {{else}}
    ,
  {{/if}}
{{/repeat}}

Example: Iterate across two dimensions using parent context:

{{#repeat x}}
  {{#repeat y}}
    X: {{@../index}}, Y: {{@index}}
  {{/repeat}}
{{/repeat}}

Sample Templates

This section provides some examples of complete custom export templates. To get started, download the sample export templates from the Download Export Templates section.

HTML Table Layout

The following template outputs the current document as an HTML table with Id, Description and Status columns:

<table id="reqsTable">
<!-- Heading of the requirements table -->
<thead><tr>
  <th>ID</th><th>Description</th><th>Status</th>
 </tr></thead>


<!-- Table with list of requirements -->
<tbody>
{{#eachDocumentObject}}
<tr>
  <td>{{id}}</td>
  <td>
    {{#section numbering=true}}{{{heading}}}{{/section}}
    {{{text}}}
    {{#eachAttachment}}
      <div>
        {{#if isImage}}
          <img src="{{data}}"></br>
          <em>Image attachment:</em> <span>{{name}}</span>
        {{else}}
          <em>File attachment:</em> <span>{{name}}</span>
        {{/if}}
      </div>
    {{/eachAttachment}}
  </td>
  <td>{{attributeValue "status"}}</td>
</tr>
{{/eachDocumentObject}}
</tbody>
</table>

HTML Table and Book Layouts

The following template outputs a combination of section headings and informative paragraphs using a HTML book layout, and a list of requirements using a HTML table layout with "ID" and "Requirement" columns.

HTML report: Example output of the template for the SRS document of the Example Project.

HTML template:

{{var "inTable" 0}} {{! Helpers for table layout }}
{{#*inline "endHTMLTable"}}
    {{#if (get "inTable")}}
        </tbody>
        </table>
        {{set "inTable" 0}}
    {{/if}}
{{/inline}}


{{#eachDocumentObject}} {{! Content formatting }}
    {{! Output (non-)functional requirements using a table layout }}
    {{#if (or (eval type "==" "FR") (eval type "==" "NFR"))}}
        {{#unless (get "inTable")}}
            <table>
            <thead><tr><th style="width:8em">ID</th><th style="width:40em">Requirement</th></tr></thead>
            <tbody>
            {{set "inTable" 1}}
        {{/unless}}
        <tr>
            <td><a id="{{docObjId}}" name="{{formatURIComponent (docObjId)}}"></a>{{docId}}.{{id}}</td>
            <td>{{shortDescription}}</td>
        </tr>
    {{else}} {{! Output other types of document using a book layout }}
        {{> endHTMLTable}}


        {{#if heading}}{{#section}} {{heading}}{{/section}}{{/if}}
        {{{attributeValue "text"}}}
    {{/if}}
{{/eachDocumentObject}}
{{> endHTMLTable}}

Note: The template demonstrates how to use Handlebars inline partials to reuse template code.

HTML Traceability Matrix

The following template outputs a traceability matrix for satisfaction links as an HTML table with two columns ID and Links.

{{! Handlebars inline partial which outputs traceability coverage. }}
{{#*inline "exportLinksRecursive"}}
  <ul>
  {{#eachInlinkWith type="satisfaction"}}
    <li>
    {{status}}
    {{docObjId}} {{shortDescription}}


    {{! If the object has a satisfaction link then invoke the partial recursively. }}
    {{#if (hasInlinks "satisfaction")}}   
      {{> exportLinksRecursive}}
    {{/if}}
    </li> 
  {{/eachInlinkWith}}
  </ul>
{{/inline}}


<table id="reqsTable">
  <thead><tr>
    <th>ID</th><th>Links</th>
  </tr></thead>
  <tbody>
  {{#eachDocumentObject}}
    {{! Output traceability matrix for user stories only. }}
    {{#if (eval type "==" "STORY")}}
    <tr>
      <td>{{id}}</td>
      {{! Invoke the inline partial to output traceability coverage. }}
      <td>{{> exportLinksRecursive}}</td>    
    </tr>
    {{/if}}
  {{/eachDocumentObject}}
  </tbody>
</table>

Note: The template demonstrates how to use Handlebars inline partials recursively to output a traceability coverage across several levels.

HTML Traceability Report

You can easily create a HTML export template generating a traceability report with a custom layout, for example exploring which functionality has missing tests and which functionality has been verified by passed tests.

Let’s check a concrete example of a top-down traceability report displaying the highest-level business needs (NEEDS) satisfied by detailed functional requirements (SRS) verified by test cases (TESTS) for the Example Project.

HTML report:

Preview of the HTML template:

HTML template snippet rendering the Traceability column:

<ul>
  {{#eachInlinkWith type="satisfaction"}}
    <li>
      <span>{{docId}}-{{id}}: {{shortDescription}}</span>
      <span>{{status}}</span>
      <ul>
      {{#eachInlinkWith type="verification"}}
        <li>
          <span>{{docId}}-{{id}}: {{shortDescription maxLength=40}}</span>
          <span>{{status}}</span>
        </li>
      {{/eachInlinkWith}}
      </ul>
    </li>
  {{/eachInlinkWith}}
</ul>

The snippet first uses eachInlinkWith block helper to iterate all incoming satisfaction traceability links of the given NEEDS user story. For each such link, it renders a SRS requirement ID, a short description (heading or text attributes) and the value of the status custom attribute.

Still in the context of the linked SRS requirement, the snippet analogically uses eachInlinkWith helper to iterate all incoming verification links. For each TEST object it renders a test ID, a short description, and the value of the status custom attribute.

HTML for Import to Word

The following template outputs HTML to be easily imported into MS Word with book layout containing id, heading, text system attributes, displayed custom attributes and attachments.

<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="utf-8">
  <title>{{docName}}</title>
</head>
<body>
{{#eachDocumentObject}}
  <a name="{{id}}" id="{{id}}"></a>
  <!-- Document object description -->
  {{#if heading}}{{#section numbering=false}}{{{heading}}}{{/section}}{{/if}}
  {{#formatPrefixedXHTML text paragraphClass="text"}}
    {{#unless heading}}<span class="id">[{{docObjId}}]</span> {{/unless}}
  {{/formatPrefixedXHTML}}
  <!-- Document object attachments -->
  {{#eachAttachment}}
    <p class="attachment">
      <span class="attachmentInfo">Attachment:</span>
      {{#if href}}
        <a href="{{href}}">{{{name}}}</a>
        {{#if isImage}}<br><img src="{{href}}" {{imageSize maxWidth=700}}>{{/if}}
      {{else}}
        {{{name}}}
      {{/if}}
    </p>
  {{/eachAttachment}}
  <!-- Displayed document object custom attributes -->
  {{#eachDisplayedCustomAttribute}}
    {{#if value}}
      <div class="attribute">
        <span class="attributeInfo">{{{name}}}:</span>
        {{{formatXHTML value charClass="attributeValueChar" paragraphClass="attributeValuePar"}}}
      </div>
    {{/if}}
  {{/eachDisplayedCustomAttribute}}
  </div>
{{/eachDocumentObject}}
</body>

Note: The HTML template contains the document content marked with HTML tags containing class names without any CSS styling.

This allows easy customization using predefined Word styles in a MS Word template in which the exported HTML is inserted. For more information, see Import Into MS Word.

HTML With Merged Documents

The following template outputs a single HTML file containing id, heading and text attributes of document objects from all exported documents.

<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="utf-8">
  <title>{{projectId}}</title>
</head>
<body>
<h1>{{projectId}}</h1>
<hr><hr>
{{#eachDocument separator="<br><hr><br>"}}
  <h1>{{docName}}</h1>
  <hr>
  {{#eachDocumentObject}}
    <a name="{{id}}" id="{{id}}"></a>
    <!-- Document object description -->
    {{#if heading}}{{#section numbering=false}}{{{heading}}}{{/section}}{{/if}}
    {{#formatPrefixedXHTML text paragraphClass="text"}}
      {{#unless heading}}<span class="id">[{{docObjId}}]</span> {{/unless}}
    {{/formatPrefixedXHTML}}
  {{/eachDocumentObject}}
{{/eachDocument}}
</body>

If you wish to output only specific documents, have a different layout for each document or change the order of documents, use multiple {{#withDocument docId}} blocks within the same template file.

CSV Export

The following sample template outputs a CSV file with values of id, heading, text, and status document object attributes. The tildes (~) are used for trimming whitespace in order to not break CSV format.

"id"{{{csvSeparator}}}"heading"{{{csvSeparator}}}"text"{{{csvSeparator}}}"status"
{{#eachDocumentObject}}
  {{~{formatCSVColumn (docObjId)}}}{{~{csvSeparator}}}
  {{~{formatAttributeCSVColumn "heading"}}}{{~{csvSeparator}}}
  {{~{formatAttributeCSVColumn "text"}}}{{~{csvSeparator}}}
  {{~{formatAttributeCSVColumn "status"}}}
{{/eachDocumentObject}}

JSON Export

The following sample template outputs a JSON file with values of id, section, heading, and text document object attributes.

[
{{#eachDocumentObject separator=", "}}
  {
    "id": {{formatJSONString (docObjId)}},
    "section": {{formatJSONString (sectionNumber)}},
    "heading": {{formatJSONString heading}},
    "text": {{{formatJSONString text}}}
  }
{{~/eachDocumentObject~}}
]

XML Export

An XML file structured as below:

<doc id="D">
    <section id="1" title="Heading 1">
        <section id="1.1" title="Heading 2">
            <clause text="Text 1"/>
            <clause text="Text 2"/>
        </section>
        <section id="1.2" title="Heading 3"/>
        <section id="1.3" title="Heading 4"/>
        <clause text="Text 3"/>
    </section>
    <section id="2" title="Heading 5"/>
    ...
</doc>

can be produced by the following sample template. An array is used as a stack to ensure that all tags are closed correctly. Post-processing by an XML formatting tool is recommended.

{{array "stack"}}
{{var "prevSectionLevel" 0}}
<doc id="{{docId}}">
{{#eachDocumentObject}}
  {{!-- close open tags if current level decreased --}}
  {{#repeat (eval (eval (get "prevSectionLevel") "-" level) "+" 1)}}
    {{{pop "stack"}}}
    {{decr "prevSectionLevel"}}
  {{/repeat}}
  {{#if (isSection)}}
    {{!-- create a new section, save the closing tag for later and note this section's level --}}
    <section id="{{sectionNumber}}" title="{{formatString heading}}">
    {{push "stack" "</section>"}}
    {{set "prevSectionLevel" level}}
  {{else}}
    <clause text="{{formatString text}}"/>
  {{/if}}
{{/eachDocumentObject}}
{{!-- close all remaining open tags --}}
{{#repeat (size "stack")}}
  {{{pop "stack"}}}
{{/repeat}}
</doc>

Download Export Templates

Predefined HTML Templates:

You can download and reuse predefined templates for Export Documents to HTML:

  • HTML / Modern Report — export an interactive HTML file with a table layout using modern CSS styles
  • HTML / Book — export a filtered HTML file with a single column layout and minimal CSS styles, which is suitable for import into MS Word
  • HTML / Table — export a filtered HTML file with a table layout and minimal CSS styles, which is suitable for import into MS Word

Predefined PDF Templates:

You can download and reuse predefined templates for Export Documents to PDF:

  • PDF / Book — export a filtered HTML file with a single column and minimal CSS styles, which is suitable for conversion into a paged PDF document

Example Traceability Templates:

You can download and reuse custom export templates for traceability reports designed for the Example Project:

  • NEEDSTraceabilityTemplate.html — export the top level *NEEDS* document to a HTML file displaying downstream traceability coverage (NEEDS ← SRS ← TESTS)
  • SRSTraceabilityTemplate.html — export the *SRS* document to a HTML file displaying upstream *satisfaction* links (NEEDS ← SRS ) and *verification* links (SRS ← TESTS)
  • CSVTraceabilityTemplate.csv — export a document to a CSV file listing all document object with their *reference* links
  • JSONTraceabilityTemplate.json — export a document to a JSON file listing its document objects with their incoming *satisfaction* links
Updated for version 2.16.2