Tutorial

WordReport

Table of contents
  1. cplace Report Generation Basics
  2. Unsupported components
  3. Other unsupported methods
  4. Repeatable regions
    1. RepeatableRegionComponent vs. TableComponent
    2. Nesting and usage in tables
  5. Tables in Word reporting
    1. General differences
    2. Nesting tabled
  6. Replacing images
  7. Rendering HTML

cplace Report Generation Basics

Very much like the PPT report, the Word report generation takes two major ingredients:

  • a template file which contains the structure and placeholders of the document to generate
  • a script which transforms provided data and maps it to the template's placeholders

Placeholders in Word are placed entirely different than in PowerPoint. Here we don't use the alternative text of elements, but insert merge fields from Word's mail merge feature. This is due to the documents different structure on the one hand and the internally used mechanisms to replace certain elements on the other hand. Also while behaving like regular text they are as versatile as it and can be used to insert data in the middle of a sentence for example.

Besides that there are many similarities between Word and PowerPoint reporting, like the whole component API, but also some differences which we will have a closer look at here.

Something that is probably the most obvious is that Word documents do not consist of several slides with shapes on them, but have a far more fluent structure as they're meant to be read. In consequence to this the whole Slide API is not supported when working with Word reports, i.e. calls like report.addSlide() will result in an error interrupting the script execution.

Unsupported components

Due to the lack of presence of shapes in Word documents the ShapeComponent is not available as well as the ChartComponent as the reporting engine is not capable of creating charts inside of documents. This means calls to Component.createShape() and Components.createChart will result in an error when used in Word reports.

Other unsupported methods

As Word documents have a structure which is focused on readability and flow and because of technical restrictions of the reporting engine, (re-) positioning objects is also not possible. This applies to all components and means the following methods are not usable in Word reporting scripts:

  • moveX(xPosition) and respectively moveY(yPosition)
  • withX(xPosition) and respectively withY(yPosition)
  • withZIndex(index)

Repeatable regions

In Word reporting there is an additional component available: RepeatableRegion which you can use to handle - you guessed it - repeatable region placeholders in your template. It works similar like a table component with the one big difference that it's not styleable. To create a repeatable region use the new factory method Components.createRepeatableRegion() and fill it with data by creating new region containers with RepeatableRegionComponent.addRegion() and put data in them, just like you would do with rows of a table component. Here's a short example of how this could look like:

var repeatableRegion = Components.createRepeatableRegion();
for(var i = 0; i < data.length; i++) {
    var regionData = repeatableRegion.addRegion();
    // assuming data contains pages
    regionData.put('dataA', data[i].get('dataA'));
    regionData.put('dataB', data[i].get('dataB'));
    // ...
}
// do not forget to put the actual component
report.put('data', repeatableRegion);

To create a repeatable region in the template it must be enclosed with marker merge fields indicating it's start and end point. These markers look like RepeatStart:<name> and RepeatEnd:<name>. They must start with RepeatStart/RepeatEnd or else the engine won't recognize them correctly. Also the given name must match on the start and the end placeholders.

RepeatableRegionComponent vs. TableComponent

You may notice that the syntax used in the template for tables does not differ - it's both RepeatStart and RepeatEnd. However, the semantics significantly change when switching from a table component to a repeatable region component (or vice versa). Repeatable region components are not styleable at all. Also there are some differences in the behaviour of the report generation.

Nesting and usage in tables

When nesting plain regions the outer region is repeated for every nested element. This means that something like

«RepeatStart:outer» «outerData» «RepeatStart:inner» «innerData» «RepeatEnd:inner» «RepeatEnd:outer»

with outerData = [A, B] and innerData = [1, 2] will result in

 A 1 
 A 2 
 B 1 
 B 2 

Whereas the same data put in a table like

A B
«RepeatStart:outer» «outerData» «RepeatStart:inner» «innerData»«RepeatEnd:inner» «RepeatEnd:outer»

