feat(prototype kit integration): users of prototype-kit-v13 should have macros and filters available

[nataliecarey]

Description of the change

In version 13 of GOV.UK Prototype Kit we have some new integration points. This makes use of the new integration points and makes the installation simpler for users. Specifically, for moj-frontend, this will import all the nunjucks macros (components) and filters without the user having to do any setup themselves.

Alternative designs

You could leave the govuk-prototype-kit.config.json as-is and it will still work with the same features. The mechanism for including filters has changed so users of the kit would need to add some code to their prototypes to handle this.

Ultimately, using the config saves the kit user from having to wire these things in for themselves. The alternative is to instruct users on how to integrate these features.

Possible drawbacks

The only concern I have is for a potential conflict with the date filter, that can be resolved by namespacing it. The fact these filters are now added by default means that users might find it harder to work around that conflict if it appears.

This is a backwards compatible change, it can be updated release-by-release.

Verification process

I have tested this against the latest version of govuk-prototype-kit. You can test this by running:

npx --package=alphagov/govuk-prototype-kit#v13 govuk-prototype-kit create -v local path/to/crated/kit
cd path/to/crated/kit
npm start

You can then install this new version of moj-frontend into the kit, I've been doing that with the command:

npm run build:package && cd package && tar -czpf ../moj-frontend.tar.gz . && cd ..
cd ~/wherever-the-kit-is
npm install ~/wherever-moj-frontend-is/moj-frontend.tar.gz

(you can use the package directory without compressing it first but NPM handles the dependencies differently which can be pretty annoying). The view I'm using to test is:

{% extends "layout.html" %}

{% block pageTitle %}
  Home – {{ serviceName }} – GOV.UK Prototype Kit
{% endblock %}

{% block header %}


      {{ mojHeader({
        organisationLabel: {
          text: 'Organisation name',
          href: '#'
        },
        serviceLabel: {
          text: 'Service name',
          href: '#'
        },
        navigation: {
          label: 'Account navigation',
          items: [{
            text: 'Account name',
            href: '#',
            active: true
          }, {
            text: 'Sign out',
            href: '#'
          }]
        }

      }) }}
{% endblock %}

