Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Makes the code example an exported component #264

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Makes the code example an exported component #264

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 0 additions & 33 deletions docs/_components/example/_example.scss
View file
Open in desktop

This file was deleted.

38 changes: 0 additions & 38 deletions docs/_components/example/template.njk
View file
Open in desktop

This file was deleted.

6 changes: 5 additions & 1 deletion docs/_layouts/sub-navigation.njk
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]`)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The requirement to add the iFrame script to both the source content and the page that consumes the component either needs incorporating into the component somehow, else documenting how to set up. Part of me wonders if their might be something cleaver we could do with web components, but that’d be very different to how other components work.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah this is super annoying. Seems odd that there’s no way to set an iframe to natively resize to its contents but I guess there were performance reasons why that wasn’t built in?

Could bundle the iframeresizer script with the xGovukExample component javascript itself, but that means an extra dependency and might be tricky? Possibly worth investigating still though. Otherwise we’d just have to document it well as something extra that you have to add to make dynamic iframe sizing work. Possibly there’s some contexts where a fixed height would be ok and you wouldn’t need it, but it does feel quite essential?

</script>
<script src="/assets/x-govuk/all.js"></script>
<script>
window.GOVUKPrototypeComponents.initAll()
</script>
{% endblock %}
1 change: 0 additions & 1 deletion docs/assets/application.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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]) {
Expand Down
26 changes: 22 additions & 4 deletions docs/autocomplete.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
}
}
]
}) }}
frankieroberto marked this conversation as resolved.
Show resolved Hide resolved

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.
Expand Down
72 changes: 72 additions & 0 deletions docs/code-example.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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." }
]
]
}) }}
6 changes: 6 additions & 0 deletions docs/examples/code-example-output.njk
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
eleventyExcludeFromCollections: true
layout: example-full-width.njk
title: Code example
---
<p>This is an <strong>example</strong>.</p>
37 changes: 37 additions & 0 deletions docs/examples/code-example.njk
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
}
}
]
}) }}
73 changes: 65 additions & 8 deletions docs/masthead.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down
Loading
Loading