From f86ab6bbed09299e87201a6b400b7b4a5cfff58c Mon Sep 17 00:00:00 2001 From: beeps Date: Wed, 21 Aug 2024 10:14:04 +0100 Subject: [PATCH] Separate Nunjucks macro options from examples - Split the Nunjucks parameter table code from the example code - Automatically insert parameter tables at the bottom of component pages - If there is only one set of parameters, the table is output immediately; otherwise, an accordion is created --- src/javascripts/application.mjs | 3 +- src/stylesheets/main.scss | 1 + views/layouts/layout-pane.njk | 2 + views/partials/_example.njk | 68 +----------------------- views/partials/_nunjucks-params.njk | 81 +++++++++++++++++++++++++++++ 5 files changed, 88 insertions(+), 67 deletions(-) create mode 100644 views/partials/_nunjucks-params.njk diff --git a/src/javascripts/application.mjs b/src/javascripts/application.mjs index 538029623f..a5f0d72f50 100644 --- a/src/javascripts/application.mjs +++ b/src/javascripts/application.mjs @@ -1,6 +1,6 @@ /* eslint-disable no-new */ -import { createAll, Button, NotificationBanner, SkipLink } from 'govuk-frontend' +import { createAll, Accordion, Button, NotificationBanner, SkipLink } from 'govuk-frontend' import { loadAnalytics } from './components/analytics.mjs' import BackToTop from './components/back-to-top.mjs' @@ -19,6 +19,7 @@ import Search from './components/search.mjs' import AppTabs from './components/tabs.mjs' // Initialise GOV.UK Frontend +createAll(Accordion) createAll(Button) createAll(NotificationBanner) createAll(SkipLink) diff --git a/src/stylesheets/main.scss b/src/stylesheets/main.scss index ecfcd3e9f2..abd085307c 100644 --- a/src/stylesheets/main.scss +++ b/src/stylesheets/main.scss @@ -6,6 +6,7 @@ $govuk-new-typography-scale: true; @import "govuk/core"; @import "govuk/objects"; +@import "govuk/components/accordion"; @import "govuk/components/back-link"; @import "govuk/components/breadcrumbs"; @import "govuk/components/button"; diff --git a/views/layouts/layout-pane.njk b/views/layouts/layout-pane.njk index b6c8f98df3..b9f21aca2a 100644 --- a/views/layouts/layout-pane.njk +++ b/views/layouts/layout-pane.njk @@ -52,6 +52,8 @@ {{ contents | safe }} + {% include "_nunjucks-params.njk" %} + {# No JS fallback to show overview #} {% if showSubNav %} {% include "_category-nav.njk" %} diff --git a/views/partials/_example.njk b/views/partials/_example.njk index 999e7ebe10..60a0c21474 100644 --- a/views/partials/_example.njk +++ b/views/partials/_example.njk @@ -80,72 +80,8 @@ {% endif -%}
{%- if (params.group == 'components') %} - {% set macroOptions = getMacroOptions(params.item) %} - - {% set macroOptionsHTML %} -

- Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text. -

-

- Some options are required for the macro to work; these are marked as "Required" in the option description. -

-

- If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits. -

- {% for table in macroOptions %} - - - - - - - - - - - {% for option in table.options -%} - {# Option name only, without parent prefix -#} - {% set optionName = option.name.split(" ") | last %} - - - - - - {% endfor %} - -
{{ table.name | safe }}
NameTypeDescription
{{ optionName | safe }}{{ option.type }} - {% if (option.required) %} - Required. - {% endif %} - {{ option.description | safe }} - {% if (option.params) or (option.isComponent and ["hint", "label"].includes(option.id)) %} - {% if option.isComponent and not ["hint", "label"].includes(option.id) %} - {# Link to subset of Nunjucks macro options table and Design System component page -#} - See supported {{ option.name | safe }} options for {{ optionName | safe }}. - {% else %} - {# Link to Nunjucks macro options table only -#} - See {{ option.name | safe }}. - {% endif %} - {% elif option.isComponent %} - {# Link to Design System component page for nested components -#} - See {{ optionName | safe }}. - {% endif %} -
- {% endfor %} - - {%- endset %} - - {%- from "govuk/components/details/macro.njk" import govukDetails %} - - {{- govukDetails({ - summaryHtml: 'Nunjucks macro options', - html: macroOptionsHTML, - classes: "app-options", - attributes:{ - id: "options-" + exampleId + "-details" - } - })}} - {% endif -%} +

Nunjucks options for this component

+ {%- endif %}
```njk diff --git a/views/partials/_nunjucks-params.njk b/views/partials/_nunjucks-params.njk new file mode 100644 index 0000000000..a40e16ead6 --- /dev/null +++ b/views/partials/_nunjucks-params.njk @@ -0,0 +1,81 @@ +{% if ["Components"].includes(section) %} + {% from "govuk/components/accordion/macro.njk" import govukAccordion %} + + {% set macroOptions = getMacroOptions(item) %} + {% set accordionSections = [] %} + + {# Utility macro for holding all the table code #} + {% macro _paramTable(table) %} + + + + + + + + + + {% for option in table.options -%} + {# Option name only, without parent prefix -#} + {% set optionName = option.name.split(" ") | last %} + + + + + + {% endfor %} + +
NameTypeDescription
{{ optionName | safe }}{{ option.type }} + {% if (option.required) %} + Required. + {% endif %} + {{ option.description | safe }} + {% if (option.params) or (option.isComponent and ["hint", "label"].includes(option.id)) %} + {% if option.isComponent and not ["hint", "label"].includes(option.id) %} + {# Link to subset of Nunjucks macro options table and Design System component page -#} + See supported {{ option.name | safe }} options for {{ optionName | safe }}. + {% else %} + {# Link to Nunjucks macro options table only -#} + See {{ option.name | safe }}. + {% endif %} + {% elif option.isComponent %} + {# Link to Design System component page for nested components -#} + See {{ optionName | safe }}. + {% endif %} +
+ {% endmacro %} + +

Nunjucks options for this component

+
+

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

+

Some options are required for the macro to work; these are marked as "Required" in the option description.

+

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

+ + {# If there is only one table, just output it to the page #} + {% if macroOptions.length === 1 %} + {{ _paramTable(macroOptions[0]) }} + + {# Otherwise, loop through them all and build out an accordion #} + {% else %} + {% for table in macroOptions %} + {% set tableName %}{{ table.name | safe }}{% endset %} + {% set tableHtml %} + {{ _paramTable(table) }} + {% endset %} + + {# Push content into an array, formatted as needed by the accordion #} + {% set accordionSections = (accordionSections.push({ + heading: { html: tableName }, + content: { html: tableHtml } + }), accordionSections)%} + {% endfor %} + + {{ govukAccordion({ + id: "nunjucks-options-accordion", + headingLevel: 3, + rememberExpanded: false, + items: accordionSections + }) }} + {% endif %} +
+{% endif %}