{% block content %}


  <div class="govuk-grid-row">

    <div class="govuk-grid-column-one-third">

      {{ mojSideNavigation({
        label: 'Side navigation',
        items: [{
          text: 'Nav item 1',
          href: '#1',
          active: true
        }, {
          text: 'Nav item 2',
          href: '#2'
        }, {
          text: 'Nav item 3',
          href: '#3'
        }]
      }) }}

    </div>

    <div class="govuk-grid-column-two-thirds">



      {{ mojOrganisationSwitcher({
        text: 'HMP Sheppey Cluster (Swaleside)',
        link: {
          text: 'Change prison',
          href: '#'
        }
      }) }}



      {{ mojPrimaryNavigation({
        label: 'Primary navigation',
        items: [
          {
            text: 'Nav item 1',
            href: '#1',
            active: true
          },
          {
            text: 'Nav item 2',
            href: '#2'
          },
          {
            text: 'Nav item 3',
            href: '#3'
          }
        ]
      }) }}



      {{ mojSearch({
        action: '#',
        method: 'post',
        input: {
          id: 'search',
          name: 'search'
        },
        label: {
          text: 'Find a person',
          classes: 'govuk-!-font-weight-bold'
        },
        hint: {
          text: 'You can search by name, date of birth or national insurance number'
        },
        button: {
          text: 'Search'
        }
      }) }}



      {{ mojIdentityBar({
        title: {
          html: "<b>Jane Wolenksy</b> and <b>Simon Wolensky</b>"
        }
      }) }}


      {{ mojSubNavigation({
        label: 'Sub navigation',
        items: [{
          text: 'Nav item 1',
          href: '#1',
          active: true
        }, {
          text: 'Nav item 2',
          href: '#2'
        }, {
          text: 'Nav item 3',
          href: '#3'
        }]
      }) }}


      {{ mojNotificationBadge({
        text: "10"
      }) }}

      

      {{ mojPageHeaderActions({
        heading: {
          text: 'Documents'
        },
        items: [{
          text: 'Upload new',
          classes: 'govuk-button--secondary'
        }, {
          text: 'Share collection',
          classes: 'govuk-button--secondary'
        }]
      }) }}



      {{ mojButtonMenu({
        items: [{
          text: "Primary action",
          href: "#"
        }, {
          text: "Second action",
          href: "#",
          classes: "govuk-button--secondary"
        }, {
          text: "Third action",
          href: "#",
          classes: "govuk-button--secondary"
        }]
      }) }}



      {%- set filterOptionsHtml %}
        <br/>(filter options)
      {% endset -%}

      {{ mojFilter({
        heading: {
          text: 'Filter'
        },
        selectedFilters: {

          heading: {
            text: 'Selected filters'
          },

          clearLink: {
            text: 'Clear filters'
          },

          categories: [
            {
              heading: {
              text: 'Type'
            },
              items: [{
              href: '/path/to/remove/this',
              text: 'Blue'
            }, {
              href: '/path/to/remove/this',
              text: 'Yellow'
            }]
            },
            {
              heading: {
              text: 'Status'
            },
              items: [{
              href: '/path/to/remove/this',
              text: 'Completed'
            }]
            }
          ]
        },
        optionsHtml: filterOptionsHtml
      }) }}



      {{ mojPagination({
        items: [{
          text: '1',
          href: '/page=1'
        }, {
          text: '2',
          href: '/page=2',
          selected: true
        }, {
          text: '3',
          href: '/page=3'
        }, {
          type: 'dots'
        }, {
          text: '5',
          href: '/page=5'
        }],
        results: {
          count: 30,
          from: 10,
          to: 20,
          text: 'pages'
        },
        previous: {
          text: 'Previous',
          href: ''
        },
        next: {
          text: 'Next',
          href: ''
        }
      }) }}


      {% set bannerHtml %}
        <h2 class="govuk-heading-m">This service will be unavailable from 1 June 2019</h2>
      {% endset %}

      {{ mojBanner({
        type: 'information',
        html: bannerHtml
      }) }}



      {{ mojBadge({
        text: 'Recently added'
      }) }}


      {{ mojMessages({
        items: [
          {
            text: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
            type: 'sent',
            timestamp: '2019-03-16T10:50:00.000Z',
            sender: 'Person A'
          },
          {
            text: 'Nullam vestibulum lorem vulputate velit euismod luctus.',
            type: 'received',
            timestamp: '2019-03-17T10:51:00.000Z',
            sender: 'Person B'
          },
          {
            text: 'Fusce et vulputate justo. Integer suscipit felis non urna lobortis, vel finibus sem tristique.',
            type: 'sent',
            timestamp: '2019-03-19T10:53:00.000Z',
            sender: 'Person A'
          },
          {
            text: 'Mauris tincidunt feugiat orci et convallis. Nam efficitur gravida justo non lobortis. Aliquam velit ante, lobortis eu venenatis sit amet, semper sit amet justo.',
            type: 'sent',
            timestamp: '2019-03-19T10:55:00.000Z',
            sender: 'Person A'
          },
          {
            text: 'Proin dapibus, nisl id ultricies ultricies, erat magna pulvinar risus, sit amet commodo nunc purus eu nulla. Aliquam erat volutpat. Vestibulum in ante interdum, elementum arcu vel, viverra nibh. Etiam ultrices urna at suscipit sollicitudin. Nulla non lectus magna. Curabitur vel vestibulum lorem. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.',
            type: 'received',
            timestamp: '2019-03-21T11:56:00.000Z',
            sender: 'Person B'
          }
        ]
      }) }}



      {{ mojTicketPanel({
        attributes: {
          'aria-label': 'Sub navigation 1'
        },
        items: [{
          html: ' <h2 class="govuk-heading-m govuk-!-margin-bottom-2">This is a heading 2</h2>
    <p class="govuk-body">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
    <a class="govuk-button govuk-!-margin-bottom-1" data-module="govuk-button">
      Save and continue
    </a>',
          attributes: {
            'aria-label': 'Section 1'
          },
          classes: 'moj-ticket-panel__content--blue'
        }]
      }) }}



      {%- set confirmationHtml %}
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras non felis risus. Curabitur nec ante vitae felis ullamcorper tincidunt.</p>
        <a class="govuk-button govuk-!-margin-bottom-0" href="#">Continue</a>
      {% endset -%}

      {%- set detailsHtml %}
        <details class="govuk-details govuk-!-margin-bottom-0">
          <summary class="govuk-details__summary">
    <span class="govuk-details__summary-text">
      Application details
    </span>
          </summary>
          <div class="govuk-details__text">
            Ut quam nunc, vulputate ac metus pharetra, posuere maximus velit. <a class="govuk-link" href="#">Etiam nec interdum velit.</a> Suspendisse molestie lectus in eros ornare
          </div>
        </details>
      {% endset -%}

      {%- set listHtml %}
        <ul class="govuk-list govuk-list--bullet">
          <li><a class="govuk-link" href="#">Item 1</a></li>
          <li><a class="govuk-link" href="#">Item 2</a></li>
        </ul>
      {% endset -%}

      {%- set documentsHtml %}
        <ul class="moj-timeline__documents">
          <li class="moj-timeline__document-item">
            <a class="govuk-link" href="#">
              <svg class="moj-timeline__document-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 20" width="20" height="16">
                <path d="M9 7V1.5L14.5 7H9zM2 0C.9 0 0 .9 0 2v16c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V6l-6-6H2z"/>
              </svg>
              Document 1
            </a>
          </li>
          <li class="moj-timeline__document-item">
            <a class="govuk-link" href="#">
              <svg class="moj-timeline__document-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 20" width="20" height="16">
                <path d="M9 7V1.5L14.5 7H9zM2 0C.9 0 0 .9 0 2v16c0 1.1.9 2 2 2h12c1.1 0 2-.9 2-2V6l-6-6H2z"/>
              </svg>
              Document 2
            </a>
          </li>
        </ul>
      {% endset -%}

      {{ mojTimeline({
        items: [
          {
            label: {
            text: "Application requires confirmation"
          },
            html: confirmationHtml,
            datetime: {
            timestamp: "2019-06-14T14:01:00.000Z",
            type: "datetime"
          },
            byline: {
            text: "Joe Bloggs"
          }
          },
          {
            label: {
            text:  "Application review in progress"
          },
            text: "Your application is being reviewed by one of our case workers.",
            datetime: {
            timestamp: "2019-06-07T12:32:00.000Z",
            type: "datetime"
          },
            byline: {
            text: "Caseworker 1"
          }
          },
          {
            label: {
            text:  "Application received"
          },
            text: "Your application has been received – reference MOJ-1234-5678",
            datetime: {
            timestamp: "2019-06-06T09:12:00.000Z",
            type: "datetime"
          },
            byline: {
            text: "Caseworker 1"
          }
          },
          {
            label: {
            text:  "Application submitted"
          },
            html: detailsHtml,
            datetime: {
            timestamp: "2019-05-28T10:45:00.000Z",
            type: "datetime"
          },
            byline: {
            text: "Joe Bloggs"
          }
          },
          {
            label: {
            text:  "Documents uploaded"
          },
            html: documentsHtml,
            datetime: {
            timestamp: "2019-05-28T10:15:00.000Z",
            type: "datetime"
          },
            byline: {
            text: "Joe Bloggs"
          }
          },
          {
            label: {
            text:  "Application started"
          },
            html: listHtml,
            datetime: {
            timestamp: "2019-05-21T13:15:00.000Z",
            type: "datetime"
          },
            byline: {
            text: "Joe Bloggs"
          }
          }
        ]
      }) }}
      
      

    </div>
  </div>

{% endblock %}

Release notes

• Using the new features of the prototype-kit integration to include filters and components for the user

[gregtyler]

Thanks @nataliecarey, this is great functionality from the prototype kit and I really appreciate you doing the PR on our side too 🚀

[gregtyler]

🎉 This PR is included in version 1.6.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