Live Previewer

The best way to develop report templates is with the Live Previewer tool. The Live Previewer is a console application that watches a folder for file changes and automatically renders a preview to a window. It provides near instant rendering of a report each time the report template or data file is saved on disk. This feedback allows for very quick iteration on report changes making development of reports much easier.

Requirements

The Live Previewer tool is built with .NET Core and runs on Windows and Mac systems. The following are the requirements for running the tool:

.NET Core 7 Runtime
QuestPDF Previewer
Visual Studio, Visual Studio Code or any other JSON file editor

Installing the QuestPDF Previewer

The live preview editor requires a tool called QuestPDF Previewer. This tool can be installed using the dotnet cli:

dotnet tool install QuestPDF.Previewer --global

Installing the Live Previewer

The Live Previewer can be installed from the JHReporting private package feed which is hosted on GitHub. You must first configure access to the private feed by following these instructions.

The Live Previewer can then be installed using the command below:

dotnet tool install JackHenry.Reports.Previewer --global

Running the Live Previewer

From a command line, navigate to the folder that contains your report template and data files, then run the command:

jh-report-previewer watch

The previewer tool will start, launch the QuestPDF Previewer and then begin watching for file changes in the current folder. As soon as a change is detected, you will see the report output displayed in the QuestPDF Previewer window. Each time you make a change to the report template, save the file and you will get an updated preview of the report. The command window will also display helpful information about the rendering process including render times and any warnings or errors that occur.

The jh-report-previewer command also supports passing a path to the folder that contains your template and data files as shown below:

jh-report-previewer watch --watchfolder /path/to/reports/

Configuration

The Live Previewer tool can be configured to include json data and resource files that should be loaded when rendering reports. This is useful for teams that have shared components, styles or data elements that are used across multiple report templates. In the Live Previewer appsettings.json file, the following values can be configured:

{
  "Reporting": {
    "PreviewerConfig": {
      "DataFiles": ["file://data.json"],
      "ResourcePaths": ["file://shared/"],
      "OverrideDataFile": "overrideData.json"
    }
}

Any values defined here will apply to all reports when rendered in the Live Previewer. To define settings for a specific report, see: PreviewerOptions.

File Naming

If report data/resource URLs are not defined in the report template's PreviewerOptions, the report template and json data file should be in the same folder and share the same base filename. For example:

Report Template File: /reports/myreport.rpt.json
Report Data File: /reports/myreport.json

In addition, any external files required to render a report (e.g. external options files, images, etc.) may be placed in a folder with the same name as the report template and data files. Following the example above, resource files should be placed in a folder as shown below:

Report Resources: /reports/myreport/

The image below shows how to name and organize the report template, data and resource files for a report named 'Call Code'.

The user can use any text editor/IDE they choose. Each time a report template or report data file is saved, the live preview window will refresh with an image-based exact replica of a final PDF report.

Examples

A few examples of Live Preview are show below. These examples use VSCode as the file editor and show code completion features provided when using Json Schema validation.