View source for Documentation:HtmlReport

You can generate XHTML, HTML-shaped output, or XML from a [[Documentation:ViewModel Editor|ViewModel]] by placing ViewModel values into an XHTML/XML template; use this page when you need a data-driven report as a string, BLOB, or browser output.
== Overview ==
'''HtmlReport''' processes a template and replaces tags with data from a ViewModel. The result is XHTML as a string or BLOB, or it can be opened in the browser.

The report processor works with XHTML and XML. XHTML is XML-compatible HTML and has one root node. This matters because the template is processed as a DOM (Document Object Model): tags must occur inside valid XML/XHTML nodes to be found and replaced.

HtmlReport shares much of its processing logic with [[Documentation:OpenDocument|OpenDocument]] reporting. Use HtmlReport when your output is XHTML or XML; use OpenDocument when you need an OpenDocument file such as an ODT or ODS template.
== What you need ==
# A '''report ViewModel''' that exposes the values to insert and, where applicable, identifies the template location.
# An XHTML or XML '''template''' containing report tags.
# An [[Documentation:Learn OCL|OCL]] or EAL expression that invokes the appropriate report operation.

A ViewModel is the contract between the template and your model. If the template contains <code>%Customername%</code>, the report ViewModel must provide a column named <code>Customername</code> in the relevant ViewModel context.

The report ViewModel can supply the template through either of these attributes:
{| class="wikitable"
|'''Attribute name'''
|'''Attribute should evaluate to'''
|'''Value type and content'''
|-
|TemplateHtml
|A string that contains Html
|Not encoded in any special way
|-
|TemplateUrl
|The URL or local filename
|String with for example http://www.mdriven.net/templates/report.odt or for prototyping c:\\temp\\mytemplate.odt
|-
|TemplateBlob
|A class attribute containing the template
|Blob with an uploaded document template, value is expected to be Base64 encoded
|-
|ReportFileName
|A string with a filename
|Not used by XHtmlReportAsString but needed for opendocumentreportasblob
|}
== Create a basic HTML report ==

=== 1. Create the report ViewModel ===

In [[Documentation:ViewModel Editor|ViewModel Editor]], create a ViewModel that obtains the report root object and add the columns required by the template.

For example, a report ViewModel can expose these scalar columns:

{| class="wikitable"
! ViewModel column
! Example value
! Template tag
|-
| <code>String</code>
| <code>John</code>
| <code>%String%</code>
|-
| <code>Text</code>
| <code>Thank you for your order.</code>
| <code>%Text%</code>
|}

The ViewModel also supplies the information needed to retrieve the template. A template can be retrieved from:

* A String attribute in a modeled class.
* A BLOB attribute in a modeled class. The BLOB content is Base64 encoded.
* A URL.
* The local file system.
=== 2. Create a well-formed template ===

Put each scalar ViewModel column name between percent signs. The following template replaces <code>%String%</code> and <code>%Text%</code> with the corresponding ViewModel values:

<syntaxhighlight lang="html">
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <body>
    <p>Hello %String%</p>
    <p>%Text%</p>
  </body>
</html>
</syntaxhighlight>

For the example values above, the report output includes:

<syntaxhighlight lang="html">
<html>
  <body>
    <p>Hello John</p>
    <p>Thank you for your order.</p>
  </body>
</html>
</syntaxhighlight>
=== 3. Run the report ===

Use the report operation that matches the input and desired output. In the following examples:

* <code>self</code> becomes the root object of the reporting ViewModel.
* <code>ReportRoot</code> is the class that owns the reporting ViewModel.
* <code>ViewModels</code> retrieves the class ViewModels.
* <code>ReportingViewmodel</code> is the report ViewModel name.
== Choose a report operation ==

{| class="wikitable"
! Operation
! Use it when
! Result
|-
| <code>XHtmlReportAsString</code>
| Your template input is a string and you need XHTML as a string.
| A string. No Base64 encoding of input HTML is required.
|-
| <code>opendocumentreportasblob</code>
| Your template and output are handled as byte arrays.
| A BLOB. Content is UTF-8 encoded and Base64 formatted.
|-
| <code>opendocumentreportshow</code>
| You want to generate the BLOB-based report and open the resulting HTML in the browser.
| Browser output.
|}
=== Return XHTML as a string ===

<syntaxhighlight lang="text">
ResultHtmlAsString := self.XHtmlReportAsString(ReportRoot.ViewModels.ReportingViewmodel)
</syntaxhighlight>

