Export reports to Microsoft Word using Custom Templates

This function allows you to export input data and tables of calculation results to Microsoft Word custom templates.

To export the input data and calculation results, select the menu command File > Export > Report into MS Word

Then, select the data that needs to be exported, select the option "export via *.tlb" and click OK.

1. Custom Templates

Templates are ordinary .docx files edited directly in MS Word. A special markup language is used to control the output.

The package includes a basic set of templates for the main norms and languages. The users can edit the provided templates and create their own kits.

2. Settings

To select the language of output documentation, select the menu item Service > Settings > Language > Language of output documents

You can enter additional user information for the report on the menu tab File > Project Settings > Info

Field Variable
Title user.Title
Project Name user.Project_name
Client user.Client
Document Number user.document_No
Receivion user.Revision
Receivion Date user.revision_date
Approved user.approved
Checker user.checked
Prepared user.prepared

 

3. Kits of templates

The basic kit of templates is located in the installation directory Start ..\CTAPTPR\Templates\

Each regulatory document (code) has its own template - the root template. It may include other templates - embedded templates. Together they make up a kit of templates.

For each output documents language, it is possible to create a separate kit of templates. Templates shall be placed in the appropriate directory:

Language Folder Name
English en
Spanish esp
Chinese ch
Russian ru

If a folder already exists for the selected output documents language, templates in the root of the ..\STARTPR\Templates\ directory will be ignored.

4. Data tables

When starting the report export from START, text data tables are generated, on the basis of which the report is generated. Data tables are saved in files with the .tbl extension in the temporary system directory ..\AppData\Local\Temp.

Each data table is divided into sections. A section starts with its name in square brackets and ends, if a new section starts or the end of the file is encountered.

The section has one of two types: map (map) or table (table). In the map section, each line has the form <key>=<value>[,<additional parameters>].

In the table section, each line has the same number of value fields separated by commas. If you need to use a comma as a data segment, use the sequence &comma;.

Each table has two sections: meta of the map type and data of the table type. The meta section describes the parameters of the fields, whose values are included in the data section.

Meta description format:

<id>[=<val>[,<name>[,<type>[,<units>[,<factor>]]]]]

id – field identifier

val – value, an empty string by default

name – field name, by default matches id

type – type, 0 by default

units – units of measure, an empty string by default

factor – multiplier to convert value to SI system units, default is 1.0

It is allowed to omit the values of some parameters, keeping the commas. For example, the line

foo=,42,,0.5

defines a field with the following parameters:

id name type units factor
foo foo 42   0.5

The data section includes lines, each of which is the value of the val fields in the order corresponding to the description of the meta section.

An example of a fragment of the input data table:

[meta]

node_start

node_end

x=,,,mm

y=,,,mm

z=,,,mm

material=,,1

[data]

1,2,1000,0,0,A106 B

2,3,0,1000,0,A106 B

3,4,0,1000,0,A106 B

This table defines three lines of data:

node_start node_end x y z Material
1 2 1000 0 0 A106 B
2 3 0 1000 0 A106 B
3 4 0 1000 0 A106 B

 

For variables x, y, z defined not empty parameter units with value "mm".

5. Template Syntax

5.1. Template directives

