Formatters

When band data is loaded and structurized, we need to describe how to create resulting document. Yarg introduces and abstraction named com.haulmont.yarg.formatters.ReportFormatter, which is a simple description of class that can create some binary document. You can implement any logic in your own formatters. Also you can extend com.haulmont.yarg.formatters.impl.AbstractFormatter class, which contains many usable features for formatters.

By default, Yarg provide several types of formatters.

Xlsx formatter

This formatter can process xlsx template files.

There are several requirements for template

1. Template should contain named regions for each of loaded bands. For instance, report has 2 bands - Header and Data. This means that template also should have Header and Data named ranges.
2. Vice versa, each part of sheet you want to show should be a band in report (at least an empty band).
3. Named range should contain placeholders (${fieldName}), describing which data should be loaded there.

As you know from Structure bands can be horizontally and vertically oriented. If band is horizontal - suitable named region will grow downward, vertical will grow rightward.

Xlsx formatter supports formulas and charts. All formulas and charts should be placed in named ranges linked with bands.

[The quick start guide] (/Haulmont/yarg/wiki/Quick-start#xlsx-report) contains a simple example of report creation.

Inlining images

The image inlining mechanism for xlsx formatter is similar to mechanism for docx described [here]. (/Haulmont/yarg/wiki/Formatters#inlining-images)

Docx formatter

This formatter can process docx template files.

Docx formatter basically replaces ${BandName.fieldName} aliases with value from suitable band. You also can provide a detailed path to certain band using following alias ${ParentBand.ChildBand.fieldName} (if you have duplicated band names in different levels of hierarchy).

Docx template also supports growing tables. To link table with some band you should add ##band=BandName marker to first cell of table. Then you can place ${fieldName} aliases to the table and they will be automatically replaced with values from suitable band.

[The quick start guide] (/Haulmont/yarg/wiki/Quick-start#docx-report) contains a simple example of report creation

Inlining html

Docx formatter allows you to put html to certain alias place. You should do following steps

1. Load html into some band's field
2. Create a field formatter which points to this field and has ${html} as format value.

You can see an example of html inlining in [quick start] (/Haulmont/yarg/wiki/Quick-start#template-1) (the field ${Main.signature}).

Inlining images

There are 2 ways to inline image into docx and doc templates.

1. Load binary content to band and inline it as binary data. To use this ability you have to create a field format for field which contain binary data. Format should has following form - ${bitmap:WIDTHxHEIGHT} where WIDTH and HEIGHT is integer values.

2. Load URL to band and inline image using URL. To use this ability you have to create a field format for field which contain image URL. Format should has following form - ${image:WIDTHxHEIGHT} where WIDTH and HEIGHT is integer values.

3. You also can create and register your own content inliner. See the list com.haulmont.yarg.formatters.impl.AbstractFormatter#contentInliners where you can add your own inliners during formatter construction.

Xls formatter

Xls formatter has the similar abilities and requirements with [xlsx formatter] (/Haulmont/yarg/wiki/Formatters#xlsx-formatter). The only difference is that xls formatter does not support charts.

Doc formatter

Doc formatter has the similar abilities and requirements with [docx formatter] (/Haulmont/yarg/wiki/Formatters#docx-formatter).

Attention

DocFormatter uses OpenOffice API to create reports. If you need to deal with doc or odt templates - you have to install OpenOffice or LibreOffice

How to integrate

There are several ways to setup integration with Open Office in Yarg.

1. Pass com.haulmont.yarg.formatters.impl.doc.connector.OfficeIntegrationAPI implementation to doc formatter's construnctor.

OfficeIntegrationAPI officeIntegration = new OfficeIntegration("/usr/lib/openoffice/program", 8100, 8101)
DocFormatter docFormatter = new DocFormatter(factoryInput, officeIntegration);

2. If you use com.haulmont.yarg.formatters.factory.DefaultFormatterFactory, you can set officeIntegration to the factory.

OfficeIntegrationAPI officeIntegration = new OfficeIntegration("/usr/lib/openoffice/program", 8100, 8101)
DefaultFormatterFactory factory = new DefaultFormatterFactory();
factory.setOfficeIntegration(officeIntegration);

3. If you use Yarg from console - you should fill office path and ports in properties file

cuba.reporting.openoffice.path=/usr/lib/openoffice/program
cuba.reporting.openoffice.ports=8100,8101

Html formatter