Generic Documentation Project

https://www.xmreport.com/doc/
Admin
This project contains a single markdown document, likely serving as general documentation or content...
Tokens:6,565
Snippets:97
Trust Score:5.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Engine to Local Repository

Source: https://www.xmreport.com/doc/document.html

Installs the XMReport engine JAR file into the local Maven repository. Ensure you are in the directory containing the JAR file before running this command.

```bash
mvn install:install-file -Dfile=web-report-engine-1.1.jar -DgroupId=org.mosmith -DartifactId=web-report-engine -Dversion=1.1 -Dpackaging=jar
```

--------------------------------

### Data Binding Expression Example

Source: https://www.xmreport.com/doc/document.html

An example of a Data Binding Expression that manipulates page numbers. This expression is evaluated before the Prepare Script and its result is bound to the widget.

```javascript
=getPageNo() -2 + '/{totalPages}'

```

--------------------------------

### Get Global Total Pages Directly

Source: https://www.xmreport.com/doc/document.html

Directly retrieves the total number of global pages. Returns a placeholder string.

```javascript
getGlobalTotalPages();

```

--------------------------------

### Get Global Page Number

Source: https://www.xmreport.com/doc/document.html

Retrieves the current global page number.

```javascript
getGlobalPageNo(): number;
```

--------------------------------

### Get Global Total Pages

Source: https://www.xmreport.com/doc/document.html

Retrieves the total number of pages. Returns a placeholder string as the total pages are unknown until execution completion.

```javascript
getGlobalTotalPages(): string;
```

--------------------------------

### Get Print Widget Property

Source: https://www.xmreport.com/doc/document.html

Fetches the value of a specified property from the Print Widget.

```javascript
printWidget.getProprty(propName: string): string;
```

--------------------------------

### Get Grid Total Pages Directly

Source: https://www.xmreport.com/doc/document.html

Directly retrieves the total number of pages within the current grid. Returns a placeholder string.

```javascript
getGridTotalPages();

```

--------------------------------

### Get Global Page Number Directly

Source: https://www.xmreport.com/doc/document.html

Directly retrieves the current global page number.

```javascript
getGlobalPageNO();

```

--------------------------------

### Format Value with Expression

Source: https://www.xmreport.com/doc/document.html

Formats a value using an expression similar to MS Excel's data format. Examples show currency and decimal formatting.

```javascript
format(9999, '[CN,RMB]'); // return 玖仟玖佰玖拾玖元整
```

```javascript
Format(12.888, '0.00'); // return 12.89
```

--------------------------------

### Get Global Variable

Source: https://www.xmreport.com/doc/document.html

Retrieves a global variable by its name. Equivalent to executeContext.getProperty().

```javascript
get(propName: string): Object;
```

--------------------------------

### Get Design Widget by ID

Source: https://www.xmreport.com/doc/document.html

Retrieves a Design Widget using its unique ID.

```javascript
getDesignWidget(widgetId: string): DesignWidget;
```

--------------------------------

### Get Date Components

Source: https://www.xmreport.com/doc/document.html

Utility functions to extract specific components (year, month, day, hour, minute, second) from a date.

```javascript
getYear()/getMonth()/getDate()/getHours()/getMinutes()/getSeconds(): number;
```

--------------------------------

### Modifying Total Pages in Final Script

Source: https://www.xmreport.com/doc/document.html

A Final Script example that modifies the content of a printWidget by replacing a placeholder with the adjusted total page count. This script runs after all execution is complete.

```javascript
var content = printWidget.getContent();
content = content.replace('{totalPages}', (getTotalPages()-2) + '');
printWidget.setContent(content);

```

--------------------------------

### Get Grid Page Number Directly

Source: https://www.xmreport.com/doc/document.html

Directly retrieves the current page number within the current grid.

```javascript
getGridPageNo();

```

--------------------------------

### Get Total Pages

Source: https://www.xmreport.com/doc/document.html

