A Nunjucks component and Express middleware to search for probation cases.
Use this component to build probation case search functionality into your HMPPS service and deliver a consistent search experience to probation practitioners.
Try it out in the dev environment: https://probation-search-dev.hmpps.service.justice.gov.uk/examples
This guide assumes you are using the hmpps-template-typescript.
npm install --save @ministryofjustice/probation-search-frontend
Use the caseSearch
component in your Nunjucks file:
{% from "probation/case-search/macro.njk" import caseSearch %}
{{ caseSearch({
id: "search",
results: searchResults
}) }}
Full example: views/search.njk
Create an instance of the CaseSearchService
:
import CaseSearchService from '@ministryofjustice/probation-search-frontend/service/caseSearchService'
const searchService = new CaseSearchService({
environment: config.environment, // whether you want to search cases in the dev, preprod or prod environment
oauthClient: service.hmppsAuthClient, // a reference to your HMPPS Auth client
})
Full example: services/index.ts
Then use it to set up the post and get routes for your search page.
router.post('/search', searchService.post)
router.get('/search', searchService.get, (req, res) => res.render('pages/search'))
Full example: routes/search.ts
That's it! Start your service and visit http://localhost:3000/search to try it out.
For a fully working example, check out the probation-search-ui project.
The front-end can be accessed here: https://probation-search-dev.hmpps.service.justice.gov.uk/search
The caseSearch
Nunjucks macro takes the following options:
Option | Description | Default |
---|---|---|
label |
The label used by the text input component. | "Find a person on probation" |
hint |
Can be used to add a hint to the text input component. | "You can search by name, date of birth or any other identifier (for example CRN or PNC id)." |
id |
The id of the text input field | "search" |
type |
Type of input control to render. | "search" |
classes |
Classes to add to the input. | "" |
results |
This must always be set to searchResults . The value of searchResults is populated by the Express routes, and contains the results of the search query to be rendered by the component. |
(none) |
The CaseSearchService
function takes the following options:
Option | Description | Default |
---|---|---|
environment |
Whether you want to search cases in the dev, preprod or prod environment. You can also specify local to use some hard-coded test data - override the test data by setting localData . |
(none) |
oauthClient |
A function for returning a HMPPS Auth client_credentials token. This will be used to get a token for calling the Probation Search API. | (none) |
resultPath |
A function used to generate a link to the case in your service, based on the case reference number (CRN). | (crn: string) => /case/${crn}
|
extraColumns |
An optional array of extra columns to display in search results, in addition to Name, CRN, and Date of Birth. For example, to add an Age column: [{ header: 'Age', result => result.age }] . |
[] |
pageSize |
The number of results to return per page. | 10 |
maxPagesToShow |
The maximum number of pages to show on the paginator. | 7 |
localData |
A list of search results to return during local development (i.e. when environment = 'local') | Two dummy records - John Doe and Jane Doe |
For any issues or questions, please contact the Probation Integration team via the #probation-integration-tech Slack channel. Or feel free to create a new issue in this repository.