Make it clear that the "html" attribute can be unsafe

What

We had a discussion on a design system slack channel about the documentation not to encourage the use of html parameter in macros. We concluded, we shouldn’t take away that functionality, but make it clear it’s unsafe to use, causing people to rethink the strategy or apply necessary fixes before hand.

Why

It’s more efficient to copy and paste a block of text without realising what it’s doing. It could easily bring some XSS vulnerability into the application by accident, which we’d all like to avoid.

Proposal

Changing the name of the html attribute is a good start. This will need to be followed by some documentation changes on the Design System.

Before

{% from "panel/macro.njk" import govukPanel %}

{{ govukPanel({
  "titleText": "Application complete",
  "html": "Your reference number<br><strong>HDJ2123F</strong>"
})
}}

After

{% from "panel/macro.njk" import govukPanel %}

{{ govukPanel({
  "titleText": "Application complete",
  "unsafeHTML": "Your reference number<br><strong>HDJ2123F</strong>"
})
}}

Connection

alphagov/govuk-design-system#175

[joelanman]

I guess the main point I’m trying to make is, html param should be an exception - if we’re having to use it commonly that seems like we could investigate that macro to meet the common need a different way. The idea of macros is to avoid people writing their own html.

[36degrees]

I think we definitely can and should do more to support call, but it’s only going to be helpful for components that have one obvious ‘area’ that accepts HTML, and it won’t help where components call other components (such as passing HTML to the label that’s inside a text input).