You can generate OpenDocument text and spreadsheet reports from ViewModel data when you need a document template populated by an MDriven application.

Overview

OpenDocument reporting reads a template, replaces report tags with data from a ViewModel, and produces a document file. Use this for:

• OpenDocument Text files (.odt) such as letters and document-style reports.
• OpenDocument Spreadsheet files (.ods) such as tabular reports.
• HTML templates (.htm or .html); see HtmlReport for HTML-specific requirements.

The template can be obtained from:

• A BLOB attribute in a modeled class.
• A URL, for example a document server or a deployed content location.
• The local file system, which is useful during local development.

Build a report

Create the report data and template in this order.

1. Create an .odt or .ods template in an Office application that supports OpenDocument format.
2. Create a ViewModel that contains the values and nested data that the document needs. A ViewModel shapes model data for a particular use; here, its purpose is the report.
3. Add the report information expected by the reporting function: TemplateUrl, which identifies the template location, and ReportFileName, which gives the generated file a name including its extension.
4. Add a %meta% tag to the template and generate the report once. The resulting metadata lists the tags available from the ViewModel.
5. Copy required tags from that output into the template, including both percent signs. For example, a ViewModel column named CustomerName is referenced as %CustomerName%.
6. Create an action that calls an OpenDocument report operator with the report ViewModel.
7. Run the action and verify the generated document with the application that will open it.

For a complete worked example, including nested ViewModel data in tables, see Microsoft Office and OpenDocument as a Report generator.

Example ViewModel contract

A report ViewModel can contain ordinary report columns together with the two report-information columns:

ViewModel column	Purpose	Example value
TemplateUrl	Identifies the template to process.	c:\\temp\\mytemplate.odt during local development, or a URL to a deployed template.
ReportFileName	Names the generated file. Include the matching document extension.	CustomerLetter.odt
CustomerName	Supplies report content.	Insert in the template as %CustomerName%.

When you deploy a Turnkey application, you can place templates with the model assets and address them through the application's content URL. The training example describes the <YourModelFileName>_AssetsTK and content folder structure; follow the training guide for that deployment setup.

Generate the document from EAL

Use an EAL OpenDocument operator in the action that initiates the report.

Open the generated report

Use opendocumentreportshow when the client should try to open the generated report:

self.opendocumentreportshow(ReportRoot.ViewModels.ReportingViewmodel)

You can supply the ViewModel by name or as a ViewModel expression. For the accepted forms and behavior, see OCLOperators opendocumentreportshow.

Get the generated report as a BLOB

Use opendocumentreportasblob when subsequent logic needs the report as bytes rather than opening it in the browser:

ResultAsBlob := self.opendocumentreportasblob(ReportRoot.ViewModels.ReportingViewmodel)

This operator takes a byte array as input and returns the resulting document as a byte array. See OCLOperators opendocumentreportasblob for the operator reference.

Create and use tags

A report tag is a ViewModel-derived placeholder surrounded by percent signs. The reporting engine recognizes %meta% as a request for metadata that helps you identify valid tags.

Use %meta% to discover valid tags

1. Put %meta% in the template.
2. Ensure that %meta% is the first string in its document element.
3. Generate the report.
4. Copy a tag name from the generated metadata into the template. Copy the complete tag, including the percent signs, and avoid carrying formatting with it.

%meta% is case-sensitive. Do not insert spaces, for example % meta % is not the same tag.

Keep tags intact in the editor

Office editors can add formatting or invisible control information inside text that looks unchanged on screen. That information can prevent the reporting engine from recognizing a tag.

• Copy generated tags as plain text when possible.
• If a tag stops being replaced after editing, replace the whole tag by pasting it as plain text, including both percent signs.
• Do not split a tag across line breaks.
• In Microsoft Word, font changes, including changes that are not visibly apparent, can interfere with tag detection. Replace the affected tag with a plain-text copy.
• In Word, use text-section settings with no line breaks when line breaks would divide tag text.

OpenDocument Text (.odt)

Use .odt for text documents. Place scalar tags in the text where their values should appear. For example:

Dear %CustomerName%,

For repeating data, create the required nested ViewModel data and place the tags in a document table. The report generator can create structured output from nested ViewModel data; see the report-generator example for the table pattern.

Images in document templates

You can replace a placeholder image with image BLOB data from the ViewModel. In the template, set the placeholder image's Alt Text to the tag that identifies the image BLOB. The generated report replaces the placeholder and preserves the source image aspect ratio. This workflow is documented in Microsoft Office and OpenDocument as a Report generator.

OpenDocument Spreadsheet (.ods)

Use .ods for spreadsheet reports. Tags in spreadsheet cells are initially interpreted as text unless the ViewModel column name identifies the expected numeric interpretation.

Column-name form	Spreadsheet interpretation
Amount	String (default)
Amount_float	Number/float

For example, name a report ViewModel column Total_float when the value must be treated as a number in Excel rather than text. Apply the naming convention to the ViewModel column, then use its corresponding tag in the .ods template.

Spreadsheet compatibility note

Downloads of .ods templates created in OpenOffice 4.1.x have been observed to become corrupt. Verify that the template downloads correctly. If you create the template in Excel, also verify the downloaded document before relying on it in the application.

HTML templates

If the template name ends in .htm or .html, the reporting logic treats it as HTML and expects a well-formed HTML document. See HtmlReport instead of applying OpenDocument-specific editing guidance to an HTML template.

Troubleshoot a report

Symptom	Check
A placeholder remains unchanged	Confirm the tag was copied exactly, is case-correct, contains both percent signs, and has not been split by a line break or hidden editor formatting.
You do not know which tag to use	Put %meta% first in an element, generate the report, and copy a listed tag as plain text.
A spreadsheet value behaves as text	Rename the relevant ViewModel column with the _float suffix when it must be interpreted as a number.
The wrong template or output name is used	Check the TemplateUrl and ReportFileName values in the report ViewModel, including the file extension.
A deployed template cannot be reached	Confirm that the template is available at the configured URL and review the assets-based deployment setup in the training guide.

See also

• Documentation:Microsoft office and OpenDocument as a Report generator
• Documentation:Part 6 openDocument reports
• Documentation:OCLOperators opendocumentreportshow
• Documentation:OCLOperators opendocumentreportasblob
• HtmlReport