DOCSEARCHbyAlgolia
Submit Docs

UReport2 Documentation

repository·master·Indexed 24 days ago

https://github.com/youseries/ureport

UReport2 is a high-performance, pure Java report engine based on Spring architecture designed for creating complex, Chinese-style reports. It features a web-based designer compatible with modern browsers and supports a sophisticated expression system for conditional logic, relative cell referencing, and time-series calculations (MoM/YoY). The engine utilizes a hierarchical cell expansion model and provides a default server file system storage mechanism for report files.

Tokens
5K
Snippets
8
Records
25
Agent score
80%

What's inside UReport2

  1. Overview of UReport2

    master

    UReport2 is a high-performance, pure Java reporting engine architected on top of Spring. It is designed specifically to handle complex 'Chinese-style' reports through cell iteration.

    Key features include:

    • Spring-based Architecture: Built as a pure Java engine integrated with the Spring framework.
    • Web-based Designer: A modern report designer that runs in mainstream browsers such as Chrome, Firefox, and Edge (Note: IE is not supported).
    • Open Source: Distributed under the Apache-2.0 license.

  2. How cell references work in UReport2

    master

    In UReport2, cell references are calculated relative to the current cell. You can refer to a cell by its name (e.g., A1). Because reports often involve data expansion (sectional structures), a single reference might result in multiple values.

    Reference Principles

    1. Same Row or Column: If the target cell is in the same row or column as the current cell, the value at that specific intersection is applied.
    2. Common Parent Cell: If the target cell is not in the same row/column, UReport2 looks for a common parent (or indirect parent) cell. It then applies all values of the target cell that fall under that common parent. If multiple values are acquired, they are output as a comma-separated list (e.g., val1,val2).
    3. No Common Parent: If there is no common parent cell, all target cells resulting from the iteration are applied.

  3. Use the & sign to mark expanded cell sequences

    master

    When using an if judgment expression to handle edge cases in calculations (like the first row of a report), you can use the & prefix to refer to the sequence number of an expanded target cell.

    Syntax: &cell_name

    Requirement: The current cell must be a sub-cell or an indirect sub-cell of the target cell.

    Example: If you are in cell D2 (an indirect sub-cell of A2), you can use &A2 to check the sequence value of the expanded A2 unit. This is useful for determining if you are in the first group of a report to avoid displaying 0 for non-existent previous periods.

    &A2==1

  4. Use cell coordinates for complex cell references

    master

    UReport2 uses cell coordinates to perform complex relative references. Coordinates are calculated relative to the current cell and follow a specific syntax to navigate through expanded parent cells (left and top).

    Syntax: CellName[Li:li,Li-1:li-1;Ti:ti,Ti-1:ti-1]{condition...}

    • L (Left parent): Li:li represents the left parent cell and the sequence number li after expansion. A negative value moves upward/leftward relative to the current position.
    • T (Top parent): ;Ti:ti represents the top parent cell and the sequence number ti. A negative value moves upward relative to the current cell; a positive value moves downward.
    • Conditions: Enclosed in {}. Multiple conditions can be joined with and or or. Conditions are used to filter the cells acquired through the coordinates.

    Examples:

    • C1[A1:2,B1:1]: Finds the 2nd cell after A1 is expanded, then the 1st cell after B1 is expanded under that, to find C1.
    • C2[A1:2,B2:2]{C2>1000}: Navigates to the 2nd cell after A1, then the 2nd cell after B2 under that, and filters for all C2 cells where the value is greater than 1,000.
    • C2[A1:2,B2:2]{C2>1000 and C2<10000}: Filters for C2 cells where the value is between 1,000 and 10,000.

  5. Understand the cell dependency model in UReport2

    master

    In UReport2, cells maintain a dependency relationship through 'left parent' and 'top parent' cells. This model defines how cells relate to their neighbors and how expansion behavior propagates through the report structure.

    Default Parent Behavior

    • Left Parent: By default, refers to the nearest cell to the left in the same row. Cells in the first column have no left parent.
    • Top Parent: By default, refers to the nearest cell above in the same column. Cells in the first row have no top parent.

    Users can manually override these defaults in the UReport2 report designer by selecting a cell and modifying its parent cell properties in the properties panel.

  6. Understand default report storage in UReport2

    master

    By default, UReport2 uses a "server file system" mechanism to store report files. When a project starts, UReport2 automatically generates a directory named ureportfiles under the WEB-INF directory of your project. This is the default storage location for all designed reports.

    Note on Environment Differences:

    • Eclipse (Jetty): The ureportfiles directory will appear directly under WEB-INF in your project structure.
    • Tomcat: The directory might not appear in your project source folder because Tomcat uses a temporary working directory. You may need to look in your workspace metadata (e.g., workspace.metadata/plugins/org.eclipse.wst.server.core/tmp0/wtpwebapp/) to find the actual WEB-INF/ureportfiles directory.

  7. How cell expansion and data iteration work

    master

    UReport2 uses a hierarchical expansion model based on data sets. If a cell is bound to a field in a data set that contains multiple pieces of data, that cell can be expanded.

    Expansion Rules

    • Propagation: When a parent cell is expanded, all its sub-cells (and their subsequent sub-cells) expand along with it.
      • Expanding a parent cell downward forces all sub-cells and nested sub-cells to expand downward.
    • Data Restrictions: If a sub-cell is bound to the same data set as its parent cell, the sub-cell's data is subject to the restrictions/filtering applied to the parent cell.
    • Layout Impact: If a parent cell and its sub-cell are located in the same row or column, expanding the sub-cell will cause the parent cell to widen to maintain alignment.

  8. Access the UReport2 Report Designer

    master

    Once UReport2 is installed and configured, you can access the web-based report designer via your browser at the following URL:

    http://localhost:8080/[contextPath]/ureport/designer

    Replace [contextPath] with your application's actual context path.

  9. Configure a Spring Bean Data Source

    master

    You can use a Spring Bean as a data source by selecting a Bean defined in your Spring context.

    1. In the report designer, enter the name of the data source and the ID of the Bean to be used.
    2. After saving, add a data set by right-clicking the data source and choosing "add the data set".
    3. Define the data set name, the method name to call, and the return object type.

    Method Requirements

    The method selected from the Bean must follow a specific signature with exactly three parameters:

    1. String: The name of the data source.
    2. String: The name of the data set.
    3. Map<String, Object>: The external parameters map.

    Supported Return Types

    UReport2 supports two types of return values for these methods:

    • List<Map<String, Object>>
    • List<POJO> (a list of plain old Java objects)
    package com.ureport.test;

