Integration Guides Integrating the FE

This guide describes the integration process to add FE components and processes into your service.

Pre-requisites

Contents

Report Catalogue component

This component supports the DPR platform functionality by providing a unified way of listing and navigating reports

The catalogue component is used to:

  • view report variants in a list.
  • view report information such as product, variant name, and description in the list.
  • filter the list columns by string.
  • request variants.
  • bookmark variants.

Initialise the components render data

Initialise the component with the required data using the component utility helper and pass it to the res.render function.

// server/routes/index.ts

import CatalogueUtils from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/components/_catalogue/catalogue/utils'


export default function routes(services: Services): Router {

  ...

  router.get('/path/to/catalogue', (req, res) => {
    const catalogue = await CatalogueUtils.init({ res, services })
    res.render('reports-catalogue.njk', {
      catalogue
    })
  })
}

Add the component to your HTML

{ from "components/_catalogue/catalogue/view.njk" import dprCatalogue }

{ dprCatalogue(catalogue) }

See Catalogue component for usage and examples.

User reports list Component

This component is used to visualise and enable users to keep track of all requests, bookmarks and recently viewed reports so you can quickly navigate around the embedded DPR platform.

It is responsible for:

  • Listing requested reports
  • Listing recently viewed reports
  • Listing bookmarks
  • Polling the status of a requested.

Initialise the lists render data

Initialise the component with the required data using the component utility helper:

// server/routes/index.ts

import UserReportsListUtils from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/components/user-reports/utils'


export default function routes(services: Services): Router {

  ...

  router.get('/path/to/requested/reports/list/', (req, res) => {

    const userReportsLists = await UserReportsListUtils.init({ res, req, services })

    res.render('requested-reports.njk', {
      title: 'DPR test site',
      userReportsLists
    })
  })
}

Add the component to your HTML

{ from "@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/components/user-reports/view.njk" import dprUserReports }

{ dprUserReports(userReportsLists) }

See Reports List component for usage and examples.

Implement request route directly

If you prefer to create your own report listings, and not use DPR's Catalogue component, you can link your reports to the request path directly to start the process.

<h1>My reports list</h1>

<a href="/async/report/report-id-1/variant-id-1-1/request">Async report 1</a>
<a href="/async/report/report-id-1/variant-id-1-2/request">Async report 2</a>
<a href="/async/report/report-id-2/variant-id-2-1/request">Async report 3</a>

For information about the request path see here

Render report as list

As an alternative to requesting a report, reports can be loaded syncronously and rendered as a list.

There are three ways to render a report as a list that loads synchronously into your service:

Render using a handler

Recommended

import ReportListUtils from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/components/report-list/utils'

app.get(
  '/handler',
  ReportListUtils.createReportListRequestHandler({
    title: 'Test app',
    definitionName: 'test-report',
    variantName: 'test-variant',
    apiUrl: `http://localhost:3010`,
    apiTimeout: 10000,
    layoutTemplate: 'page.njk',
    tokenProvider: (req, res, next) => res.locals.user.token,
    definitionsPath: 'definitions/prisons/test'
  }),
)

Render using a method

import ReportListUtils from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/components/report-list/utils'

app.get('/method', (req, res, next) => {
  const args = {
    title: 'Method',
    definitionName: 'test-report',
    variantName: 'test-variant',
    apiUrl: 'http://localhost:3010',
    layoutTemplate: 'page.njk',
  }

  ReportListUtils.renderListWithDefinition({
    ...args,
    request: req,
    response: res,
    next,
  })
})

Render with data

import ReportListUtils from '@ministryofjustice/hmpps-digital-prison-reporting-frontend/dpr/components/report-list/utils'

app.get('/data', (req, res, next) => {
  const MyVariantDefinition = Promise.resolve(reportName, variantName)
  const args = {
    title: 'Test app',
    reportName: 'ReportName',
    variantDefinition: MyVariantDefinition,
    getListDataSources: () => ({
      data: Promise.resolve(data),
      count: Promise.resolve(data.length),
    }),
    otherOptions: {
      exampleOption: true,
    },
    layoutTemplate: 'page.njk',
  }

  ReportListUtils.renderListWithData({
    ...args,
    request: req,
    response: res,
    next,
  })
})