All template language expressions are contained within a bounding pair of opening and closing character sequences of the form {#...#}.

In the notation used below, square brackets enclose optional parts of directives, triangular brackets — mnemonic names that should be replaced with a real value.

The general view of the directive is as follows:

{# <tag>[: attributes] #}

For variables or

{# <tag>: attributes #} … {# end<tag> #}

For sections if, for, etc.

Attributes of the attributes directive is a kit of attributes separated by commas. Each attribute is represented by a name or a <key>=<value> pair. In some directives, instead of the = sign, logical operators can be used (see below).

An example of directive:

{# name: F=c, L=en #}

Here tag is "name" and two attributes "F" and "L" with values "c" and "en" respectively.

5.2. Tables

At each moment of template processing a current table exists, which is used by default. Each table has its own structure — a set of lines, each of which includes a set of variables (similar to the lines and fields of a database table) and corresponds to its own data table file generated in START.

The current table has a current line, from which data is retrieved. Line by line traversal of the table called name is carried out by special directives:

{# for: <table>[,<condition> ] #}…{# endfor #}

At each iteration, the set of variables takes values from the current line of the table.

The optional attribute <condition> allows you to iterate over records filtered by a condition. For more information about conditional attributes, see “Conditional Directives”.

The value of condition is evaluated at each step of the cycle in the context of the current record. If the condition is true, the cycle body is executed for this record, otherwise the record is skipped and the next record is processed.

Blocks for can be nested.

Table fields can also be iterated. This can be done using the directive

{# for: [<table>.]fields [,<condition> ] #} {# endfor #}

At each step of the cycle for fields, variables are available that correspond to the parameters of the current variable: id, name, val, etc. Intrinsically, “fields” is a special table that is created at each step of the cycle “for table”. If for fields is used outside of for table, then prefix “table” shall be defined. In this case, the values are taken from the meta section.

The optional attribute <condition> allows you to iterate over fields filtered by a condition. For more information about conditional attributes, see “Conditional Directives”.

5.3. Table of tables

The table of tables contains a list of generated tables that can be used to display those tables in the order set by the user. Table of tables example:

[meta]

DescrData=,1

Materials=,1

The table of tables is stored in the tables.tbl file.

5.4. Auxiliary data tables

5.4.1.  Translation tables

For translation into different languages, a translation table is used, which includes the translation of names into different languages. Translation is given for values of id variables or arbitrary strings. Translation table example:

[meta]

id

en

esp

[data]

DescrData, general data, general data

pipe, tuberia

node, nodo

The translation table is saved in a file translation.tbl.

5.4.2. Additional information table

Additional user information is stored in a file user.tbl.

5.5. Variables

Variable directives are replaced with data from tables — variables take on the values of the fields of the current line.

Each variable can have several parameters:

id – variable identifier (mandatory).

name – variable name (optional, if omitted, matches id).

val – variable value (mandatory).

type – type (classifier) of the variable. Used for filtering. For example, in the input data, the fields node1, node2,x,y,z have type=0, the main parameters are type=1, the additional parameters are type=2.

factor – multiplier of the value that converts it to the SI system

units – units of measure

The “units” and “factor” parameters allow you to display values both in the original units and change the units in the template.

General view of the variable:

{# [<table>.]<id>[:<attr1>=<value>,<attr2>=<value2>…] #}.

table — name of the table. If the table name is omitted, then the value of the variable is taken from the current table, set in the {# for... #} cycle. If the table name exists, then the default values from the [meta] section are used, even if the table is opened in a cycle.

id – variable identifier. Attributes:

D – display: output variable attribute, val by default

L – language: output language. The output value is translated into the required language

M – multiplier: multiplier factor. The output value is multiplied by the multiplier value. Can be specified as a number or an expression containing * or / and the variable 'factor' - the value of the “factor” parameter of the current variable.

F – format: number output format in the form s[n]. s specifies the type of output (e - exponential; f - fixed point; g - chooses the shortest notation from e and f; n - integer; t - the value is converted to the text "None" [if the value is empty or equal to 0] and " Yes" otherwise; c is capitalized), n specifies the number of characters to output.

The following examples show different ways to output a variable:

{# code: L=en #} – displaying the value of the “code” variable in English

{# force #} – displaying the value of the “force” variable, as it is contained in the data table

{# force: L=ru, D=name #} – displaying the “force” variable name in Russian

{# force: F=g5 #} – displaying the value of the “force” variable in universal format with 5 digits

{# force:D=units, L=ru#} – displaying units of a variable in Russian

{# force: M=factor*1000, F=e3 #} – displaying the value of the “force” variable multiplied by 100 in scientific format with 3 digits.

Let, for example, we have the following data for the current record of the current table:

id=A, name=A, value=42, units=mm, color=red

as well as the corresponding translation of the words "mm" and "red" in the translation table.

Then in the template we can write various directives:

{# A #} = 42

{# A: M=0.01, F=e1 #} = 0.4

{# A: D=value #} = 42

{# A: D=name #} = A

{# A: D=units, L=ru #} = мм

{# A: D=color, L=ru #} = красный

5.6. Conditional directives

Conditional directives allow you to evaluate a value and include or exclude a template fragment based on the value of the result.

The conditional directive looks as follows:

{# if: <condition> #}

[ {# else #} ]

{# endif #}

Condition is a conditional expression. Operators <, >, ==, !=, <=, >= can be used in a conditional expression. Values to be compared can be double-quoted strings, numbers, or variables in the form [<table>.]<name>[.<parameter>]. “table” is the current table by default, “parameter” is val by default.

To check if a variable exists, use the exist pseudo-property:

{# if: <name>.exist #}

Form without comparison operator

{# if: <name> #}

Is a short form of record

{# if: <name> != “” #}

5.7. Translation Directive

To translate arbitrary strings by the translation table, use the directive

{# tr:<text>, L=<lang> #},

where text is the text in double quotes to be translated, lang is the target language.

Example: {# tr:”red”, L=ru #} = красный

5.8. Images

The inclusion of images in JPEG, BMP, PNG formats, defined by the file extension *.jpeg, *.jpg, *.bmp, *png, is supported.

The image files are taken from the same folder as the data tables.

To include an image, use the directive

{# img: <filename>, w=<width>, h=<height> #}, where w and h are the width and height of the image in centimeters. If one of the w or h parameters is missing, the remaining parameter is used and the picture is scaled proportionally to the original size. If both parameters are missing, the image is inserted at 100% size.

The file name <filename> is specified either statically as a double-quoted string, or as a variable in the form [<table>.]<name> , whose value is substituted as the file name.

5.9. Enable templates

Special derective

{# include: <filename>[, curTable=<table>] #}

allows you to include the contents of another template named <filename> in the current template. If filename is a quoted string, then it is used as is, otherwise it is interpreted as a variable name in the form [<table>.]<name>, the value of which is substituted as the file name.

If the curTable attribute is specified, then variables in the embedded template named curTable and curTable_config will be replaced with variables named <table> and <table>_config respectively. This allows to use the same template with different tables that are set when the template is enabled.

When you include templates, only the content of the main section of the document is used. Style definitions, headers, page settings, and sections of included templates are ignored. Styles and page settings should be configured in the main template. Therefore, it is recommended that all included templates be created based on the root template, so that the document styles will always match.

Examples:

The following directive includes the template from the Materials.docx file:

{# include: “Materials.docx” #}

The following cycle can include templates for the tables contained in the table of tables by prefixing them with bilingual headings:

{# for: tables #}

{# name: L=ru, F=c #} ({# name: L=en, F=c #})

{# include: id #}

{# endfor #}

6.  Template generator

The report generator is a separate external program. If necessary, the generator can be used separately from START by running the executable file with the following parameters

..\CTAPTPR\StartReport\NTP.StartReport.Console.exe <main_template> <output> < template_directory> <data>

where:

<main_template> - path to the main template file.

<output> - path to the report file.

< template_directory> - directory of templates kit.

<data> - data directory.

Menu Access

File > Export > Report into MS Word