DocX

The DocX Report Engine resides in the Repertoire application and make use of a DocX file and the datasource file as data to generate the required report.

The DocX engine can be invoked using the user interface in the Repository.

The Repository has a job queue to allow multiple jobs to be triggered on the same report. Some delay may be experienced on the return results or reports if there are jobs that need to be completed before yours could begin.

DocX File

The DocX file is a template that contains the format and defines which datasource file to use to generate the report.

It can be created using Microsoft Word from Office 2007 onwards. To view a DocX file, you may need to install the File Compatibility Pack which an be downloaded from Microsoft Download Center (http://www.microsoft.com/downloads/). If Open Office is used, the Compatibility Pack is not required for viewing.

After the DocX file is being created, place the DocX file in the Repository folder so the rendering engine can find it.

Comments

There are markers in the document that indicate the locations of the different bands of the template. In most cases, only the start of a comment and the text associated with the comment is important. For RenderIf, described later, both the start and end of the comment are important.

Some comments have special meanings to them and they are listed below.

Comment Description
Section Indicates the start of data processing.
This can be defined by any name. For example: /Elx/Section1.
Header Presents information about the particular data group being viewed.
For instance, the group name and a brief description about the data contained in the group which appears at the beginning of a new group of record. This can be defined by adding the following into the comment:
/Elx/Header
Subreport Contains data from another report.
It can be defined by adding the following:
/Elx/Subreport
RenderIf Allows for conditional rendering.
It has the same use as RenderIf in regular RML reports. This can be defined by adding the following:
/Elx/RenderIf <script>
where <script> can be any JavaScript, such as age>=18.
If the script evaluates to true then all the content between the start and end of the comment is included.
If the script evaluates to false then all the content between the start and end of the comment is skipped.
RenderIf scripts should only be used within, not across report band boundaries like /Elx/Header, /Elx/Detail and /Elx/Footer. If the script is likely to be long, it is advisable to create a function elsewhere and reference it, for example:
/Elx/RenderIf testAge(age)
instead of putting the full script in the comment. See /Elx/Script for more details on creating long scripts.
Detail Contains the main body of the report’s data.
The detail section prints individual records and repeat until all records have been printed. It can be defined by adding the following into the comment:
/Elx/Detail
Image Contains a column name, extracts the value of image as Binary Array data type from a datasource, i.e., Blob from a database, and displays the extracted value as image.
The data type of this column should by ByteArray, and its name must be consistent with the column name in the datasource. This can be defined by adding the following:
/Elx/Image/<ColumnName>
Note
Add this comment where a blob image is supposed to appear, and add a placeholder image as well. The comment should be added just before the placeholder image following the syntax above. In case the placeholder image is not replaced after rendering, check if the /Elx/Image comment is before the image in reading order (typically left/right top/bottom).
Footer Contains totals or similar information that appears at the end of each group.
This can be defined by adding the following:
/Elx/Footer
Footer/PageBreakAfter Forces a page break after each group of the report.
This is different from using /Elx/Footer comment alone, which will generate line breaks between groups. This can be dfined by adding the following:
/Elx/Footer/PageBreakAfter
End Refers to the end of the Section.
This can be defined by adding the following:
/Elx/End

Datasource

A datasource (DS) file provides the configuration details to access a collection of records, for example by loading from JDBC, XLSX or MongoDB. The DS file need to be defined in the DocX file to be used by the DocX report engine to generate reports.

Define DS File

The DS file can be defined in the DocX file by using the following:

/Elx/DataSource/<SectionName>/Name/<datasourceName>.ds

For example:

/Elx/Datasource/Section1/Name/FruitSales.ds

Define DS Parameter

This can be added using the following:

/Elx/DataSource/<SectionName>/Parameter/Name/<ParameterValue>

For example:

/Elx/Datasource/Section1/Parameter/Name/${Company}

Group and Sort Data

Grouping is done for categorization of data into various logical collection. Sorting is for arranging the data in ascending or descending order.

You can group and sort the data using the following:

/Elx/DataSource/<SectionName>/Group/<dsFieldName>/<SortOrder>

For example:

/Elx/DataSource/Section1/Group/City/Ascending

Note

There are four different types of sorting available: - Normal sorting - Ascending - Descending - Lexicographic sorting - Ascending-Lexicographic - Descending-Lexicographic

The differences between ascending/descending and ascending/descending-lexicographic: - Normal sorting follows a proper dictionary sort algorithm in which spaces are ignored. Lexicographic sorting does not follow the proper full sort definition, instead it treats every character as significant. - Dictionary normal sorting sorts in the order of symbols first followed by alphabets, ignoring any spaces between the words. Lexicographic sorting is in the order of spaces, symbols and then alphabets. - Lexicographic sorting is especially useful when sorting data that contains any symbols, abbreviation, initials and spaces.

Parameter

A parameter is “declared” when a user enters a string like ${parameterName} within a DocX report. A parameter is defined when a value is supplied. A report may have multiple declarations and mixed with normal text. Below is an example:

My name is ${first} ${last}.

There are two ways of defining parameters:

  • Define parameter individually - Defining each parameter one by one in the DocX report. It can be defined as:
    /Elx/Parameter/<ParameterName>/Value
    For example:
    /Elx/Parameter/Text/${User##MyName}

  • Load properties file - all parameters declared are to be placed in a “Properties” file together with the desired elements defined. It can be defined as:
    /Elx/ParameterFile/<Properties-FileName>.properties
    The parameters should follow the following format:
    <ParameterName>=Value.
    For example:

    Password=${Password#password#MyPassword}
Name=${User##MyName}
PreferredChoice=${MyChoice#choice(Apple,Orange,Pear)#Pear}
Data=${Date#date#2011-06-01}
Integer=${Integer#integer#20}
Number=${Number#number#25-6}

Parameter Element

Each parameter can have up to three elements; name, type and default value. These elements are separated by the character #, which can be omitted when there are no subsequent elements.

Syntax Description
${name} This syntax is used to specify a parameter name.
${name#type} This syntax is used to specify the name and type of dynamic parameter.
${name#type#value} This syntax is used to specify the name, type and value.
${name##value} This syntax is used to specify the name and value.

Substitutions

You can include substitutions in table names, headers and footers, to replace variables with field values.

Before adding substitutions, ensure to define the datasource where the data comes from at the end of the DocX document. For example:
/Elx/DataSource/Section2/Name/MySample/DocX/MyDataSource.ds

Table Names

To substitute for table names, define as follows ${Section2:MyField} to allows data from other datasources to be rendered as table names, which does not have to be within one section. When the datasource is within one section (where the substitution will be included), leave out the prefix and only use ${MyField}. When the datasource is from another section, you will get the data from the first record in the table.

Headers and Footers

Similar with above, you can render data fields and parameters into headers, using ${Section2:MyField}, ${S1:Field} or other code following the syntax. When the datasource is defined within one section, remove the prefix and only use ${MyField}. When the datasource is from another section, you will get values from the first record of the referenced data table.

Scripts

You can add a script into the DocX document, by declaring them individually or by loading a script file.

Defines Individually

To define scripts individually, it can be defined as following:
/Elx/Script/<Define scripts here>

For example:
/Elx/Script/function sumFn(a,b){return a+b;}
var script2=sumFn(2,4);

To use the script in the report, enter ${=script2}.

Load Script File

To load a script file, define as follows:
/Elx/ScriptFile/<ScriptFileNAme>.js

For example:
importScript("ElixirSamples/Reports/Scripting/minusJS.js");
function sumFn(a,b)
{ return a+b; }

To use the script in the DocX report, enter the following:
${=sumFn(2,4)}

Alias

Alias are used to shorten substitutions in order to fit the available space better. For example:

${=elxfn.dataDiff(new java.util.Date(107,0,1), new java.util.Date(),'d')}

The result is probably a few integers which will fit in a table cell. However, Microsoft Word will try to show the whole substitution ${=elxfn.dataDiff(new java.util.Date(107,0,1), new java.util.Date(),'d')} in the field, which will later the layout. Therefore, for report neatness, we use substitution as an alias. Instead of a long string, we can use ${@1} (1 is used here, but any name is fine).

Note
The alteration of layout is only during the designing of the DocX report. When rendered, the tables will display according to the height and length of the text.

Hiding Processing Instructions

Processing instructions can be temporarily disabled in two ways; by adding an additional slash or the word Hide.

  • Adding additional slash - use the following syntax:

    /Elx//Datasource/Sectional1/Name/FruitSales.ds

  • Use Hide - use the following syntax:

    /Elx/Hide/Datasource/Sectional1/Name/FruitSales.ds

Formatting

Very often, substituted values need to be formatted. For example, a user wishes to show only the hours and minutes of a date, or show thousand separator and two decimal places for calculated results. This is handled by prefixing the substitution with a format string, which always begins with the character #. This follows the standard Java formatting syntax. The end of the string is marked with the | character.

Data Field

The formatting syntax for data field is as follows:

${%,.<numOfDecimalPlaces>f|<DataFieldName>}

For example:

${%,.2f|2000}

Script

The formatting syntax for script is as follows:

${%,.<numOfDecimalPlaces>f|<JavascriptHere>}

For example:

${%,.2f|=var a=2; var b=4; totalSum=a+b;}

Alias

The formatting syntax for alias is as follows:

/Elx/@/<AliasName>/%,.<numOfDecimalPlaces>f|<JavascriptHere>

For example:

/Elx/@/1/%,.2f|=var a=2; var b=4; totalSum=a+b;

Note
As Javascript has no integer type, always use %f (floating point) when referring to numbers returned from Javascript. If you refer to %d (decimal integer), an error will occur. To show a floating number as an integer, use %.0. To show a numeric figure such as 12.34, use %.2, which indicates two decimal places.

Example of DocX File

Below is an example of a DocX file. The upper part of the DocX file defines the format of the report. The first line below the table defines the location of the datasource file. The rest defines the order and the format of the fields used.

The datasource file must reside in the location defined in the DocX file, otherwise an empty report will be generated.

Render DocX Report

To render the report, select the DocX document from the Repository and right-click it. Select the “Render” option from the pop-up menu.

The “Dynamic Parameters” dialog box will appear.

Key in the desired city in the “city” field. Click on the “Finish” button to render the report. The output report will be rendered and displayed in Microsoft Word.

In the example below, the city defined is “Haney”. The report is generated using the DS file as content and the DocX file as template.

Next: Scripting with JavaScript