Report Designer

When to Use

• When a new report needs to be built from application data.
• When report filters need to be added, made required, locked by role, or changed to another input type.
• When report results are wrong because SQL, filter placeholders, or child queries need correction.
• When report layout needs updates such as title, table, subtotal, grand total, chart, text, or print layout.

Basic Concepts

• Report File is the report definition selected from the server.
• Report Path is the code used by menus, preview, and route opening. Do not change it without checking related menus.
• SQL Code is JSON containing mainsql and optional childrensql. Query results become data in the template.
• Filter Definition controls the input shown before running the report.
• HTML/EJS controls report output. HTML defines layout; EJS reads data, loops rows, calculates totals, and shows conditional content.
• Preview runs the report being edited so the implementor can inspect filters, output, and sample data.

Workflow

1. Open Settings / Designer & Menu / Report Designer.
2. Select the report file to edit.
3. Before changing an important report, use Duplicate or Export JSON.
4. Review Name, Description, Report Path, Report Type, SQL Code, Filter Definition, HTML/EJS, and Default Page Setup.
5. Make sure each filter Field Name matches placeholders used in SQL Code.
6. Run Preview, fill filters, and compare rendered output with sample data.
7. Click Save only after the query, filters, and template are correct.

Filter Definition

SQL Code

• SQL Code is JSON, not just plain SQL text.
• mainsql is the main query.
• childrensql is used for nested report details.
• <-customfilter-> is replaced by WHERE filters generated from user input.
• <--filtername--> is replaced by SQL condition for that filter.
• <--filtername.value--> reads the selected filter value directly.
• <---fieldname---> reads the parent row value for child queries.
• <-customhaving-> and HAVING placeholders are used for aggregate filters.

HTML/EJS and Preview

• Common variables include data, form, company, users, filter, filterdata, langs, functions, langId, server, and userroles.
• data is the SQL result. If SQL has child queries, the data structure is nested.
• filter contains filter definitions. filterdata contains selected values.
• Use Code mode for reports with many loops, subtotals, or conditions.
• Preview runs the current report file and shows rendered output plus sample data for field matching.

Import, Export, Duplicate, and Delete

• Duplicate is the safest first step before editing an active report.
• Export JSON creates a backup that can be restored or moved to another server.
• Import loads a report JSON file into the designer; review Report Path before saving.
• Delete only reports that are no longer connected to menus or active users.

Print and Export Setup

• Allow Print controls whether users can print the report.
• Allow Export controls whether users can export data.
• Report Type controls whether output is HTML or text.
• Default Page Setup controls paper size, orientation, and margins.
• Export Filename can use placeholders to produce meaningful downloaded file names.

Public Reports and the Share / Embed Button

By default a report can only be opened after logging in. Turn on the Public Report (No Login Required) toggle in Report Designer when a report must be opened by people without an account, for example parents viewing a report card or customers checking a status.

1. Turn on Public Report for the report, then save.
2. Open that report from the menu as usual. A Share / Embed button appears in the filter panel.
3. The dialog shows the report page Link and an Embed code as a ready-to-paste <iframe> snippet, each with a copy button.
4. Paste the link or embed code into your website or message. The iframe snippet carries a small script that fits the box height to the report content, so a long report does not scroll inside a fixed-size box.

Modify Design with AI

The Modify design with AI panel helps change a design without writing code yourself. It is available to users whose role has Allow AI, and it uses the same credit balance as the AI Assistant.

1. Select the design to change, then describe what you need in Requested changes. Example: fit the receipt to 80 mm paper, enlarge the company name, and add a signature area.
2. Click Propose changes. AI shows a summary and a comparison of Before and AI proposal; the credits used and the remaining balance are shown too.
3. Click Apply to editor if the proposal fits, or Dismiss proposal if not. Applying or discarding a proposal uses no further credits.
4. Check the result in the editor, then save with the designer's usual save button. Undo AI changes restores the design from before it was applied, as long as no other edit has been made.

Things to Check

• Incorrect SQL can produce empty, slow, or wrong reports.
• If Preview is empty, check required filters, placeholders, field names, child queries, and HTML/EJS.
• If filters do not work, compare Filter Definition Field Name with SQL placeholders.
• If print/export differs from Preview, check Allow Print, Allow Export, Report Type, Export Filename, and Default Page Setup.
• Export Filename can use placeholders such as {{datetime}}, {{report.xxx}}, {{company.xxx}}, {{username}}, {{filter.xxx}}, and {{filterdata.xxx}}.