Retrieves the total number of pages. Returns a placeholder string as the total page count is unknown until execution completes. Behavior varies based on context similar to getPageNo().

```javascript
getTotalPages();

```

--------------------------------

### Get Group Total Pages Directly

Source: https://www.xmreport.com/doc/document.html

Directly retrieves the total number of pages within the current group. Returns a placeholder string.

```javascript
getGroupTotalPages();

```

--------------------------------

### Add XMReport Maven Dependency

Source: https://www.xmreport.com/doc/document.html

Adds the XMReport engine as a dependency to your Maven project. Ensure the engine JAR is installed in your local repository first.

```xml
<dependency>
    <groupId>org.mosmith</groupId>
    <artifactId>web-report-engine</artifactId>
    <version>1.1</version>
</dependency>
```

--------------------------------

### Get Group Page Number Directly

Source: https://www.xmreport.com/doc/document.html

Directly retrieves the current page number within the current group.

```javascript
getGroupPageNo();

```

--------------------------------

### Get Current Page Number

Source: https://www.xmreport.com/doc/document.html

Retrieves the current page number. Behavior varies based on context: within a group row, it returns the group's page number; within the grid (not a group row), it returns the grid's page number; otherwise, it returns the global page number.

```javascript
getPageNo();

```

--------------------------------

### Compile and Package Project

Source: https://www.xmreport.com/doc/document.html

Compiles and packages the XMReport demo project. Tests are skipped to speed up the process.

```bash
mvn clean install -DskipTests=true
```

--------------------------------

### Run the Application

Source: https://www.xmreport.com/doc/document.html

Executes the compiled XMReport Spring Boot application. After running, the designer can be accessed via a web browser.

```bash
java -jar target/web-report-spring-boot-0.1.jar
```

--------------------------------

### Loading and Using Shared Script in XMReport

Source: https://www.xmreport.com/doc/document.html

Demonstrates how to load a shared JavaScript file and invoke its functions within XMReport widget scripts. Ensure the shared script is accessible.

```javascript
//javascript
load('/StringUtils.js');
var value = "";
var valueIsEmpty = isEmpty(value);
...
```

--------------------------------

### Reading a File with Java in XMReport Script

Source: https://www.xmreport.com/doc/document.html

Demonstrates how to read a text file using Java's FileInputStream, StringBuilder, and BufferedReader within an XMReport script. Ensure the file path is correct and handle potential exceptions.

```javascript
importPackage(java.io);
var fs=new FileInputStream("d:/test.txt");
var sb=new StringBuilder();
try {
    var br=new BufferedReader(new InputStreamReader(fs, "utf-8"));
    var line;
    while((line=br.readLine())!=null) {
        sb.append(line);
        sb.append("\n");
    }
} finally {
	fs.close();
}
sb.toString();

```

--------------------------------

### Configure URL Prefix for Designer

Source: https://www.xmreport.com/doc/document.html

Sets a custom URL prefix for API calls made by the designer.

```javascript
window.config={
   ... 
   urlPrefix: 'your_prefix_here'
}

```

--------------------------------

### Custom Data Source Parser Configuration

Source: https://www.xmreport.com/doc/document.html

Configures a custom parser for data sources, including acceptance criteria and parsing logic.

```javascript
window.config={
   dataSourceTemplateParser: {
       accept: function(content) {
           if(content.indexOf('/// type=ckey')==0) {
               return true;
           }
           return false;
       },
       parse: function(content) {
            var model=eval('var model; model=' + content);
            var ckey=model.ckey;
            // process via ajax ... jQuery is window.jq

            return {
                expression: '='+ckey,
                children: [
                    {name: 'field1', expression: 'expression of field1'},
                    {name: 'field2', expression: 'expression of field2'}
                ]
            }
        }
    }
}


```

--------------------------------

### Generate PDF Report

Source: https://www.xmreport.com/doc/document.html

