Report template specification

TimeTraces
Size: 2.9 MB
Also as zip archive


For only US $ 26.99

Introduction

TimeTraces comes with several report templates pre-installed.  The available templates are described on the Report look and layout page.  You can customize these existing report templates or create new report templates for yourself.  The report templates are installed in the "Report templates" subfolder in the TimeTraces application folder (most commonly located at "C:\Program Files\TimeTraces\Report templates").  The report templates are translated in all supported languages; each language's set of templates are located in its own subfolder.  When you want to use additional report templates you have to place them in these folders.

Report templates consist of two files; a settings file and a content file.  The settings file must have the ".ttr" extension; you are however free to name the content file as you like.

The templates that are located in the report template folder are presented as possible choices in the "Generate report" window.  Included with the help pages are also some sample templates you can base your own templates on.  You can find these in your TimeTraces application installation folder in the subfolder "Help\EN\Report samples".  They show you how to work with the different file formats, but they will probably need customization to fit your needs.

Report settings file

The report settings file is a regular Windows INI file.  It needs to have a section called "[Settings]", in which all settings are listed.  All settings need to be specified.  The available settings are:

The used report format encoding dictates how the data will be written out.  The data will be processed and/or encoded to fit the desired output format when needed.  The available formats are:

Report content template file

The content of the report will be built up dynamically by filling in tags and tag sections in the report content template.  All tags are placed between "[#" and "#]" marks, like [#tagname#].  Tags are case sensitive and whitespace is not allowed in them.  There are a couple of groups of tags you can use.

Some tags form tag sections.  These are used for writing out all the activities, time periods and time values in the report.  These sections are used to mark an entire block of content to be filled in repeatedly for each item in the set they represent; they thus enable you to e.g. list all used activities and write out the time values as a table.  Section tag names end with "startsection" and "endsection" and must be used in pairs.

There are several modes in which activities and time period sections will write out their items.  This is denoted by writing the mode after the section start name between "(" and ")" characters, like [#activity_startsection(user)#].  The available modes per tag are mentioned in the documentation for the tag by listing all modes between "(" and ")", like "(all, user, used)".  The following modes are recognized:

The "user" and "user_insection" versions reflect the user's choice; he can opt to not include empty activities and/or empty time periods in the "Generate report" window (the report options "Include empty activities" and "Include empty time periods").

Another distinction exists between "(roundsum)" and "(sumround)" tag modes; this is indicated by "(roundsum, sumround)".  There is a difference in the final result between rounding values before summing them up versus summing up values and then rounding the result.  Both versions are useful in reports.  The "(roundsum)" mode represents results that are summed over rounded values, and the "(sumround)" mode represents results that are rounded after summing the values.

A tag or tag pair can occur more than one time in the content template.  Every occurrence will be filled in independently, which allows you to e.g. create both a header and a footer row using the same "activities" section tag pair.

Report options tags

The available report option tags are:

Project details tags

Available project detail tags are:

Time period details tags

The chosen time period for the report is divided into discrete separate sub time periods according to the "Statistics per" reporting option.  The tags for the details on these sub time period periods are:

Report total time tags

The total time registered in the report is available via the tags:

Report activities tags

The set of activities can be written out by a tag pair.  The tag pair is:

Within an activity section you can write out the activity's characteristics via the following tags:

Within an activity section you can also write out the details of each time period via the following tag pair:

Within an activity time period section you can write out the details of that time period and the time registered on that activity in that time period via the following tags:

Report time periods tags

The set of time periods can be written out by a tag pair.  The tag pair is:

Within a time period section you can write out the time period's characteristics via the following tags:

Within a time period section you can also write out the details of each activity via the following tag pair:

Within a time period activity section you can write out the details of that activity and the time registered in that time period on that activity via the following tags:

Report content tag usage examples

The above information is a bit abstract, so here is an example to help you on your way.  The template below writes out a CSV data file.

• We need to list both a header line containing the activities and the time data grid for each time period.  The first objective is performed using the [#activity_startsection(user)#] tag, and the second objective via the [#timeperiod_startsection(user)#] tag.
• The "Start,End" at the start of the template forms the headers for the start- and end date/time of the time periods in the rows.
• Immediately following that is the [#activity_startsection(user)#] and [#activity_endsection#] tag pair that writes out all activities in the report.  This composes the part of the header including the activity details.
  • Note that a comma leads the details in this section; this way each entry is separated by a comma (as is required by the CSV format).
  • Since each activity has a preceding comma, you do not explicitly have to separate the "End" header from the first activity.
  • Each activity is represented by its path via the [#activity_path#] tag.
• After the activity header has been build up we include the final "Total time" header, preceded with a comma to separate it from the last activity.
• Because each row in a CSV file needs to be on its own line, and because empty rows are unwanted in CSV files, you have to include exactly one line ending between the [#timeperiod_startsection(user)#] and [#timeperiod_endsection#] tags.  Since the first data row needs to be separated from the header anyway, it is best to use the line ending at the end of the header for this.  On the same line following the header is thus the [#timeperiod_startsection(user)#] tag with nothing but the line ending following it.
• Each data row is preceded with the start- and the end date/time of the time period representing the row.  This is done via the [#timeperiod_start#] and [#timeperiod_end#] tags.  They need to be separated with a comma.
• Following the row header is the time data.  This is done the same way as the header was build up, now using the [#timeperiod_activity_startsection(user)#] and [#timeperiod_activity_endsection#] tag pair instead.  Each time value is written out by the [#timeperiod_activity_time(roundsum)#] tag.

General notes

• Since you need to insert a tag section's start- and end tags right where you must write out the report sections, it might not be possible to edit some template in all editors.  An example is a HTML formatted report in which you want to build up a table containing the time periods on the rows.  In this case the start- and end tags writing out the rows should be placed around the HTML row tags (<tr> and </tr>), but within the <table> tag.  This is however illegal in HTML; arbitrary text between these tags is not allowed.  You could still use an HTML editor to set up the look and feel of the template, but you need a plain text editor like Notepad to finally insert the section start- and end tags.
• The tag names are case sensitive and do not allow whitespace in them.  Unrecognized tags are not processed.
• When you modify an existing report template, it will be overwritten when you install a newer version of TimeTraces.  In order to preserve your modifications it is best to create a copy of the template you wish to modify and modify the copy instead.  Do not forget to specify a new name for your copy, otherwise it and its original will be indistinguishable in the "Report template" choice.
• When you make a portable installation of TimeTraces that includes report templates, all files in the "Report templates" subfolder will be copied.
• The table layout format in the RTF specification is quite difficult to reconcile with dynamically building up a table via template substitution.  The reason for this is that you have to define the absolute position of the right edge of each table cell individually (using the \cellx command).  When using tables in RTF you can best limit the dynamic expansion to the rows only, and keep a fixed number of predefined columns.  The columns can of course still contain single template parameters.  If you want to dynamically add columns via the template, your best option is to use the "activity_nr" or "timeperiod_nr" tags to create increasing column end positions (in multiples of 100 e.g. by using "\cellx[#activity_nr#]00").
• If you plan on writing RTF templates, you are (at least initially) advised to save your templates via WordPad and not Microsoft Word.  WordPad uses a far smaller subset of the RTF specification which vastly reduces the generated RTF complexity and size.  The templates created this way are still fully compatible with Microsoft Word.