@ministryofjustice/probation-search-frontend
Version:
A shared UI component to search for probation cases from within your Express/Nunjucks application
106 lines (72 loc) • 7.51 kB
Markdown
# Probation Search Front-end Components
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
## Get started
This guide assumes you are using
the [hmpps-template-typescript](https://github.com/ministryofjustice/hmpps-template-typescript).
### 1. Install the dependency
```shell
npm install --save /probation-search-frontend
```
### 2. Add the Nunjucks component
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](https://github.com/ministryofjustice/probation-search-ui/blob/main/server/views/pages/search.njk)
### 3. Configure the Express routes
Create an instance of the `CaseSearchService`:
```ts
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
hmppsAuthClient: services.hmppsAuthClient, // a reference to your HMPPS Auth client
})
```
> Full example:
> [services/index.ts](https://github.com/ministryofjustice/probation-search-ui/blob/main/server/services/index.ts)
Then use it to set up the post and get routes for your search page.
```ts
router.post('/search', searchService.post)
router.get('/search', searchService.get, (req, res) => res.render('pages/search'))
```
> Full example:
> [routes/search.ts](https://github.com/ministryofjustice/probation-search-ui/blob/main/server/routes/search.ts)
That's it! Start your service and visit http://localhost:3000/search to try it out.
## Examples
For a fully working example, check out
the [probation-search-ui](https://github.com/ministryofjustice/probation-search-ui) project.
The front-end can be accessed here: https://probation-search-dev.hmpps.service.justice.gov.uk/search
## Configuration
### Nunjucks (front-end) configuration
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) |
### Express (back-end) configuration
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) |
| `hmppsAuthClient` | 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 |
## Support
For any issues or questions, please contact the Probation Integration team via
the [#probation-integration-tech](https://mojdt.slack.com/archives/C02HQ4M2YQN) Slack channel. Or feel free to create
a [new issue](https://github.com/ministryofjustice/probation-search-frontend/issues/new) in this repository.