Get Started with the ActiveReportsJS API

In addition to the Report Viewer and the Report Designer components, ActiveReportsJS provides a set of APIs that allow you to create reports programmatically and export them to PDF, Excel, and HTML formats. This feature is handy for developers who want to implement a custom report designer or custom report viewer or build, run, and export reports without using an interactive UI. This tutorial shows how to use the API to create a simple report programmatically and export it to PDF. We use React.js + Typescript as the framework for this tutorial, but the techniques described here also apply to other frameworks. To get the most out of the API, we recommend using Typescript because the API is supplied with the type declarations recognizable by the IntelliSense feature of Visual Studio Code or other IDE that supports TypeScript.

Create React Application

The easiest way to create a new React application is to use the Create React App tool. Run the following command from the command prompt or terminal to create a React application from the Typescript template. For details, see Getting Started on the Create React App site.

# npm 6.x
npm init react-app arjs-api --template typescript

# npm 7+, extra double-dash is needed
npm init react-app arjs-api -- --template typescript

Or if you are using yarn:

yarn create react-app arjs-api --template typescript

For more ways to create a React application, see the official documentation

Install ActivereportsJS npm packages

The ActiveReportsJS API is distributed via @mescius/activereportsjs npm package. The same package contains the export filters and other core functionality.

To install the current version of this package, run the following command from the application's root folder.

npm install @mescius/activereportsjs@latest

Or if you are using yarn:

yarn add @mescius/activereportsjs@latest

Implement Report Service

In the src folder, create a new file called reportService.ts with the following content:

import { Rdl as ARJS, PageReport } from "@mescius/activereportsjs/core";
import { PdfExport } from "@mescius/activereportsjs";

export function buildReportDefinition(): ARJS.Report {
  const report: ARJS.Report = {};
  report.Width = "8.5in";
  report.Page = {
    TopMargin: "0.5in",
    BottomMargin: "0.5in",
    LeftMargin: "0.5in",
    RightMargin: "0.5in",
    PageWidth: "8.5in",
    PageHeight: "11in",
  };
  const textbox: ARJS.Textbox = { Type: "textbox", Name: "txtGreetings" };
  textbox.Value = "Hello, ActiveReportsJS";
  textbox.Style = {
    FontSize: "18pt",
  };
  textbox.Width = "7in";
  textbox.Height = "0.5in";
  report.Body = { ReportItems: [textbox] };
  return report;
}

export async function exportReport(
  reportDefinition: ARJS.Report
): Promise<PdfExport.PdfExportResult> {
  const pageReport = new PageReport();
  await pageReport.load(reportDefinition);
  const doc = await pageReport.run();
  return PdfExport.exportDocument(doc, {
    info: {
      title: "Generated by ActiveReportsJS",
    },
  });
}

The first function builds the report definition by using the Core API of ActiveReportsJS. The second function exports the report to PDF by using the PDF Export API

Using Report Service

Open the src\App.tsx file and replace its content with the following code.

import "./App.css";
import { buildReportDefinition, exportReport } from "./reportService";

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <a
          className="App-link"
          href="."
          onClick={(e) => {
            e.preventDefault();
            const reportDefinition = buildReportDefinition();
            exportReport(reportDefinition)
              .then((result) => {
                result.download("ActiveReportsJSReport");
              })
              .catch(console.error);
          }}
        >
          Generate Report
        </a>
      </header>
    </div>
  );
}

export default App;

Run and test the application

Running the npm start or yarn start commands could fail with the fatal error that the JavaScript heap is out of memory. In that case, open the package.json file and replace the start script with the following one.

react-scripts --max_old_space_size=8192 start

Then re-run the npm start or yarn start command. If the command fails with an error like the one below, or a similar one, delete the node_modules folder and run npm install or yarn to re-install all the required packages. Then run npm start or yarn start again.

> react-scripts start

internal/modules/cjs/loader.js:883
  throw err;
  ^

Error: Cannot find module 'react'

When the application starts, click the "Generate Report" link to build and export the report. The PDF document will be opened in the browser, in the external program, or processed to download depending on the browser settings.