-
Notifications
You must be signed in to change notification settings - Fork 74
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.
This formatter can process xlsx template files.
There are several requirements for template
- 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.
- Vice versa, each part of the sheet you want to show should be a band in report (at least an empty band).
- 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:
- Write the first row of parent band.
- Write all first row's children rows.
- Write the next row of parent band.
See the example of usage children bands: template, Java code, report xml.
Xlsx formatter supports formulas and charts. All formulas and charts should be placed in named ranges linked with bands.
The quick start guide contains a simple example of report creation.
Inlining html is not supported for both xlsx and xls templates.
The images inlining mechanism for xlsx formatter is similar to mechanism for docx described here
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 contains a simple example of report creation
Docx formatter allows you to put html to certain alias place. You should take the following steps
- Load html into some band's field
- 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 (the field ${Main.signature}).
There are two ways to inline image into docx and doc templates.
-
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.
-
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.
-
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.
CSV formatter allows to use CSV template and produce CSV reports. This formatter produces one table. It is expected to have one entity per report. Template accepts two lines:
- Header, that describes columns
- Aliases to replace fields of given entity and to provide order of columns.
Example of a csv template.
Template supports any common separators i.e. comma, semi-colon, and wrappers i.e. quotes.
Jasper formatter allows to use Jasper-kind templates *.jrxml, *.jasper as input and output types pdf, html, csv, doc(actual format is rtf), docx, xls, xlsx.
As YARG uses its own data generator, we wrote our own Jasper data source: JRBandDataDataSource
which contains data as tree with root band
as the root.
It is not necessary to declare it explicitly in the report, it is passed as main data source.
To simplify usage of datasources and remove long package names at the report,
the CubaJRFunction
class is passed to report as REPORTING
parameter. It is not necessary to declare
this parameter in the report template, YARG adds it if it is omitted. But if you are going to compile
template at Jasper IDE you need to declare this parameter.
CUBA parameter supports two functions:
-
dataset
which gets subDatasource from main datasource with the same Class and can be used i.e. at tables or subreports as subDataset. This method searches at children of the root band for the band with specified name and creates a new datasource with this band as a new root. Example:
<subDataset name="Dataset2" uuid="6e7a11ea-d592-4182-8f91-8769b4da1f73">
<field name="name" class="java.lang.String"/>
<field name="price" class="java.lang.Integer"/>
</subDataset>
...
<dataSourceExpression><![CDATA[$P{REPORTING}.dataset("Dataset2")]]></dataSourceExpression>
-
bitmap
which transforms given byte array into ByteArrayInputStream and cat be used to put images into the report. Example:
<field name="Main.image" class="java.lang.Object"/> //brought from DB as byte array
...
<imageExpression><![CDATA[$P{REPORTING}.bitmap($F{Main.image})]]></imageExpression>
Example of a jasper template.
TODO
Xls formatter has similar featiures and requirements as xlsx formatter. The only difference is that xls formatter does not support charts.
Doc formatter has similar features and requirements as docx formatter.
DocFormatter uses OpenOffice API to create reports. If you need to produce doc or odt templates - you must install OpenOffice or LibreOffice.
YARG also can use OpenOffice API to convert XLSX, XLS, DOCX, DOC, ODT documents to PDF.
There are several ways to setup integration with Open Office in Yarg.
- 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);
- 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);
- If you use Yarg from console or as standalone server - you should fill office path and ports in properties file
cuba.reporting.openoffice.path=/usr/lib/openoffice/program
cuba.reporting.openoffice.ports=8100,8101