Generates a PDF report using the XMReport engine. This snippet demonstrates how to load a template, provide data, and use the ReportHelper to convert it to PDF.

```java
import java.io.FileInputStream;
import java.io.InputStream;
import java.io.Reader;
import java.io.InputStreamReader;
import org.mosmith.tools.report.engine.output.ReportHelper;

...

Reader templateDataReader=new InputStreamReader(new FileInputStream("test.template"), "UTF-8"); //	Template Data
Object previewData=new Object(); // Data Source

ReportHelper reportHelper=new ReportHelper(); // Helper tools, refer to the implementation of ReportHelper for more details if you want to do some customization.
InputStream pdfIs=reportHelper.toPdf(templateDataReader, previewData); // Execute and return the InputStream of Pdf file.
...
```

--------------------------------

### Print Widget Methods

Source: https://www.xmreport.com/doc/document.html

Methods for interacting with the Print Widget, such as setting properties, values, content, and dimensions.

```APIDOC
## Print Widget Methods

### `printWidget.setProperty(propName: string, propVal: string): void`

**Description**: Set a property to the Print Widget. This can be used to record data or set hidden properties like 'htmlAttrs'.

### `printWidget.getProperty(propName: string): string`

**Description**: Fetch a property value of the Print Widget.

### `printWidget.setValue(value: Object): void`

**Description**: Set the bound value of the Print Widget. The value is converted to display content based on the data format.

### `printWidget.setContent(content: string): void`

**Description**: Set the display content of the Print Widget. This is distinct from the value, which is used for computation, while content is for display. Use this to customize content without changing the value.

### `printWidget.setX(x: number): void`

**Description**: Set the X-coordinate position of the Print Widget.

### `printWidget.setY(y: number): void`

**Description**: Set the Y-coordinate position of the Print Widget.

### `printWidget.setWidth(width: number): void`

**Description**: Set the width of the Print Widget.

### `printWidget.setHeight(height: number): void`

**Description**: Set the height of the Print Widget.
```

--------------------------------

### Reduce Image Size in PDF (Post Script)

Source: https://www.xmreport.com/doc/document.html

Optimizes PDF generation by reusing image IDs and caching images in the execution context.

```javascript
1.printWidget.setProperty("pdfImgSerialId", "image1"); 
2.printWidget.setCacheImgInExecuteContext(true); 


```

--------------------------------

### Simple-Mode Data Source (JSON)

Source: https://www.xmreport.com/doc/document.html

Defines a data source using a JSON structure. Field values are expressions.

```json
/// type=demo  
{
    field1: 'expression of field1',
    field2: {
        subField1: 'expression of subField1',
        subField2: 'expression of subField2'
    }
}


```

--------------------------------

### Simple-Mode Data Source (Ignore Values)

Source: https://www.xmreport.com/doc/document.html

Defines a data source where field values are ignored. Useful for structure definition.

```json
/// type=demo, ignoreValue=true  
{
    field1: 'expression of field1', 
    field2: {
        subField1: 'content here will be ignored',
        subField2: 'content here will be ignored'
    }
} 


```

--------------------------------

### Built-in Utility Functions

Source: https://www.xmreport.com/doc/document.html

A collection of utility functions for data manipulation, formatting, encoding, and widget lookup.

