User Guide

Welcome to ZReport. This guide will help you master report design, from simple lists to complex analytical dashboards.

Interface Overview

The designer is divided into four main areas:

Tutorial: Your First Report

Let's build a simple Employee List report.

Bands Explained

Bands are the containers for your elements. Understanding bands is key to mastering reporting.

Grouping Data

Grouping allows you to organize data into logical sections, such as Sales by Region or Employees by Department.

Elements Guide

Data Sources

The Data Dictionary panel is where you define and manage data sources for a project. These sources are shared across all reports in the same project.

Data Binding ($F, $P, $V, $R)

ZReport uses a JasperReports-style syntax to reference data. Every data-bound expression must be wrapped in curly braces {...} with a prefix.

Parameters & Variables Detail

Formatting & Patterns

Apply display patterns to your data using the colon : syntax within the expression.

Functions Reference

ZReport includes a powerful functional library with 50+ functions for calculations and data manipulation.

Conditional Logic

You can hide elements or entire bands based on data conditions using the printWhen property.

Inline Logic (IF)

Use the IF function for dynamic content within a single text box.

Preview & Exporting

Saving & Loading

Keyboard Shortcuts

Limits & Troubleshooting

Expression Engine

The expression parser evaluates JasperReports-style expressions at runtime.

Syntax

Format Specifiers

Append :format to apply formatting:

• $F{price:currency} – Format as currency
• $F{date:date:yyyy-MM-dd} – Format as date
• $F{name:uppercase} – Convert to uppercase
• $F{code:pad:6:0} – Left-pad with zeros

System Variables

• PageNumber – Current page number
• TotalPages – Total page count (available after render)
• PrintDate – Current date/time
• ReportName – Name of the report
• RecordNumber – Current record index
• GroupRecordNumber – Record index within current group

Rich Content ($R)

The $R{paramName} expression renders structured rich content from a parameter value. Unlike $P{} which renders parameters as plain text, $R{} parses a JSON array of blocks and renders them with full formatting in PDF and DOCX exports.

Usage

Set a text element's content to $R{paramName}, then pass the rich content JSON as the parameter value via the Export API:

{
  "reportId": "rpt_abc123",
  "parameters": {
    "content": [
      {
        "type": "paragraph",
        "align": "center",
        "content": [
          { "text": "Normal text " },
          { "text": "bold text", "bold": true },
          { "text": " colored", "color": "#ff0000", "fontSize": 14 }
        ]
      },
      { "type": "heading", "level": 2, "content": [{ "text": "Section Title" }] },
      { "type": "hr" }
    ]
  }
}

Block Types

Inline Text Properties

Each block that accepts content takes an array of inline text objects with these properties:

List Styles

Set the style property on a list block to control the marker type. If omitted, defaults to "bullet" (or "number" when ordered: true for backward compatibility).

For check lists, each item accepts a checked boolean property to control whether the checkbox is ticked.

{
  "type": "list",
  "style": "check",
  "items": [
    { "content": [{ "text": "Design mockups" }], "checked": true },
    { "content": [{ "text": "API integration" }], "checked": true },
    { "content": [{ "text": "Write tests" }], "checked": false }
  ]
}

Full Example

[
  {
    "type": "heading",
    "level": 1,
    "content": [{ "text": "Invoice Summary" }]
  },
  {
    "type": "paragraph",
    "content": [
      { "text": "Thank you for your order. " },
      { "text": "Order #12345", "bold": true },
      { "text": " has been confirmed." }
    ]
  },
  {
    "type": "table",
    "headers": [
      { "content": [{ "text": "Item" }] },
      { "content": [{ "text": "Qty" }] },
      { "content": [{ "text": "Price" }] }
    ],
    "rows": [
      [
        { "content": [{ "text": "Widget A" }] },
        { "content": [{ "text": "2" }] },
        { "content": [{ "text": "$49.99" }] }
      ]
    ]
  },
  {
    "type": "list",
    "style": "bullet",
    "items": [
      { "content": [{ "text": "Free shipping included" }] },
      { "content": [{ "text": "30-day return policy", "italic": true }] }
    ]
  },
  {
    "type": "list",
    "style": "check",
    "items": [
      { "content": [{ "text": "Payment received" }], "checked": true },
      { "content": [{ "text": "Order shipped" }], "checked": false }
    ]
  },
  { "type": "hr" },
  {
    "type": "paragraph",
    "align": "center",
    "content": [
      { "text": "Visit our website", "link": "https://example.com", "color": "#0563C1" }
    ]
  }
]

Supported in PDF and DOCX exports. The element's position and dimensions (x, y, width, height) from the report designer are used to place the rich content block.

Export Services

ZReport supports exporting rendered reports to multiple formats.

Export API

Generate reports in various formats programmatically using our REST API.

Authentication

All API requests require an API key. Include it in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Generate API keys from your organization settings at Settings → API Keys.

Export Endpoints

POST https://api.zreport.cloud/api/export/pdf
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "reportId": "rpt_abc123",
  "data": {
    "orders": [
      { "id": 1, "product": "Widget", "amount": 99.99 }
    ]
  },
  "parameters": {
    "title": "Q4 Sales Report",
    "startDate": "2024-10-01"
  }
}

Code Examples

Playground

Test the Export API directly from this page.

Response

On success, the API returns the file as a binary stream with appropriate content-type headers. On error:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Report ID is required"
  }
}

Rate Limits