Example: Creating individual Report Templates

This example leads you step by steps through the process of creating an individual report template in the DocBook format. It will also be helpfull to look through the examples if you want to create a report in another format as there are only minor differences. A list of differences can be found here.
Also note the Tutorial: Creating individual Report Templates

Example Header (DocBook)

The following example header describes the appearance of a header for a report templates:

################### TEMPLATE HEADER #####################
##targetType="docbook"
##templateEncoding="Cp1252"
##targetEncoding="UTF-8"
###########################################################
<?xml version="1.0" encoding="UTF-8"?>

The parameter targetType identifies the report template as a template for DocBooks. "Cp1252" will be used as character encoding (parameter templateEncoding). The targetEncoding for DocBooks has to be "UTF-8".
The XML Header can be found below the template header (as required for DocBooks).

Back...

DocBook Example

The following XML snippet shows the most common elements used by the ARCWAY Cockpit report generation in a simple example.

<book>
  <title>Title of the book</title>
  <subtitle>Subtitle of the book</subtitle>
  <chapter>
    <title>Chapter Title</title>
    <section>
      <title>Title of the section</title>
      <para>
        This is a paragraph ....
      </para>
      <table>
        <tgroup cols="2">
          <colspec colwidth="35mm"/>
          <colspec colwidth="70mm"/>
          <thead>
            <row>
            <entry>Column 1</entry><entry>Column 2</entry>
            </row>
          </thead>
          <tbody>
            <row>
            <entry>Cell 1.1</entry><entry>Cell 1.2</entry>
            </row>
            <row>
            <entry>Cell 2.1</entry><entry>Cell 2.2</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>
        This is a paragraph with a list
      </para>
      <para>
        <simplelist type="inline">
          <member>list element 1</member>
          <member>list element 2</member>
          <member>list element 3</member>
        </simplelist>
      </para>
    </section>
  </chapter>
</book>

A report template that contains a header and this DocBook block can already be used to generate a report. Test this first draft as described here.

Back...

DocBook Example with Velocity Directives

The following example extends the DocBook example with some velocity directives:

#macro (title $arg1)
  <title>$arg1</title>
#end

#set ($three = ["1", "2", "3"])
<book>
  #title ("Title of the Book")
  <subtitle>Subtitle of the Book</subtitle>
  #foreach ($count in $three)
  <chapter>
    #title ("Chapter Title $count")
    <section>
      #title ("Title of the Section")
      <para>
        This is a paragraph ....
      </para>
      <table>
        <tgroup cols="2">
          <colspec colwidth="35mm"/>
          <colspec colwidth="70mm"/>
          <thead>
            <row>
            <entry>Column 1</entry><entry>Column 2</entry>
            </row>
          </thead>
          <tbody>
            <row>
            <entry>Cell 1.1</entry><entry>Cell 1.2</entry>
            </row>
            <row>
            <entry>Cell 2.1</entry><entry>Cell 2.2</entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para>
        This is a paragraph with a list
      </para>
      <para>
        <simplelist type="inline">
          <member>list element 1</member>
          <member>list element 2</member>
          <member>list element 3</member>
        </simplelist>
      </para>
    </section>
  </chapter>
  #end
</book>

A report template that contains a header and this DocBook block with velocity directives can already be used to generate a report. Test this first draft as described here.

Back...

DocBook Example with ARCWAY Cockpit Data

The following example changes and extends the velocity example with dynamically inserted Cockpit data:

############################################################################
##
## MACRO: title
## Creates the <title>-tag with the given parameter as content
##
############################################################################
#macro (title $arg1)
  <title>$arg1</title>
#end

############################################################################
##
## MACRO: showRequirementChapter
## Creates a chapter which lists all root requirement sets
##
############################################################################
#macro( showRequirementChapter )
   #if( $arrayHelper.getArraySize( $requirementDataProvider.getAllRequirements() ) > 0)
    <chapter>
      #title ("Requirement Sets")
      <para role="StandardIndented">This chapter lists all root requirement sets:</para>
             ## add a blank line
      <para role="StandardIndented"></para>
             ## get the root set and start writing the report for the root sets
       #set ($count = 0)
       #foreach( $requirementSet in $requirementDataProvider.getRootRequirementSets() )
         #set ($count = $count + 1)
         <para role="StandardIndented">$count. $requirementSet.getName()</para>
       #end
     </chapter>
   #end
#end

#set ($activeProject = $projectDataProvider.getProject())
<book>
   #title ("Requirements in the project $activeProject.getName()")
   <subtitle>Generated automatically</subtitle>
   #showRequirementChapter()
</book>

A report template that contains a header and this DocBook block with velocity directives and Cockpit data can be used to generate a complete report. Add the ARCWAY format template to your project and test this complete draft as described here.

Back...

Example Header (other Formats)

Change the example above as described here to create a report template for other formats.

XML

Use the following header when creating the report template with a common Windows text editor and the generated report is supposed to be a XML document, but not a DocBook:

################### TEMPLATE HEADER #####################
##targetType="xml"
##templateEncoding="Cp1252"
##targetEncoding="UTF-8"
###########################################################
<?xml version="1.0" encoding="UTF-8"?>

The parameter targetType identifies the report template as a template for XML documents. "Cp1252" will be used as character encoding (parameter templateEncoding). The targetEncoding for XMl files has to be "UTF-8".
The XML Header can be found below the template header (as required for XML files).

CSV

Use the following header when creating the report template with a common Windows text editor and the generated report is supposed to be a CSV document:

################### TEMPLATE HEADER #####################
##targetType="csv"
##templateEncoding="Cp1252"
##targetEncoding="Cp1252"
###########################################################

The parameter targetType identifies the report template as a template for CSV documents. "Cp1252" will be used as character encoding (parameter templateEncoding) and as the targetEncoding for the generated CSV file.

Zurück...

Differences for Other Formats

XML

For a report template for XML documents simply change the header of the report template as described in the section above (Example Header (other Formats))

CSV

Have a look the following instructions to created a report template for csv documents:

Change the header of the report template as described in the section above (Example Header (other Formats))
The header attribute targetEncoding describes the encoding that is used by the program that opens the csv file later on. For example, if this is MS Excel under Windows, the target encoding has to be set to "Cp1252" as in the example header.
Also note that Cockpit data will be XML encoded in most cases. Hence you will have to decode the data by calling the csv helper.