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

To create a React application, we will use the create-vite starter kit by running the following command:

# npm 6.x
npm init vite arjs-api --template react-ts

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

#yarn
yarn create vite arjs-api --template react-ts

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 a simple report with a single textbox displaying Hello, ActiveReportsJS by using the Core API of ActiveReportsJS. The second function loads this report, runs it, and exports it as a PDF document by using the PDF Export API.

Using Report Service

Replace the content of src/App.tsx 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

To run the application in development mode, execute the following command:

# npm
npm run dev

#yarn
yarn dev

If you encounter an error stating 'vite' is not recognized as an internal or external command, operable program or batch file, it may be because the dependencies haven't been installed yet. Run npm install or yarn to install the required packages, and then start the development server with npm run dev or yarn dev.

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.