<code>XHtmlReportAsString</code> is the easiest option when the template is already a string. For operator-specific information, see [[Documentation:OCLOperators XHtmlReportAsString]].
=== Return XHTML as a BLOB ===

<syntaxhighlight lang="text">
ResultHtmlAsBlob := self.opendocumentreportasblob(ReportRoot.ViewModels.ReportingViewmodel)
</syntaxhighlight>

For BLOB processing, content must be UTF-8 encoded and in Base64 format. Use <code>BlobToBase64</code> to obtain a Base64 string from a BLOB, or <code>StringToBase64</code> to obtain one from a String. The resulting Base64 string is then used as the BLOB content.
=== Open the report in the browser ===

<syntaxhighlight lang="text">
self.opendocumentreportshow(ReportRoot.ViewModels.ReportingViewmodel)
</syntaxhighlight>
== Insert scalar values ==

A scalar tag is a ViewModel column name surrounded by percent signs:

<syntaxhighlight lang="html">
<p>Invoice date: %Date%</p>
<p>Customer: %Customername%</p>
</syntaxhighlight>

If the current ViewModel object has <code>Date</code> and <code>Customername</code> columns, each tag is replaced by that column's value. You can use the same tag more than once in the template.
== Repeat markup for a multi-link ==

A '''multi-link''' is a ViewModel relationship that supplies multiple objects. Mark the containing XML/XHTML element with <code>%%+MultiLinkName%</code> to repeat that element once for every object in the multi-link.

For example, if <code>Invoices</code> is a multi-link and every invoice provides <code>Date</code> and <code>Customername</code>, place the repeat tag in the table row:

<syntaxhighlight lang="html">
<table>
  <tbody>
    <tr>
      <td>Date</td>
      <td>Customer</td>
    </tr>
    <tr>%%+Invoices%
      <td>%Date%</td>
      <td>%Customername%</td>
    </tr>
  </tbody>
</table>
</syntaxhighlight>

The processor repeats the <code>&lt;tr&gt;</code> element, including its contents, for each object in <code>Invoices</code>. Within the repeated row, <code>%Date%</code> and <code>%Customername%</code> are evaluated for the current invoice.
== Render a collection of strings ==

A collection of strings needs a small ViewModel wrapper so that every string can be addressed as a value during repetition.

# Create a ViewModel column that returns the collection of strings. For example, it may return values produced from a comma-separated list.
# Create another ViewModel class without setting its type; it is derived from ViewModel.
# Add a column in that ViewModel class with <code>self</code> as its expression. This column represents the current string value.
# Repeat the collection in the template and insert the current value column.

For example:

<syntaxhighlight lang="html">
<p>%%+Viewmodel.AttributeOfCollection% %NameOfValueAttribute%</p>
</syntaxhighlight>

The processor iterates <code>Viewmodel.AttributeOfCollection</code> and fills <code>%NameOfValueAttribute%</code> for each string.
== Use HTML and XML templates safely ==
XHTML is a strict version of HTML that is XML-compatible. More importantly, it always has one, and only one, root node. '''Read more here:''' https://en.wikipedia.org/wiki/XHTML
=== Provide one document root ===

Use a well-formed XHTML or XML document with one root node. Valid XHTML typically uses an <code>&lt;html&gt;</code> root and places visible content inside <code>&lt;body&gt;</code>.

<code>XHtmlReportAsString</code> attempts to compensate when a template has no <code>&lt;root&gt;</code>, <code>&lt;body&gt;</code>, or <code>&lt;html&gt;</code> element. For example, this fragment has two top-level elements:

<syntaxhighlight lang="html">
<p>Hello %String%</p>
<p>You need to do this....</p>
</syntaxhighlight>

The operation adds an <code>&lt;html&gt;</code> wrapper:

<syntaxhighlight lang="html">
<html>
  <p>Hello John</p>
  <p>You need to do this....</p>
</html>
</syntaxhighlight>

Treat this wrapping as a fallback. Author a complete, single-root XHTML template when you control the template.
=== Put tags inside valid elements ===

The DOM processor only sees valid nodes. A tag that is not inside a valid element may not be detected or replaced.

Use a containing element:

<syntaxhighlight lang="html">
<html>
  <p>%myTag%</p>
</html>
</syntaxhighlight>

Do not rely on the <code>&lt;html&gt;</code> element alone to make an otherwise invalid fragment usable. If tags are left unchanged in the output, validate the XHTML/XML structure first and ensure that the tag occurs inside a valid node.
=== Generate XML ===
The same tag and repeat logic applies to XML. You can use tags in element text and attributes, and repeat an XML element for a multi-link:

