Training:Microsoft office and OpenDocument as a Report generator

Microsoft office and OpenDocument as a Report generator

This page was created by Alexandra on 2018-04-01. Last edited by Wikiadmin on 2026-07-29.

You can create an OpenDocument report from a ViewModel and open the completed file from an action in your MDriven application.

This training exercise shows the report-design workflow for OpenDocument Text (.odt) and OpenDocument Spreadsheet (.ods) templates. For the complete feature reference, including template retrieval options and output methods, see Documentation:OpenDocument.

What you will build

You will create a report ViewModel that supplies:

the URL or path of an OpenDocument template;
the name of the generated report file; and
the values that replace tags in the template.

For example, a rent-bill report can show an apartment number, an amount, a billing period, and a table of other people living in the same house.

Before you begin

You need:

a model with data to report on;
a ViewModel rooted at the class from which the report should start; and
an office editor that can save OpenDocument files, such as Microsoft Office, LibreOffice, or OpenOffice.

Choose the root class carefully. A report for one billing period should be rooted in the billing-period class, not in a related lease-contract class, if the billing-period values are the main report data.

Create the report ViewModel

In MDriven Designer, create a new ViewModel for the report.
Set its root class to the object from which users will generate the report.
Name the ViewModel descriptively. For example, RentBillReport.
In the ViewModel context menu, select Add column > Add columns needed for report.
Add the report data columns that the template must display. For example: ApartmentNumber, Rent, PeriodStart, and PeriodEnd.
Select the ViewModel and, in its settings, clear Use placing hints. Report ViewModels provide data to a document template; placing hints intended for a user interface make the report definition harder to read.

The Add columns needed for report command adds the root-level columns required by the reporting mechanism:

Column	Purpose	Example expression or value
`TemplateUrl`	Identifies the OpenDocument template to merge with the ViewModel data.	`'http://localhost:8182/content/RentBill.odt'`
`ReportFileName`	Names the generated file, including the correct extension.	`'RentBill.odt'`

The report ViewModel must have these columns at its root level. Use an .odt file name for text reports and an .ods file name for spreadsheet reports.

Make the template available

The report engine can retrieve a template from a URL, the local file system, or a BLOB attribute in a modeled class. See Documentation:OpenDocument for the supported retrieval methods.

Use an AssetsTK template with Turnkey

For a template that is deployed with a Turnkey application:

Locate the folder that contains your .modlr file.
Create a folder named <YourModelFileName>_AssetsTK.
In that folder, create a content folder.
Save the template in the content folder. For example, save RentBill.odt as <YourModelFileName>_AssetsTK/content/RentBill.odt.
Set the TemplateUrl expression to the URL that serves the file. A local example is 'http://localhost:8182/content/RentBill.odt'.

Use a local file while developing

You can also point TemplateUrl to a local file, for example 'c:\\temp\\RentBill.odt'. This can be useful during development, but it depends on the environment where the application runs. Use a deployed URL or another supported retrieval method when the report must run outside that development environment.

Create an ODT template

Create a text document in your office editor.
Save it as an OpenDocument Text file with the .odt extension.
Add %meta% as the first string in an element in the document.
Run the report once. The generated document replaces %meta% with the tags available from the report ViewModel.
Copy the required generated tags, including their percent signs, into the template where their values should appear.
Save and close the template before generating the report again.

For example, after discovering the available tags, a rent-bill template can contain:

Bill for apartment %ApartmentNumber%

Please pay %Rent% for the period starting %PeriodStart%
and ending %PeriodEnd%.

Important tag rules

%meta% is case-sensitive.
%meta% must be the first string in its element to be recognized.
Copy generated tags rather than typing part of a tag manually. Office editors can insert invisible formatting information that prevents a tag from being recognized.
In Microsoft Word, font changes inside a tag, including changes that appear invisible, can prevent replacement. Replace the tag by pasting it as plain text.
Line breaks inside a tag also prevent replacement. Configure the text section to avoid line breaks in the tag.
Close the template in Word or another editor before running the report. An open template can be locked and prevent report generation.

Repeat a table row for nested data

A report ViewModel can contain nested ViewModel data. To print each nested item in a table, place a row-builder tag in the first cell of the table row. The row-builder syntax is %%+ChildColumn%.

For example, assume the report has a nested column named PersonsInHouse, and each item exposes FullName. Create a table with a heading row and a data row. Put the following tags in the data row:

First cell	Second cell
`%%+PersonsInHouse%`	`%FullName%`

The reporting engine duplicates that row once for each person in PersonsInHouse and fills FullName for the current nested item.

Create an ODS spreadsheet template

Create a spreadsheet in your office editor.
Save it as an OpenDocument Spreadsheet file with the .ods extension.
Set TemplateUrl to the template URL, for example 'http://localhost:8182/content/RentBill.ods'.
Set ReportFileName to a name ending in .ods.
Add %meta% to discover available tags, then replace it with the tags required in spreadsheet cells.

Use the same tag and nested-row rules as for an ODT template. For example, a cell can contain %Rent%, and a repeated row can begin with %%+PersonsInHouse%.

Preserve numeric values in spreadsheets

OpenDocument spreadsheet tags are interpreted as text unless the report ViewModel column name uses the supported numeric naming convention. Add _float to the end of a report column name when its output must be processed as a number in Excel.

For example, expose a numeric amount as Rent_float and use %Rent_float% in the spreadsheet template. Without the numeric naming convention, Excel treats the merged cell as a string.

See Documentation:OpenDocument for the available spreadsheet naming conventions, including percentage handling.

Add an action that generates the report

Add a class action to the root class of the report ViewModel. Set its execute expression to call opendocumentreportshow.

You can supply the ViewModel name as a string:

self.opendocumentreportshow('RentBillReport')

Or use the ViewModel expression form:

self.opendocumentreportshow(BillablePeriod.ViewModels.RentBillReport)

When the user triggers the action for a BillablePeriod, MDriven builds the report ViewModel, retrieves the template specified by TemplateUrl, replaces its tags, and tries to open the resulting document.

Use opendocumentreportasblob instead when you need the generated document data as a BLOB rather than opening the report. See Documentation:OpenDocument for the method and its result.

Test the report

Start your application and open an object that matches the report ViewModel root class.
Trigger the report action.
If the template contains %meta%, inspect the generated tag list and update the template with copied tags.
Save and close the template.
Trigger the action again and verify the values, table rows, file name, and file extension.
For an .ods report, verify that amount columns intended for calculations are numeric rather than text.

Troubleshooting

Symptom	Check
Tags remain unchanged	Verify that the tag was copied exactly, has no line break or formatting inside it, and that `%meta%` was placed as the first string in its element.
The report cannot access the template	Verify the `TemplateUrl`, confirm that the template is available at that path or URL, and confirm that the file is not locked by an open office application.
Spreadsheet amounts cannot be calculated	Use the supported numeric column naming convention, such as the `_float` suffix, and use that exact column name in the template tag.
A nested table has only one row or no values	Confirm that the nested ViewModel column is populated and that the first cell of the repeated row contains `%%+ChildColumn%`.

Contents