passports-components

Nunjucks components and filters for building gov.uk pages with hmpo-form-wizard

Installation

npm install [--save] hmpo-components;

Usage

const path = require('path');
const express = require('express');
const i18n = require('hmpo-i18n');
const hmpoComponents = require('hmpo-template-components');

let views = [
    path.resolve(__dirname, 'views'),
    path.resolve(__dirname, 'node_modules', 'hmpo-components', 'components'),
    path.resolve(__dirname, 'node_modules', 'govuk-frontend', 'dist'),
    path.resolve(__dirname, 'node_modules', 'govuk-frontend', 'dist', 'components')
];

let nunjucksEnv = nunjucks.configure(views, { express: app });
i18n.middleware(app);
hmpoComponents.setup(app, nunjucksEnv);

app.set('view engine', 'html');

app.use(function (req, res) {
    res.render('mytemplate');
});

If rendering as part of an HMPO controller's middleware chain then the field configuration will automatically be set to res.locals.options.fields by the controller, and will be loaded from here by the components

Translation

Translation is performed using a req.translate local function, for example as provided by hmpo-i18n

Components

Components can be called as macros:

{% from "hmpo-input/macro.njk" import hmpoInput %}
{% from "hmpo-submit/macro.njk" import hmpoSubmit %}

{{ hmpoInput(ctx, { id: "fieldId" }) }}
{{ hmpoSubmit(ctx, { key: "textKey" }) }}

Available form wizard components:

hmpoForm(ctx, params)
hmpoErrorGroup(ctx, params)
hmpoAutoSubmit(ctx, params)
hmpoSubmit(ctx, params)

hmpoCheckboxes(ctx, params);
hmpoDate(ctx, params)
hmpoNumber(ctx, params)
hmpoPhone(ctx, params)
hmpoRadios(ctx, params)
hmpoSelect(ctx, params)
hmpoText(ctx, params)
hmpoTextarea(ctx, params)

Field parameters

Most govuk-frontend parameters can be specified in the fields config, or supplied to the component directly. Label, hint, and legend text is loaded from localisation using a default key structure unless overridden.

• label.key: overridden label key.
• legend.key: overridden legend key.
• hint.key: overridden hint key
• items: Array of select box, radio, or checkbox options, or an Array of govuk item objects.
• legend: Applicable to radio button controls, which are wrapped in a HTML fieldset with a legend element.

Other available components:

hmpoCharsLeft(params);
hmpoCircleStep(params);
hmpoCircleStepList(params);
hmpoClose(params);
hmpoCookieBanner(params);
hmpoDetails(params)
hmpoFlashCard(params)
hmpoFooter(params)
hmpoInsetText(params)
hmpoPrintPage(params)
hmpoSidebar(params)
hmpoWarningText(params)

Helper and formatting components:

hmpoHtml(obj)

Filters

translate
selected
lowercase
uppercase
capscase
hyphenate
date
time
currency
currencyOrFree
url
filter

date filter

Dates should be provided a a format that moment can decode, such as ISO String format, moment object, or epoch milliseconds.

{{ "2017-06-03T12:34:56.000Z" | date }}
3 June 2017

A moment format can be supplied. The default format is D MMMM YYYY.

{{ "2017-06-3T12:34:56.000Z" | date("DD MMM YYYY HH:MMa") }}
03 Jun 2017 12:34pm

time filter

The time formatter wraps a formatted time to correct for GDS standard:

{{ "3:00pm" | time }}
3pm

{{ "11 May 2017 at 12:00pm" | time }}
11 May 2017 at midday

{{ "12:00am" | time }}
Midnight

Options can be provided to only do transforms for midday, midnight, or shortened time:

{{ "12:00pm" | time({ short: true, midnight: true, midnight: false }) }}
12pm

Controller mixins

Use the controller mixins to extend the base wizard controller:

const BaseController = require('hmpo-form-wizard').Controller;
const DateControllerMixin = require('hmpo-components').mixins.Date;

const DateController = DateControllerMixin(BaseController);

class MyController extends DateController {    
}

DateController mixin

The DateController mixin adds day, month, and year fields for a YYYY-MM-DD date field so the hmpoDate component can be validated and processed properly.

The date field must use the date validator to use this functionality.

Additional validation errors can be produced and need localisation, for example:

"validation": {
    "date": "Enter a complete {{name}}",
    "date-year": "Enter a valid year",
    "date-month": "Enter a valid month",
    "date-day": "Enter a valid day",

    "required-day": "Enter a complete {{name}}",
    "required-month": "Enter a complete {{name}}",
    "required-year": "Enter a complete {{name}}",

    "numeric-year": "Enter a year using numbers only",
    "numeric-month": "Enter a month using numbers only",
    "numeric-day": "Enter a day using numbers only"
}

Breaking changes

3.0.0

• The error summary now links to the form field causing the error instead of the error text div. You can add a field parameter to custom errors to an error to override the link.
• The first item in a set of radio buttons or checkboxes will now have the id set to fieldname instead of fieldname-value.

5.0.0

• This version should only be used with govuk-frontend >= 4. See the govuk-frontend changelog for other breaking changes.
• Summary lists have the hmpo styling by default. this can be turned off with a css variable $hmpo-summary-list: false;
• The hmpo small font styling is applied by default. This can be changed using the css variable $hmpo-text-size: "big";