import java.util.List;
import java.util.Map;

public class TestBean {
	public List<Map<String,Object>> loadReportData(String dsName, String datasetName, Map<String,Object> parameters){
		return null;
	}

	public List<User> buildReport(String dsName, String datasetName, Map<String,Object> parameters){
		return null;
	}
}

  10. Calculate Month-on-Month and Year-on-Year values

    master

    UReport2 allows for time-series calculations like Month-on-Month (MoM) or Year-on-Year (YoY) by using negative sequence numbers in cell coordinates to look at previous periods.

    Month-on-Month (MoM)

    To compare the current cell C2 with the previous month's C2, use: C2 - C2[A2:-1] Here, A2:-1 tells the system to look at the cell C2 corresponding to the parent A2 that is one position above the current A2.

    Year-on-Year (YoY)

    To compare the current value with the same period in the previous year, you often need to match a specific dimension (like a month or year name) using a condition.

    In UReport2, use the $ prefix inside a condition to refer to the value of a cell relative to the target cell being acquired, rather than the current cell.

    Example for YoY: C2 - C2[A2:-1]{B2==$B2}

    • B2 (without $) is the value of B2 in the current row.
    • $B2 is the value of B2 in the target cell (the one found via coordinates).
    • The condition {B2==$B2} ensures you are only subtracting values from the same month/period.

    Note on Defaults: If the coordinate (e.g., A2:-1) does not exist (like in the first row of a report), UReport2 defaults to the current cell's value, resulting in a difference of 0. Use an if expression to handle these cases (e.g., returning an empty string instead of 0).

  12. Install UReport2 in a Maven-based J2EE project

    master

    To incorporate UReport2 into a Maven project, add the ureport2-console dependency to your pom.xml. You can find the latest version on Maven Central or use a snapshot version by adding the Sonatype repository configuration.

    <!-- Maven Dependency -->
<dependency>
    <groupId>com.bstek.ureport</groupId>
    <artifactId>ureport2-console</artifactId>
    <version>[version]</version>
</dependency>

<!-- Repository for Snapshot versions -->
<repository>
    <id>sonatype</id>
    <url>https://oss.sonatype.org/content/groups/public/</url>
</repository>