Skip to content

Home

Jump to bottom
Eugene Degtyarjov edited this page Nov 8, 2013 · 83 revisions

Introduction to Yarg

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] (/Haulmont/yarg/wiki#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] (/Haulmont/yarg/wiki#data-loaders) and [Formatters] (/Haulmont/yarg/wiki#formatters) sections.

See the quick start

Why should I use this library?

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] (https://www.cuba-platform.com/) 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).

  1. Yarg is a ready solution, used in most of our projects.
  2. Yarg offers more than template processing, it can also manage data loading and transformation.
  3. Yarg allows users to use world standard applciations to create report templates: MS Excel and Word as well as surely OpenOffice/LibreOffice.
  4. 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.
  5. Yarg allows to extend, override or add new functionallity.
  6. Yarg has simple console interface which allows to use it outside of Java world.
  7. Yarg allows you to store report structure in simple xml (which allows to store reports in VCS).
  8. Yarg uses Groovy and it allows you to change complex reports logic at runtime.
  9. Yarg is fully embeddable. It can deal with any dependency injection frameworks (Spring, Guice, etc).
  10. 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.

How to include binaries to my project?

  1. You should add our maven repository to your project: [https://repo.cuba-platform.com/content] (https://repo.cuba-platform.com/content) (cuba/cuba123)

  2. You should add the following dependency to your project

<dependency>
  <groupId>com.haulmont.yarg</groupId>
  <artifactId>yarg</artifactId>
  <version>1.0.5</version>
</dependency>

How to build it from sources?

The only thing you need to build Yarg is installed [Gradle 1+] (http://www.gradle.org/).

When you have installed it, just run gradle assemble in the folder containing build.gradle file.

The resulting jar file will be placed to the ./core/build/libs folder.

Data structure

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).

See more about data structure

Data loaders

Data loaders load data which will be inserted into file template.

The result of data loader's work is tree-like structure of bands. Each report band from report transforms to one or more bands (depending on how much rows return certain report query).

There are several types of loaders provided by Yarg by default.

SqlDataLoader

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.

GroovyDataLoader

This data loader uses groovy to load arbitrary data from anywhere. See example below.

return [[
'name':'John Doe',
'login':'jdoe',
'email':'johndoe@gmail.com'
]]

See more about data loaders

Formatters

Yarg provides following formatters by default: DocFormatter, DocxFormatter, HtmlFormatter, XLSFormatter, XlsxFormatter - each processing corresponding type of template file.

Template files contain special placeholders describing the data which they will be replaced with. Placeholders can have the following forms ${fieldName}, ${BandName.fieldName}

See more about formatters

#Samples

Incomes

Invoice

Breakdown

Clone this wiki locally