Merge pull request #1201 from nhsuk/add-html-param-to-hero

Add missing params to hero component

Author: colinrotherham

CHANGELOG.md

@@ -61,6 +61,12 @@ You can now add `classes` and `attributes` to table cells, for example using the
 
 This was added in [pull request #1172: Add table cell `classes` and `attributes` param support](https://github.com/nhsuk/nhsuk-frontend/pull/1172).
 
+#### Add html content and heading attributes to hero
+
+You can now use `caller`, `html`, `headingClasses` and `headingLevel` in the hero component.
+
+This was added in [pull request #1201: Add missing params to hero component](https://github.com/nhsuk/nhsuk-frontend/pull/1201).
+
 #### Default bottom margin on tables
 
 This was added in [pull request #1005: Update table styles so nhsuk-table has bottom margin](https://github.com/nhsuk/nhsuk-frontend/pull/1005).

app/_templates/layout.njk

@@ -1,8 +1,6 @@
 {% extends 'template.njk' %}
 {% block pageTitle %}{{ title }} - NHS.UK Frontend{% endblock %}
 
-{% set assetPath = "/nhsuk-frontend/assets" %}
-
 {% block head %}
   <link href="https://www.nhs.uk/" rel="preconnect">
   <link href="https://assets.nhs.uk/" rel="preconnect" crossorigin>

app/components/button/link.njk

@@ -7,7 +7,7 @@
     <div class="nhsuk-grid-column-two-thirds">
       {{ button({
         "text": "Link button",
-        "href": "/nhsuk-frontend/"
+        "href": baseUrl
       }) }}
     </div>
   </div>

app/components/hero/hero-with-html.njk

@@ -0,0 +1,19 @@
+{% set title = 'Hero' %}
+{% from 'components/hero/macro.njk' import hero %}
+{% from 'components/button/macro.njk' import button %}
+
+{% extends 'example.njk' %}
+
+{% block main %}
+  {% call hero({
+    heading: "This is a header for the product or service",
+    headingClasses: "nhsuk-heading-l nhsuk-u-margin-top-5"
+  }) %}
+    <p class="nhsuk-body-l">This is some more content which explains a bit more about the product or service.</p>
+
+    {{ button({
+      text: "Sign up",
+      classes: "nhsuk-button--reverse"
+    }) }}
+  {% endcall %}
+{% endblock %}

app/pages/examples.njk

@@ -88,7 +88,8 @@
     <li><a href="../components/header/header-org-white-nav.html">Header organisational with white header and navigation</a></li>
     <li><a href="../components/hero/index.html">Hero</a></li>
     <li><a href="../components/hero/hero-image.html">Hero with image</a></li>
-    <li><a href="../components/hero/hero-image-content.html">Hero with image with content</a></li>
+    <li><a href="../components/hero/hero-image-content.html">Hero with image, text content</a></li>
+    <li><a href="../components/hero/hero-with-html.html">Hero with HTML content</a></li>
     <li><a href="../components/hint/index.html">Hint</a></li>
     <li><a href="../components/images/index.html">Images</a></li>
     <li><a href="../components/input/index.html">Input</a></li>

packages/components/hero/README.md

@@ -103,12 +103,16 @@
 
 The hero macro takes the following arguments:
 
-| Name           | Type   | Required | Description                                                                                 |
-| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
-| **heading**    | string | No       | Text heading of the hero component.                                                         |
-| **text**       | string | No       | Text content of the hero component.                                                         |
-| **imageURL**   | string | No       | URL of the image of the hero component.                                                     |
-| **classes**    | string | No       | Optional additional classes to add to the hero container. Separate each class with a space. |
-| **attributes** | object | No       | Any extra HTML attributes (for example data attributes) to add to the hero container.       |
+| Name               | Type           | Required | Description                                                                                                                                                                                                                                                                                                                                           |
+| ------------------ | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **heading**        | string         | No       | Text heading of the hero component                                                                                                                                                                                                                                                                                                                    |
+| **headingClasses** | string         | No       | Optional additional classes to add to heading. Separate each class with a space.                                                                                                                                                                                                                                                                      |
+| **headingLevel**   | integer        | No       | Optional heading level for the heading. Default: `1`                                                                                                                                                                                                                                                                                                  |
+| **text**           | string         | No       | Text content of the hero component. If `html` is provided, the `text` argument will be ignored.                                                                                                                                                                                                                                                       |
+| **html**           | string         | No       | HTML content of the hero component. If `html` is provided, the `text` argument will be ignored.                                                                                                                                                                                                                                                       |
+| **caller**         | nunjucks-block | No       | Not strictly a parameter but [Nunjucks code convention](https://mozilla.github.io/nunjucks/templating.html#call). Using a `call` block enables you to call a macro with all the text inside the tag. This is helpful if you want to pass a lot of content into a macro. To use it, you will need to wrap the entire hero component in a `call` block. |
+| **imageURL**       | string         | No       | URL of the image of the hero component.                                                                                                                                                                                                                                                                                                               |
+| **classes**        | string         | No       | Optional additional classes to add to the hero container. Separate each class with a space.                                                                                                                                                                                                                                                           |
+| **attributes**     | object         | No       | Any extra HTML attributes (for example data attributes) to add to the hero container.                                                                                                                                                                                                                                                                 |
 
 If you are using Nunjucks macros in production be aware that using `html` arguments, or ones ending with `html` can be a [security risk](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting). Read more about this in the [Nunjucks documentation](https://mozilla.github.io/nunjucks/api.html#user-defined-templates-warning).

packages/components/hero/_hero.scss

@@ -15,6 +15,10 @@
   color: $color_nhsuk-white;
   position: relative; // [1]
 
+  a {
+    @include nhsuk-link-style-white;
+  }
+
   .nhsuk-hero--border {
     // [2]
     border-top: $nhsuk-hero-border solid $nhsuk-secondary-border-color;
@@ -26,6 +30,10 @@
   @include nhsuk-responsive-padding(8, bottom);
 }
 
+.nhsuk-hero__heading {
+  @include nhsuk-responsive-margin(3, bottom);
+}
+
 ///  Hero component image styles
 ///
 /// 3. Center the background image.
@@ -84,8 +92,15 @@
 /// 13. Remove the arrow in Windows high contrast mode.
 /// 14. Reduce spacing and change positioning for Windows high contrast mode.
 /// 15. Prevent text breaking out of box on smaller sizes
+/// 16. Prevent overlap using safe area: box offset + arrow height + spacing
 
 .nhsuk-hero--image-description {
+  margin-bottom: calc(70px + 20px + nhsuk-spacing(3)); // [16]
+
+  @include mq($from: tablet) {
+    margin-bottom: calc(48px + 20px + nhsuk-spacing(4)); // [16]
+  }
+
   .nhsuk-hero-content {
     background-color: $color_nhsuk-blue;
     color: $color_nhsuk-white;

packages/components/hero/template.njk

@@ -1,20 +1,34 @@
 {% from "../../macros/attributes.njk" import nhsukAttributes %}
 
+{% set headingLevel = params.headingLevel if params.headingLevel else 1 -%}
+
 <section class="nhsuk-hero
 {%- if params.imageURL and params.heading %} nhsuk-hero--image nhsuk-hero--image-description
 {%- elif params.imageURL %} nhsuk-hero--image{% endif %}
 {%- if params.classes %} {{ params.classes }}{% endif %}"
 {%- if params.imageURL %} style="background-image: url('{{ params.imageURL }}');"{% endif %}
 {{- nhsukAttributes(params.attributes) }}>
 {% if params.imageURL %}<div class="nhsuk-hero__overlay">{% endif %}
-{%- if params.heading %}
+{%- if caller or params.heading or params.text or params.html %}
   <div class="nhsuk-width-container{% if not params.imageURL %} nhsuk-hero--border{% endif %}">
     <div class="nhsuk-grid-row">
       <div class="nhsuk-grid-column-two-thirds">
         <div class="{% if params.imageURL %}nhsuk-hero-content{% else %}nhsuk-hero__wrapper{% endif %}">
-          <h1 {% if params.text %}class="nhsuk-u-margin-bottom-3"{% endif %}>{{ params.heading }}</h1>
-          {% if params.text %}<p class="nhsuk-body-l nhsuk-u-margin-bottom-0">{{ params.text }}</p>{% endif %}
-          {% if params.imageURL %}<span class="nhsuk-hero__arrow" aria-hidden="true"></span>{% endif %}
+          {%- if params.heading -%}
+            <h{{ headingLevel }} class="nhsuk-hero__heading
+              {%- if params.headingClasses %} {{ params.headingClasses }}{% endif %}
+              {%- if not (caller or params.text or params.html) %} nhsuk-u-margin-bottom-0{% endif %}">
+              {{- params.heading -}}
+            </h{{ headingLevel }}>
+          {%- endif %}
+          {% if caller or params.html -%}
+            {{ caller() if caller else params.html | safe }}
+          {%- elif params.text -%}
+            <p class="nhsuk-body-l nhsuk-u-margin-bottom-0">{{ params.text }}</p>
+          {%- endif %}
+          {% if params.imageURL -%}
+            <span class="nhsuk-hero__arrow" aria-hidden="true"></span>
+          {%- endif %}
         </div>
       </div>
     </div>

tasks/docs.js

@@ -32,6 +32,7 @@ async function buildHTML() {
     const { name, dir } = parse(path)
 
     const html = env.render(path, {
+      assetPath: `/nhsuk-frontend/assets`,
       baseUrl: '/nhsuk-frontend/',
       version
     })