```APIDOC
## Built-in Utility Functions

### `lookup(name: string): Object`

**Description**: Lookup a value by 'name' within the data stack. Refer to the 'Data Binding' section for details.

### `get(propName: string): Object`

**Description**: Get a global variable by its 'propName'. Equivalent to `executeContext.getProperty()`.

### `set(propName: string, propValue: Object): void`

**Description**: Set a global variable with a given name and value. Equivalent to `executeContext.setProperty()`.

### `getGlobalPageNo(): number`

**Description**: Get the current global page number.

### `getGlobalTotalPages(): string`

**Description**: Get the global total pages. Returns a placeholder string that the engine replaces with the actual total page count upon completion.

### `format(value: Object, formatExpression: string): string`

**Description**: Format values using an expression similar to MS Excel's data format. Examples:
`format(9999, '[CN,RMB]')` returns `玖仟玖佰玖拾玖元整`.
`format(12.888, '0.00')` returns `12.89`.

### `htmlEncode(value: string): string`

**Description**: Encode text using HTML encoding. Example:
`htmlEncode('Hello\nWorld, 1+1>2')` returns `'Hello<br/>World, 1+1>2'`.

### `urlEncode(str: string): string`

**Description**: Escape keywords in a value for URL encoding, similar to `encodeURIComponent()`.

### `replace(value: string, from: string, to: string): string`

**Description**: Corresponds to `java.lang.String.replace()`. Used for global string replacement, especially when JavaScript's native string replacement is inconvenient.

### `parseDate(dateStr: string, format: format): java.util.Date`

**Description**: Parse a date string with a given format pattern using `java.lang.SimpleDateFormat`. Example:
`parseDate(“2021-12-12”, “yyyy-MM-dd”)`.

### `getYear(): number`

**Description**: Retrieve the current year.

### `getMonth(): number`

**Description**: Retrieve the current month.

### `getDate(): number`

**Description**: Retrieve the current day of the month.

### `getHours(): number`

**Description**: Retrieve the current hour.

### `getMinutes(): number`

**Description**: Retrieve the current minute.

### `getSeconds(): number`

**Description**: Retrieve the current second.

### `newBytes(): byte[]`

**Description**: Create a new Java byte array object.

### `newInts(): int[]`

**Description**: Create a new Java int array object.

### `newLongs(): long[]`

**Description**: Create a new Java long array object.

### `findPrintWidgets(containerPW: ContainerPW, id: string): PrintWidget[]`

**Description**: Find a Print Widget by its ID within a given container Print Widget. Returns an array as widget iteration can generate multiple instances (e.g., in a list).

### `getDesignWidget(widgetId: string): DesignWidget`

**Description**: Find a Design Widget by its ID.

### `findDesignWidget(containerDW: ContainerDW, id: string): DesignWidget`

**Description**: Find a Design Widget by its ID within a given container Design Widget.
```

--------------------------------

### Comprehensive-Mode Data Source

Source: https://www.xmreport.com/doc/document.html

Defines a data source with detailed field descriptions including name, expression, and children.

```json
[
    {name: 'field1', expression: '=expression of field'},
    {name: 'field2', expression: '=expression of field'},
    {name: 'field3', expression: '=expression of field', children: [
        {name: 'subField1', expression: '=expression of field'},
        {name: 'subField2', expression: '=expression of field'}
    ]}
]


```

--------------------------------

### Set Global Variable

Source: https://www.xmreport.com/doc/document.html

Sets a global variable with a specified name and value. Equivalent to executeContext.setProperty().

```javascript
set(propName: string, propValue: Object): void;
```

--------------------------------

### Set Print Widget Size and Position

Source: https://www.xmreport.com/doc/document.html

Adjusts the size and position of the Print Widget on the screen.

```javascript
printWidget.setX/setY/setWidth/setHeight(x/y/width/height: number);
```

--------------------------------

### Create Java Array Object

Source: https://www.xmreport.com/doc/document.html

Creates Java array objects (byte[], int[], long[]) as JavaScript does not natively support this.

```javascript
var bytes=newBytes();
```

```javascript
var ints=newInts();
```

```javascript
var longs=newLongs();
```

--------------------------------

### Set Authorization Header for Designer

Source: https://www.xmreport.com/doc/document.html

Configures custom authorization headers for API requests initiated by the designer.

```javascript
window.config={
   ...
   headers: function() {
      return {
         Authorization: 'xxx'
      }
   }
}


```

--------------------------------

### Debugging Scripts with Text Widget

Source: https://www.xmreport.com/doc/document.html

Provides code snippets for debugging scripts by setting message limits and stringifying data.

