-
Notifications
You must be signed in to change notification settings - Fork 75
Home
This library has been developed to simplify reports generation. In short, it allows to create a template in most common formats (doc, docs, xls, xlsx, html, ftl, csv) or a custom text format and fill it with data loaded by sql, groovy or other means.
Yarg introduces generic report structure, describing how to load data, how to structurize it, how to convert it and how to show it to user. Details are in Data structure section.
Yarg splits report generation process into several steps - data loading, data conversion, templates filling. On each step you can select certain sort of actions to do. So each of these steps introduces a concept in the library: data loading introduces ReportDataLoader abstraction, data conversion introduces ReportFieldsConverter abstraction, templates filling introduces ReportFormatter abstraction. This is descibed in Data loaders and Formatters sections.
From our point of view the main trend of software engineering today is reducing the costs of development. By cost we mean time spent by developers on support existing code or writing it from scratch. This library has been developed to simplify a very common task - report generation.
We have developed our own reporting engine (as part of our CUBA platform), because no free solution we could find has satisfied the requirements of our projects in terms of features and flexibility. These projects are usually enterprise applications (like document management, automation or information systems).
- Yarg is a ready solution, used in most of our projects.
- Yarg offers more than template processing, it can also manage data loading and transformation.
- Yarg allows users to use world standard applciations to create report templates: MS Excel and Word as well as surely OpenOffice/LibreOffice.
- Yarg has same rules for all supported formats: xls, xlsx, doc, docx, odt, html, ftl. This allow you to change template or data loader type, and report will work fine.
- Yarg allows to extend, override or add new functionallity.
- Yarg has simple console interface which allows to use it outside of Java world. For more information please see the topic.
- Yarg has simple REST server which allows to use it as a standalone service. For more information please see the topic.
- Yarg allows you to store report structure in simple xml (which allows to store reports in VCS).
- Yarg uses Groovy and it allows you to change complex reports logic at runtime.
- Yarg is fully embeddable. It can deal with any dependency injection frameworks (Spring, Guice, etc).
- The main use case for Yarg is using it as an embedded reporting engine in your application. It does not have a visual interface, but its data structure is simple so that if needed, you can easily create the interface using UI framework and design approach of your choice.
Yarg versions are distributed using Nexus repository: https://repo.cuba-platform.com/content/groups/work/
There are two release lines:
- 2.0+ version requires Java 8. Java 12 isn't supported.
- 1.0+ version requires Java 6.
You can find the complete list of versions here: https://repo.cuba-platform.com/content/groups/work/com/haulmont/yarg/
Gradle:
repositories {
maven {
url "https://repo.cuba-platform.com/content/groups/work/"
}
}
...
dependencies {
compile 'com.haulmont.yarg:yarg:2.2.14'
}Maven:
<repositories>
<repository>
<snapshots>
<enabled>false</enabled>
</snapshots>
<id>repo-cuba-platform-work</id>
<name>repo</name>
<url>https://repo.cuba-platform.com/content/groups/work</url>
</repository>
</repositories>
...
<dependency>
<groupId>com.haulmont.yarg</groupId>
<artifactId>yarg</artifactId>
<version>2.2.14</version>
<type>pom</type>
</dependency>We use Gradle to build YARG. You don't need to download and install it.
Just run gradlew assemble in the ./core folder (it contains build.gradle file). Appropriate version of Gradle will be downloaded automatically. Java 12 isn't supported.
The resulting jar file will be placed to the ./core/build/libs folder.
Report is an object constructed from several parts.
- ReportParameters are user defined parameters for data loading and report generation. The values for those parameters should be provided when report is invoked.
- ReportBands are tree organized (parent - children) entities which describe how to load data to fill some template region.
- ReportQueries are contained within bands and describe certain query (sql, groovy, etc)
- ReportTemplates are documents (doc,docx,xls,xlsx,html or any other text format) with special markup.
- ReportFieldFormats convert loaded data into appropriate format (date format, decimal format, etc).
Data loaders load data which will be inserted into file template.
The result of data loader's work is list of rows containing some data.
There are several types of loaders provided by Yarg by default.
This data loader loads data from SQL-compatible databases. See example below.
select u.user_name as name, u.user_login as login, u.user_email as email
from users u
where u.create_date < ${param1}This query select user's name, login and email for all users created before param1 date.
This data loader uses groovy to load arbitrary data from anywhere. See example below.
return [[
'name':'John Doe',
'login':'jdoe',
'email':'[email protected]'
]]This data loader can load data from arbitrary JSON structure using JsonPath. You can see more details here.
Yarg provides following formatters by default: DocFormatter, DocxFormatter, HtmlFormatter, XLSFormatter, XlsxFormatter, HtmlFormatter, CsvFormatter - each processing corresponding type of template file. Additionally, Yarg supports integration with JasperReports library, so you can create templates in Jasper and use them in Yarg.
Template files contain special placeholders describing the data which they will be replaced with. Placeholders can have the following forms ${fieldName}, ${BandName.fieldName}