Makes the code example an exported component

Also changed the design to match the one used by the GOV.UK Design System website, so no longer dependent upon the Tabs component.
x-govuk · Nov 11, 2024 · 49bb4c5 · 49bb4c5
1 parent 0a8af6d
commit 49bb4c5
Show file tree

Hide file tree

Showing 22 changed files with 661 additions and 134 deletions.
diff --git a/docs/_components/example/_example.scss b/docs/_components/example/_example.scss
diff --git a/docs/_components/example/template.njk b/docs/_components/example/template.njk
diff --git a/docs/_layouts/sub-navigation.njk b/docs/_layouts/sub-navigation.njk
@@ -3,6 +3,10 @@
 {% block scripts %}
   <script src="/assets/iframeResizer.js"></script>
   <script>
-    iFrameResize({}, `[data-module="app-example-frame"]`)
+    iFrameResize({}, `[data-module="x-govuk-example-frame"]`)
+  </script>
+  <script src="/assets/x-govuk/all.js"></script>
+  <script>
+    window.GOVUKPrototypeComponents.initAll()
   </script>
 {% endblock %}
diff --git a/docs/assets/application.scss b/docs/assets/application.scss
@@ -1,5 +1,4 @@
 @import "govuk-frontend/dist/govuk/base";
-@import "../_components/example/example";
 
 @media screen and (min-width: 800px) {
   .app-prose-scope .govuk-table:not([tabindex]) {

diff --git a/docs/autocomplete.md b/docs/autocomplete.md
@@ -4,11 +4,29 @@ order: 3
 title: Autocomplete
 description: Help users find and select from a number of options.
 ---
+{% from "example/macro.njk" import xGovukExample %}
 
-{% from "example/macro.njk" import appExample %}
-
-{{ appExample({
-  example: "autocomplete"
+{{ xGovukExample({
+  idPrefix: "autocomplete",
+  previewPath: "/examples/autocomplete",
+  codeSamples: [
+    {
+      label: {
+        text: "HTML"
+      },
+      content: {
+        html: getHtmlCode("autocomplete")
+      }
+    },
+    {
+      label: {
+        text: "Nunjucks"
+      },
+      content: {
+        html: getNunjucksCode("autocomplete")
+      }
+    }
+  ]
 }) }}
 
 This component implements the [Accessible autocomplete pattern](https://github.com/alphagov/accessible-autocomplete) to enhance a fixed list of options provided by a `<select>` element.

diff --git a/docs/code-example.md b/docs/code-example.md
@@ -0,0 +1,72 @@
+---
+layout: sub-navigation
+order: 3
+title: Code example
+description: Show users how to use your components
+---
+{% from "example/macro.njk" import xGovukExample %}
+
+{{ xGovukExample({
+  idPrefix: "code-example",
+  previewPath: "/examples/code-example",
+  codeSamples: [
+    {
+      label: {
+        text: "HTML"
+      },
+      content: {
+        html: getHtmlCode("code-example")
+      }
+    },
+    {
+      label: {
+        text: "Nunjucks"
+      },
+      content: {
+        html: getNunjucksCode("code-example")
+      }
+    }
+  ]
+}) }}
+
+This component is used in documentation websites (like this one) to show examples and the code behind them.
+
+
+## Nunjucks macro options
+
+{% from "govuk/components/table/macro.njk" import govukTable %}
+{{ govukTable({
+  firstCellIsHeader: true,
+  head: [
+    { text: "Name" },
+    { text: "Type" },
+    { text: "Description" }
+  ],
+  rows: [
+    [
+      { text: "idPrefix" },
+      { text: "string" },
+      { text: "**Required**. A unique ID for the component on the page" }
+    ],
+    [
+      { text: "previewPath" },
+      { text: "string" },
+      { text: "URL path to a page where the example can be viewed" }
+    ],
+    [
+      { text: "codeSamples" },
+      { text: "array" },
+      { text: "A list of code samples in different languages" }
+    ],
+    [
+      { text: "codeSamples.label.text" },
+      { text: "string" },
+      { text: "The text label for the code sample, for example 'HTML'" }
+    ],
+    [
+      { text: "codeSamples.content.html" },
+      { text: "string" },
+      { text: "The code used in that sample. You may need to escape this, and may wany to apply code formatting styles." }
+    ]
+  ]
+}) }}
diff --git a/docs/examples/code-example-output.njk b/docs/examples/code-example-output.njk
@@ -0,0 +1,6 @@
+---
+eleventyExcludeFromCollections: true
+layout: example-full-width.njk
+title: Code example
+---
+<p>This is an <strong>example</strong>.</p>
diff --git a/docs/examples/code-example.njk b/docs/examples/code-example.njk
@@ -0,0 +1,37 @@
+---
+eleventyExcludeFromCollections: true
+layout: example-full-width.njk
+title: Code example
+---
+{% from "x-govuk/components/example/macro.njk" import xGovukExample %}
+
+{% set htmlCode %}
+  &lt;p&gt;This is an  &ltstrong&gt;example &lt/strong&gt;. &lt/p&gt;
+{% endset %}
+{% set nunjucksCode %}
+  {% raw %}{{ paragraph({ html: "This is an &ltstrong&gt;example &lt/strong&gt;." }) }}{% endraw %}
+{% endset %}
+
+
+{{ xGovukExample({
+  idPrefix: "my-code",
+  previewPath: "/examples/code-example-output",
+  codeSamples: [
+    {
+      label: {
+        text: "HTML"
+      },
+      content: {
+        html: htmlCode
+      }
+    },
+    {
+      label: {
+        text: "Nunjucks"
+      },
+      content: {
+        html: nunjucksCode
+      }
+    }
+  ]
+}) }}
diff --git a/docs/masthead.md b/docs/masthead.md
@@ -4,11 +4,29 @@ order: 4
 title: Masthead
 description: Introduce users to your product or service.
 ---
+{% from "example/macro.njk" import xGovukExample %}
 
-{% from "example/macro.njk" import appExample %}
-
-{{ appExample({
-  example: "masthead"
+{{ xGovukExample({
+  idPrefix: "masthead",
+  previewPath: "/examples/masthead",
+  codeSamples: [
+    {
+      label: {
+        text: "HTML"
+      },
+      content: {
+        html: getHtmlCode("masthead")
+      }
+    },
+    {
+      label: {
+        text: "Nunjucks"
+      },
+      content: {
+        html: getNunjucksCode("masthead")
+      }
+    }
+  ]
 }) }}
 
 ## When to use this component
@@ -32,14 +50,53 @@ It should appear directly below the header, and take up the full width of the pa
 
 To ensure there is no gap between the header and the masthead, create a modifier class to remove the bottom border from the header:
 
-{{ appExample({
-  example: "masthead-below-header"
+{{ xGovukExample({
+  idPrefix: "masthead-below-header",
+  previewPath: "/examples/masthead-below-header",
+  codeSamples: [
+    {
+      label: {
+        text: "HTML"
+      },
+      content: {
+        html: getHtmlCode("masthead-below-header")
+      }
+    },
+    {
+      label: {
+        text: "Nunjucks"
+      },
+      content: {
+        html: getNunjucksCode("masthead-below-header")
+      }
+    }
+  ]
 }) }}
 
+
 If your service uses [the primary navigation component](primary-navigation), this should appear directly above the masthead:
 
-{{ appExample({
-  example: "masthead-below-primary-navigation"
+{{ xGovukExample({
+  idPrefix: "masthead-below-primary-navigation",
+  previewPath: "/examples/masthead-below-primary-navigation",
+  codeSamples: [
+    {
+      label: {
+        text: "HTML"
+      },
+      content: {
+        html: getHtmlCode("masthead-below-primary-navigation")
+      }
+    },
+    {
+      label: {
+        text: "Nunjucks"
+      },
+      content: {
+        html: getNunjucksCode("masthead-below-primary-navigation")
+      }
+    }
+  ]
 }) }}
 
 You can use HTML or, if you are using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.