Update various components to be callable

CHANGELOG.md

@@ -20,6 +20,20 @@ Visit The National Archives' [documentation on OGL and Crown copyright](https://
 
 This was added in [pull request #2702: Allow localisation of content licence and copyright notices in Footer](https://github.com/alphagov/govuk-frontend/pull/2702).
 
+#### Pass HTML directly into compatible components
+
+If using the Nunjucks macros, you can now pass HTML content directly into compatible components using [the Nunjucks `call` syntax](https://mozilla.github.io/nunjucks/templating.html#call). If HTML is provided through the call syntax, the `html` and `text` options will be ignored.
+
+Components that have been updated to support this syntax are:
+
+- Details
+- Error summary (mapped to `descriptionHtml` parameter)
+- Inset text
+- Notification banner
+- Panel
+
+This was added in [pull request #2734: Update various components to be callable](https://github.com/alphagov/govuk-frontend/pull/2734).
+
 ### Deprecated features
 
 #### Remove deprecated `govuk-header__navigation--no-service-name` class in the header

src/govuk/components/details/details.yaml

@@ -15,6 +15,10 @@ params:
   type: string
   required: true
   description: If `text` is set, this is not required. HTML to use within the disclosed part of the details element. If `html` is provided, the `text` option will be ignored.
+- name: caller
+  type: nunjucks-block
+  required: false
+  description: 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 details component in a `call` block.
 - name: id
   type: string
   required: false

src/govuk/components/details/template.njk

@@ -5,6 +5,6 @@
     </span>
   </summary>
   <div class="govuk-details__text">
-    {{ params.html | safe if params.html else params.text }}
+    {{ caller() if caller else (params.html | safe if params.html else params.text) }}
   </div>
 </details>

src/govuk/components/details/template.test.js

@@ -53,6 +53,12 @@ describe('Details', () => {
     expect($summary.get(0).tagName).toEqual('summary')
   })
 
+  it('renders nested components using `call`', () => {
+    const $ = render('details', {}, '<div class="app-nested-component"></div>')
+
+    expect($('.govuk-details .app-nested-component').length).toBeTruthy()
+  })
+
   it('allows text to be passed whilst escaping HTML entities', () => {
     const $ = render('details', examples['html as text'])
 

src/govuk/components/error-summary/error-summary.yaml

@@ -15,6 +15,10 @@ params:
   type: string
   required: false
   description: HTML to use for the description of the errors. If you set this option, the component will ignore `descriptionText`.
+- name: caller
+  type: nunjucks-block
+  required: false
+  description: 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 error summary component in a `call` block.
 - name: errorList
   type: array
   required: true

src/govuk/components/error-summary/template.njk

@@ -6,9 +6,9 @@
     {{ params.titleHtml | safe if params.titleHtml else params.titleText }}
   </h2>
   <div class="govuk-error-summary__body">
-    {% if params.descriptionHtml or params.descriptionText %}
+    {% if caller or params.descriptionHtml or params.descriptionText %}
     <p>
-      {{ params.descriptionHtml | safe if params.descriptionHtml else params.descriptionText }}
+      {{ caller() if caller else (params.descriptionHtml | safe if params.descriptionHtml else params.descriptionText) }}
     </p>
     {% endif %}
     <ul class="govuk-list govuk-error-summary__list">

src/govuk/components/error-summary/template.test.js

@@ -97,6 +97,12 @@ describe('Error-summary', () => {
       expect(summaryDescription).toEqual('See <span>errors</span> below')
     })
 
+    it('renders nested components in description using `call`', () => {
+      const $ = render('error-summary', {}, '<div class="app-nested-component"></div>')
+
+      expect($('.govuk-error-summary .app-nested-component').length).toBeTruthy()
+    })
+
     it('allows additional classes to be added to the error-summary component', () => {
       const $ = render('error-summary', examples.classes)
 

src/govuk/components/inset-text/inset-text.yaml

@@ -7,6 +7,10 @@ params:
   type: string
   required: true
   description: If `text` is set, this is not required. HTML to use within the back link component. If `html` is provided, the `text` option will be ignored.
+- name: caller
+  type: nunjucks-block
+  required: false
+  description: 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 inset text component in a `call` block.
 - name: id
   type: string
   required: false

src/govuk/components/inset-text/template.njk

@@ -1,4 +1,4 @@
 <div {%- if params.id %} id="{{ params.id }}"{% endif %} class="govuk-inset-text {%- if params.classes %} {{ params.classes }}{% endif %}"
 {%- for attribute, value in params.attributes %} {{attribute}}="{{value}}"{% endfor %}>
-  {{ params.html | safe if params.html else params.text }}
+  {{ caller() if caller else (params.html | safe if params.html else params.text) }}
 </div>

src/govuk/components/inset-text/template.test.js

@@ -32,6 +32,12 @@ describe('Inset text', () => {
       expect($component.attr('id')).toEqual('my-inset-text')
     })
 
+    it('renders nested components using `call`', () => {
+      const $ = render('inset-text', {}, '<div class="app-nested-component"></div>')
+
+      expect($('.govuk-inset-text .app-nested-component').length).toBeTruthy()
+    })
+
     it('allows text to be passed whilst escaping HTML entities', () => {
       const $ = render('inset-text', examples['html as text'])
 

src/govuk/components/notification-banner/notification-banner.yaml

@@ -7,6 +7,10 @@ params:
   type: string
   required: true
   description: The HTML to use within the notification banner. You can use any string with this option. If you set `html`, `text` is not required and is ignored.
+- name: caller
+  type: nunjucks-block
+  required: false
+  description: 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 notification banner component in a `call` block.
 - name: titleText
   type: string
   required: false

src/govuk/components/notification-banner/template.njk

@@ -37,8 +37,8 @@
     </h{{ params.titleHeadingLevel | default(2) }}>
   </div>
   <div class="govuk-notification-banner__content">
-    {%- if params.html -%}
-      {{ params.html | safe }}
+    {%- if caller or params.html -%}
+      {{ caller() if caller else params.html | safe }}
     {%- elif params.text -%}
       {# Set default style for single line content #}
       <p class="govuk-notification-banner__heading">{{ params.text }}</p>

src/govuk/components/notification-banner/template.test.js

@@ -150,6 +150,12 @@ describe('Notification-banner', () => {
       expect($title.html().trim()).toEqual('<span>Important information</span>')
     })
 
+    it('renders nested components using `call`', () => {
+      const $ = render('notification-banner', {}, '<div class="app-nested-component"></div>')
+
+      expect($('.govuk-notification-banner .app-nested-component').length).toBeTruthy()
+    })
+
     it('renders title as html', () => {
       const $ = render('notification-banner', examples['title as html'])
       const $title = $('.govuk-notification-banner__title')

src/govuk/components/panel/panel.yaml

@@ -19,6 +19,10 @@ params:
   type: string
   required: true
   description: If `text` is set, this is not required. HTML to use within the panel content. If `html` is provided, the `text` option will be ignored.
+- name: caller
+  type: nunjucks-block
+  required: false
+  description: 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 panel component in a `call` block.
 - name: classes
   type: string
   required: false

src/govuk/components/panel/template.njk

@@ -5,9 +5,9 @@
   <h{{ headingLevel }} class="govuk-panel__title">
     {{ params.titleHtml | safe if params.titleHtml else params.titleText }}
   </h{{ headingLevel }}>
-  {% if params.html or params.text %}
+  {% if caller or params.html or params.text %}
   <div class="govuk-panel__body">
-    {{ params.html | safe if params.html else params.text }}
+    {{ caller() if caller else (params.html | safe if params.html else params.text) }}
   </div>
   {% endif %}
 </div>

src/govuk/components/panel/template.test.js

@@ -69,6 +69,12 @@ describe('Panel', () => {
       expect(panelTitle).toEqual('Application <strong>not</strong> complete')
     })
 
+    it('renders nested components using `call`', () => {
+      const $ = render('panel', {}, '<div class="app-nested-component"></div>')
+
+      expect($('.govuk-panel .app-nested-component').length).toBeTruthy()
+    })
+
     it('allows body text to be passed whilst escaping HTML entities', () => {
       const $ = render('panel', examples['body html as text'])