Formatters

When band data is loaded and structured, we need to describe how to create resulting document. Yarg introduces an 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 provides 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 the loaded bands. For instance, report has two bands - Header and Data. This means that template should also have Header and Data named ranges.
2. Vice versa, each part of the 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.

Also bands are organized in tree-like structure, so some bands can be nested to another (these bands are called children bands). Xlsx formatter render children bands using the following algorithm:

1. Write the first row of parent band.
2. Write all first row's children rows.
3. Write the next row of parent band.

See the example of usage children bands: template, Java code, [report xml] (/Haulmont/yarg/blob/master/core/modules/core/test/sample/financedetails/breakdown.xml).

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

[Xlsx charts] (/Haulmont/yarg/wiki/Xlsx-Charts-creation)

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

Inlining html

Inlining html is not supported for both xlsx and xls templates.

Inlining images

The images 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 replaces ${BandName.fieldName} aliases with values from suitable band. You can also provide a detailed path to certain band using the following alias format ${ParentBand.ChildBand.fieldName} (this can be useful if you have duplicated band names in different levels of hierarchy).

Docx template also supports growing tables. You should add ##band=BandName marker to the first cell of table to link table with some band. Then you can place ${fieldName} aliases to the table and they will be automatically replaced with the 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 take the 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 two 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 should create a field format for field which contains binary data. Format should have the 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 should create a field format for field which contain image URL. Format should have the following form - ${image:WIDTHxHEIGHT} where WIDTH and HEIGHT is integer values.

3. You can also 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 similar featiures and requirements as [xlsx formatter] (/Haulmont/yarg/wiki/Formatters#xlsx-formatter). The only difference is that xls formatter does not support charts.

Doc formatter

Doc formatter has similar features and requirements as [docx formatter] (/Haulmont/yarg/wiki/Formatters#docx-formatter).

Warning

DocFormatter uses OpenOffice API to create reports. If you need to produce doc or odt templates - you must 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

TODO

CSV formatter

TODO

Jasper formatter

TODO