<syntaxhighlight lang="xml">
<SomeXml attrib='%SomeVMColumnAsAttributeresult%'>
  %SomeOtherVMColumnAsXMLTextresult%
  <Items>
    <Item>%%+TheVMNestingColumn%
      <ContentInItem someattrib='%VMColInNesting%'>
        %StuffFromViewModelNesting%
      </ContentInItem>
    </Item>
  </Items>
</SomeXml>
</syntaxhighlight>

In this example, <code>%SomeVMColumnAsAttributeresult%</code> supplies an attribute value, and the <code>&lt;Item&gt;</code> element repeats for each object in <code>TheVMNestingColumn</code>.

XML is the more generic case of HTML. They are treated by the same logic.
<pre>
 <SomeXml attrib='%SomeVMColumnAsAttributeresult%'>
     %SomeOtherVMColumnAsXMLTextresult%
   <Items>
     <Item>%%+TheVMNestingColumn%
       <ContentInItem someattrib='%VMColInNesting%'>
          %StuffFromViewModelNesting%
       </ContentInItem>
     </Item>
   </Items>
 </SomeXml> </pre>
== Discover the available tags ==

Use <code>%meta%</code> while developing a template to obtain the exact tags available from the report ViewModel.

# Add <code>%meta%</code> as the first string in an element.
# Run the report.
# Copy the generated tag names, including their percent signs, into the template.

For HTML, use a holder element such as:

<syntaxhighlight lang="html">
<meta>%meta%</meta>
</syntaxhighlight>

A generated result can contain a list such as:

<syntaxhighlight lang="html">
<html>
  <meta>%TemplateHtml%, %TemplateBlob%, %ReportFileName%, %String%, %Text%,</meta>
</html>
</syntaxhighlight>

The <code>%meta%</code> token must be the first string in its element to be recognized. Use the generated spelling and casing exactly when creating tags.
== Troubleshooting ==

{| class="wikitable"
! Symptom
! Check
|-
| Tags remain as <code>%Name%</code> in the output.
| Confirm that the ViewModel provides a column named <code>Name</code>, that the tag is in a valid XHTML/XML element, and that the template has a valid document structure.
|-
| A repeated row or element does not appear.
| Confirm that the multi-link name in <code>%%+MultiLinkName%</code> matches the ViewModel multi-link and that the multi-link has objects to iterate.
|-
| You do not know the tag spelling.
| Add <code>%meta%</code> as the first string in an element, run the report, and copy the generated tags.
|-
| The template is plain HTML from an editor.
| Check that it has one root node and is well-formed enough for DOM processing. Prefer XHTML/XML when possible.
|-
| You need report-generated HTML inside a user interface.
| See [[Documentation:Column.DataIsHtml]]. A column marked <code>DataIsHtml</code> can use HTML directly, including HTML produced through HtmlReport.
|}
== Report templates and ViewModel data ==

HtmlReport creates output by processing an XHTML template and adding data from a ViewModel. The resulting XHTML can then be returned as a string or handled as blob-based content, depending on the function used.

To prepare an HtmlReport:
# Create a ViewModel that extracts the data needed for the report.
# Provide an XHTML template containing tags that correspond to attributes in the ViewModel.
# Configure where the template is retrieved from. Templates can be retrieved from a string attribute, a base64-encoded BLOB attribute, a URL, or the local filesystem.
# Use the applicable HtmlReport function for the input and output format.

The same functionality also applies when XML is needed. XHTML is required to have one root node.
== Authoring and self-service reporting ==
This page documents template-based report generation using a ViewModel and XHTML or XML input. It does not, in the available documentation, describe who is expected to author report templates or whether users can create or modify reports at runtime.

For requirements involving end-user report design, ad hoc data selection, dashboards, report security, or external reporting tools, verify the supported approach for the relevant MDriven version before making an implementation decision.
=== Usage ===

Example of a ViewModel that extracts two attributes to be used, "String" and "Text":
[[File:ReportingTemplate.png|none|thumb|417x417px]]

== See also ==
* [[Documentation:OCLOperators XHtmlReportAsString]]
* [[Documentation:OpenDocument]]
* [[Training:Microsoft office and OpenDocument as a Report generator]]
* [[Documentation:Column.DataIsHtml]]
* [[Documentation:ViewModel Editor]]
* ViewModel documentation
* OpenDocument functionality

[[Category:Data Import & Export]]
[[Category:Exporting Data and Reports (Excel, PDF)]]
[[Category:Integration]]
[[Category:Intermediate-Friendly]]
[[Category:Priority 60]]