```javascript
1. set('exceptionMsgLengthLimit', 50000); // place this code before the targeted scripts, so that text widget can display the full message
2. JSON.stringify(data); // Stringify a data to JSON, so that text widget can display the data details.


```

--------------------------------

### Find Print Widgets by ID

Source: https://www.xmreport.com/doc/document.html

Finds Print Widgets within a specified container Print Widget using their ID. Returns an array as multiple widgets can match.

```javascript
findPrintWidgets(containerPW: ContainerPW, id: string): PrintWidget[];
```

--------------------------------

### Set Exception Message Length Limit

Source: https://www.xmreport.com/doc/document.html

Increases the limit for displaying error messages, useful for long stack traces.

```javascript
set('exceptionMsgLengthLimit', 50000);


```

--------------------------------

### Set Print Widget Property

Source: https://www.xmreport.com/doc/document.html

Sets a property for the Print Widget. Useful for recording data or configuring hidden properties like 'htmlAttrs'.

```javascript
printWidget.setProperty(propName: string, propVal: string): void;
```

--------------------------------

### Set Cell Value with Sum Computation

Source: https://www.xmreport.com/doc/document.html

Use this to set a cell's value by summing values from other cells. Ensure the target cell is placed after the cells being summed.

```javascript
targetCell.setValue(sum("cellToSum"));

```

--------------------------------

### Find Design Widget by ID within Container

Source: https://www.xmreport.com/doc/document.html

Finds a Design Widget by its ID within a given container Design Widget.

```javascript
findDesignWidget(containerDW: ContainerDW, id: string): DesignWidget;
```

--------------------------------

### Parse Date String

Source: https://www.xmreport.com/doc/document.html

Parses a date string into a java.util.Date object using a specified format pattern. Leverages java.lang.SimpleDateFormat.

```javascript
parseDate("2021-12-12", "yyyy-MM-dd")
```

--------------------------------

### Set Print Widget Content

Source: https://www.xmreport.com/doc/document.html

Sets the display content of the Print Widget without altering its underlying value. Useful for custom display formatting.

```javascript
printWidget.setContent(content: string): void;
```

--------------------------------

### JavaScript Utility Function

Source: https://www.xmreport.com/doc/document.html

Defines a reusable JavaScript function to check if a value is null or empty. Load this script in widget data/scripts to use the function.

```javascript
function isEmpty(val) {
    return val==null || val=='';
}
```

--------------------------------

### Lookup Value in Data Stack

Source: https://www.xmreport.com/doc/document.html

Searches for a value within the data stack using a provided name. Refer to the 'Data Binding' section for details.

```javascript
lookup(name: string): Object;
```

--------------------------------

### URL Encode String

Source: https://www.xmreport.com/doc/document.html

Escapes characters in a string for use in a URL, similar to encodeURIComponent().

```javascript
urlEncode(str: string): string;
```

--------------------------------

### Set Print Widget Value

Source: https://www.xmreport.com/doc/document.html

Sets the bound value for the Print Widget. The value is typically converted to display content based on a data format.

```javascript
printWidget.setValue(value: Object): void;
```

--------------------------------

### HTML Encode String

Source: https://www.xmreport.com/doc/document.html

Encodes a string using HTML encoding, converting newline characters to '<br/>'.

```javascript
htmlEncode('Hello\nWorld, 1+1>2'); // return 'Hello<br/>World, 1+1>2'
```

--------------------------------

### Replace Substring Globally

Source: https://www.xmreport.com/doc/document.html

Replaces all occurrences of a substring within a string. Designed to overcome JavaScript's string type limitations for global replacement.

```javascript
replace(value: string, from: string, to: string): string;
```

--------------------------------

### Sum Values Between Two Cells

Source: https://www.xmreport.com/doc/document.html

Calculate the sum of values within a specified rectangular range of cells, defined by the top-left and bottom-right cell names.

```javascript
sum("cell1", "cell8");

```
Tokens:
Raw