You can generate a Word-style OpenDocument report from an MDriven Turnkey application by defining a report ViewModel, uploading an OpenDocument template as a site asset, and calling it from an action on the source object.

What you build

This session creates a report for a rental contract. The same pattern applies to invoices, agreements, confirmation letters, and spreadsheet-style reports.

The report has three parts:

Part	Purpose	Rental-contract example
Report ViewModel	Defines the data that MDriven makes available to the report.	ReportRentalContract, rooted in RentalContract
OpenDocument template	Controls the document layout and contains the generated report tags.	An .odt template with a heading, contract values, and a signature line
Action	Opens the report for the currently selected source object.	GetRentalContract on the rental-contract ViewModel

The report data comes from the report ViewModel. You can add ordinary columns, navigate associations, and add nested data in the same way as in other ViewModels. The template determines how that data is presented.

Prerequisites

Before you start, make sure that:

• You have a ViewModel that presents the object from which users will request the report. In this example, it is a rental-contract ViewModel.
• You know which values the document must show. For example, renter name, selected car, rental dates, and contract details.
• You can upload a file as a Turnkey site asset.

For the broader OpenDocument-report workflow and a Designer exercise, see Training:Bootcamp:Chapter 10 and Documentation:Microsoft office and OpenDocument as a Report generator.

Create the report ViewModel

1. In MDriven Designer, create a new ViewModel named ReportRentalContract.
2. Set its class to RentalContract.
3. Add the values that the document needs. Add columns directly from the rental contract or navigate through associations when the value belongs to a related object.
4. Right-click the ViewModel tree and choose the command to add the columns needed for a report.
5. Verify that the ViewModel now includes the report-specific columns:
   • ReportFileName
   • TemplateUrl
6. Set Use placing hints to No. A report ViewModel supplies data to a document template; it does not need generated UI layout hints.

You can include any data that can be reached from the report root. For example, a rental-contract report can include data from the contract, its renter, and its selected car. Keep the report ViewModel focused on the document: do not add columns that the template will not use.

Set the output filename

ReportFileName is an expression, so you can build a meaningful filename from report data.

For a word-processing report, the resulting filename must end in .odt. OpenDocument spreadsheets use .ods instead.

For example, construct a filename from a contract identifier and the .odt extension. The exact expression depends on the attributes in your model.

Identify the template

Set TemplateUrl to the name of the template asset that you will upload to the Turnkey site. Use the same asset name consistently in the ViewModel and when you upload the file.

Add an action that generates the report

Add an action to the ViewModel where users work with rental contracts.

1. Select the rental-contract ViewModel.
2. Add a ViewModel action named, for example, GetRentalContract.
3. Set its execute expression to call opendocumentreportshow for the current rental contract and the report ViewModel:

self.opendocumentreportshow(ReportRentalContract)

1. Save and upload the model.

The action uses the current rental contract as the report root. When a user runs the action, Turnkey creates the document from the report ViewModel data and the uploaded template.

Create the OpenDocument template

Create the template in an OpenDocument-compatible word processor and save it as an .odt file.

1. Generate a report once while the template contains the special meta tag.
2. Open the generated document. The meta tag expands to the available tags from the report ViewModel.
3. Use those generated tags to identify the values that you can place in the template.
4. Replace the exploratory meta output with the tags needed by your document.
5. Arrange the tags and static text as required, then save the file as .odt.

For example, place a report title at the top, add contract and renter values in the body, and add a static Sign here line at the end. You can use normal word-processing layout and styles, including headers and images. The available tags are determined by the report ViewModel, so add missing data to that ViewModel before editing the template further.

Format values in the ViewModel

Format values before they reach the template when the default representation is not suitable.

For example, if a date appears in an unwanted regional format, update the corresponding report column expression to use toString with formatting options. Save and upload the model, then generate the report again to verify the result.

Upload the template as a site asset

The template must be present on the Turnkey site before the action can generate the report.

1. Sign in to the site-management area and open your Turnkey site's assets.
2. Create a new asset and select the .odt template file.
3. Give the asset the name used by TemplateUrl in the report ViewModel.
4. Save the asset and send it to the site.
5. Generate a report to confirm that Turnkey finds the template.

During template development, use the CloudForm Asset Refresh facility to upload a revised file after the asset already exists. This avoids recreating the asset for every layout change.

Test the report

1. Start the Turnkey application.
2. Create or open a rental contract with the data required by the report, such as a selected car and rental dates.
3. Run GetRentalContract.
4. Allow the browser popup if the browser blocks it.
5. Inspect the generated .odt document.
6. Update the ViewModel, template, or both until the document contains the intended data and layout.

Troubleshooting

Symptom	Check
No report window opens	Check whether the browser blocked a popup. Allow popups for the application site and run the action again.
The template is not used	Confirm that the template has been uploaded as a site asset, sent to the site, and named exactly as specified by TemplateUrl.
A needed tag is unavailable	Add the required column or navigation to the report ViewModel. Regenerate the template with meta to see the updated available tags.
A date displays in the wrong format	Format the date in the report ViewModel column expression with toString formatting options, then upload the model and test again.
The report lacks data from a related object	Check the report ViewModel expression. Navigate from self through the intended association; avoid an expression that starts with all instances when you mean the current report root.

See also

• Documentation:MDriven Turnkey Series
• Training:Bootcamp:Chapter 10
• Documentation:Microsoft office and OpenDocument as a Report generator
• Documentation:Turnkey session 9: View Override
• Documentation:Turnkey Session 11: More on View Override