Make the HTML alternative arguments to text clearer

[frankieroberto]

Currently several of the Nunjucks macros also accept html arguments, as well as text, which has the effect of not escaping the HTML tags.

This is documented here: https://github.com/alphagov/govuk-frontend/blob/master/package/components/details/README.md#component-arguments and linked to from relevant components, but is easy to miss. (Well, that might just be me).

One option might be to add some documentation and examples of the HTML alternatives to the relevant component pages, eg https://design-system.service.gov.uk/components/details/

This could be achieved by some explanatory text and an alternative example like the following:

{{ govukDetails({
  summaryText: "Help with nationality",
  html: "<p>We need to know your nationality so we can work out which elections you’re entitled to vote in.</p><p>If you can’t provide your nationality, you’ll have to send copies of identity documents through the post.</p>"
}) }}

[36degrees]

Hey Frankie,

This sounds like it relates more to the way we document the components in the Design System than it does to Frontend itself? Assuming that's the case and I'm not misunderstanding, would you mind raising this issue in the Design System repo instead?

Ta!

[dashouse]

Hey Frankie,

At the moment we only use the html argument when the example we're trying to replicate cannot be achieved using the text argument alone.

As we only show the options the example the user is viewing requires, it feels like it might be hard to draw a line between showing both text / html and showing all available options like disabled or checked without needing to create multiple examples for every configuration of the component – I believe just the "items" in checkboxes have 11 arguments, so we have to balance exposing these with how the user will interact with the page.

One thing we'd like to look at in the future is a component explorer / editor that would allow you to add these arguments to a component within the example in the design system itself...however this might be some way off.

[frankieroberto]

@dashouse @36degrees hi both. Sorry for the delayed reply. To be clear: I wasn't asking to add extra html arguments, just to document the existing ones a bit more clearly. However, just taking a look at the "Nunjucks macro options" on https://design-system.service.gov.uk/components/details/#default-2-nunjucks it seems pretty clear to me now. Was that added recently, or did I just not see it before?

Either way, I think this suggestion can be closed now.

[dashouse]

Thanks @frankieroberto

I believe at the time you posted this issue the arguments only existed in the frontend README file. I'm glad that exposing them here would have made this easier. I think this got released within the last 2 or 3 months so relatively new 👍