will result in

A B
A 1
2
B 1
2

with the inner data actually repeated inside the table cell rather than copying the whole table row. Be aware of the fact that repeatable regions which are nested in tables and span multiple columns will also repeat the whole table row.

A B C
«RepeatStart:outer» «outerData» «RepeatStart:inner» «innerDataA» «innerDataB» «RepeatEnd:inner» «RepeatEnd:outer»

with innerDataA = [1, 2] and innerDataB = [10, 20] will result in

A B C
A 1 10
A 2 20
B 1 10
B 1 20

Tables in Word reporting

Handling tables in Word reports is basically the same as in PPT reports. There are, however, some differences in what you can do and how you work around these limitations.

General differences

  1. Defining templates for table rows in Word reporting works different than in PPT reporting: As the engine is not able to reference a table itself in the template file you have to mark the template row start with RepeatStart:<name> and its end with RepeatEnd:<name> markers. The start tag is usually the first element in the row and the end tag the last (in the first/last table cell). Misplacing the end tag in another row or outside the table will result in the report generation failing.
    Note: You can still nest these repetitions in the template row, for e.g. listing multiple attribute values in a cell.

  2. Table headers in Word reports cannot be managed using the TableComponent due to technical reasons. The methods withHeader() and withHeaderRow() are disabled in that context. But that does not mean this is impossible. You can still modify table headers "manually", meaning replacing content outside a component as the following example showcases:

    // assume there are 2 table columns with the placeholders "col_a" and "col_b"
    // we first replace these headers
    report.put("col_a", "Name");
    report.put("col_b", "Age");
    // now fill data
    for(var i = 0; i < pages.length; i++) {
        // ...
    }
    
  3. Table growth in Word reports is not controllable by allowGrowth() or withMaximumHeightPerSlide() - these methods are disabled in that context. Tables in Word reports always grow automatically. You don't have to worry about table misplacement or missing header though. The reporting engine takes care of breaking to new pages and also repeating table headers when necessary.

  4. Multiple template rows are not configurable in the TableComponent for Word reporting - the method withNumberOfTemplateRows() is disabled in that context. This does mean that complex tables with multiple template rows cannot be configured.

Nesting tables

Besides that there is also something which exclusively work for Word reporting:
It is possible to create nested tables in Word reports. Just create a table inside a table cell and set up placeholders. You can then just create an inner table for every row of the outer table in the script and fill in data as usual.

Replacing images

Important note: When defining image dimensions in your template be sure to use either % or pt! px will not work, but render the image in its actual size.

When placing images in table cells you have to apply scale/size and alignment in the template by changing the appropriate image parameter, or - in case of the alignment - align the text in the cell. Unfortunately it is not possible to align images independently from other cell content. The CellFormatComponent.withImageAlignment(), CellFormatComponent.withImageScaling() and CellFormatComponent.withoutImageScaling() methods are disabled in the Word reporting context.

To let text flow around an image you can set up a decoupled text box and fill in an image placeholder. Keep in mind to size the box according to the image which it is representing. You can then select the text element and set the desired text wrapping. The placeholder in the text box will then be replaced by the image. Also keep in mind that you may have to align the text inside the box to achieve the desired result.

Rendering HTML

Word reports are capable of rendering html into a file. This can be very handy when handling rich text attributes or wiki widgets. While exporting their content you can even preserve the looks of it. To do so use the asHtml() method of the TextComponent. This method is Word exclusive, i.e. it will fail in any other report context. Here is a short example of how to export the content of a page's wiki widget:

var wikiContent = Components.createText()
  .withText(page.getBuiltinFeatureValue('content')) // retrieve the contents of the wiki widget
  .asHtml();

report.put('wikiContent', wikiContent);

With the help of this mechanism you can easily export whole documentation workspaces which utilize those widgets by just iterating over the pages and rendering their contents into a file.