Prevent issues with conditionally revealed content when content id includes CSS syntax characters

[36degrees]

Because the string passed to querySelector is evaluated as a CSS selector, this can fail (throwing a JavaScript error) if the ID contains characters that have a special meaning in CSS, such as . or [] – the ID would need to be escaped for it to be evaluated correctly.

Avoid this by using document.getElementById instead, so the ID is no longer evaluated as a selector.

The downside is that we can't constrain the scope to the $module. However, we don't think this should cause any issues as the ID should be unique within the document.

Details of breaking change

• which users are affected: anyone using conditional reveals
• the change that’s been made: when looking for the revealed content associated with a checkbox or radio, the JavaScript will now look for it across the entire page rather than only looking within that set of radios or checkboxes
• changes users will have to make: ensure that all IDs on a page are unique, and that checkboxes / radios with conditionally revealed content are using the right ID for their content
• impact of users not making those changes: if a page has multiple elements with the same ID (which is technically invalid HTML) radios or checkboxes may now cause the wrong element on the page to appear / disappear when selecting a checkbox or radio

Closes #1808

[vanitabarrett]

Thanks Ollie, this change makes sense to me. Probably worth updating either the PR or the issue to explain which users will be affected by this change and what they might need to do, to help Eoin draft some release notes.

[36degrees]

Needs to be merged after #2255 once the target branch has automagically updated.

[36degrees]

First attempt at a changelog entry:

The JavaScript for radios and checkboxes with conditionally-revealed content will now look for the conditionally-revealed content anywhere on the page rather than only looking within the same set of radios or checkboxes.

If you re-use the same id multiple times on a single page, this change could cause a radio or checkbox to hide and reveal the wrong element on the page.

Make sure that any radios or checkboxes with conditionally revealed content behave as expected. If you are seeing unexpected behaviour, make sure that the id for the revealed content is unique within the page it appears on.

Or, an alternative version which tries less hard to abstract technical details and language (which may be clearer for users who are more familiar with JavaScript, but is arguably harder to understand for everyone else):

The JavaScript for radios and checkboxes with conditionally-revealed content will now look for the conditionally-revealed content using document.getElementById rather than being scoped to the same set of radios or checkboxes.

If you re-use the same id multiple times on a single page, this change could cause a radio or checkbox to hide and reveal the wrong element on the page.

Make sure that any radios or checkboxes with conditionally revealed content behave as expected. If you are seeing unexpected behaviour, make sure that the id for the revealed content is unique within the page it appears on.

I don't know if it's also worth mentioning that using the same id for multiple elements is also invalid HTML?

@EoinShaughnessy any thoughts on the above?

[EoinShaughnessy]

@36degrees Changelog entry is taking shape nicely! I'd lean towards using the first, simpler version, to help any users who may be less familiar with JS. (Plus, the final PR will mention document.getElementById, right? So we're not short-changing our more JS-savvy users.)

I don't know if it's also worth mentioning that using the same id for multiple elements is also invalid HTML?

Depends, I guess. This sounds like a borderline thing between writing Design System-specific instructions and telling people how to use HTML. Maybe, by saying multiple uses could display the wrong element, we've already given enough caution.

The JavaScript for radios and checkboxes with conditionally-revealed content will now look for the conditionally-revealed content anywhere on the page rather than only looking within the same set of radios or checkboxes.

If you re-use the same id multiple times on a single page, this change could cause a radio or checkbox to hide and reveal the wrong element on the page.

Make sure that any radios or checkboxes with conditionally revealed content behave as expected. If you are seeing unexpected behaviour, make sure that the id for the revealed content is unique within the page it appears on.

First paragraph is about JS looking anywhere on the page. Second and third paragraphs are about reuse of ID. Is that ok?

Maybe combine the second and third paragraphs, and reverse their order? Something like in the suggested revision below:

JavaScript now looks across whole page for conditional reveals

On radios and checkboxes with conditionally revealed content, the JavaScript now looks for the content anywhere on the page. Before, it only looked within the same set of radios or checkboxes.

Make sure any radios or checkboxes with conditionally revealed content behave as expected. If you see unexpected behaviour, make sure the id for the revealed content is unique within the page the content is on. If you reuse the same id within a page, this duplication could cause a radio or checkbox to reveal the wrong element.

[EoinShaughnessy]

@36degrees Thanks for the talk-through! Had a go at slight rewording, let me know what you think!

Make sure your conditional reveals are behaving as expected

On radios and checkboxes, the JavaScript now looks within the whole page for conditionally revealed content. Before, it only looked within the same set of radios or checkboxes.

If you re-use the same id within a page, this change could cause a radio or checkbox to hide and reveal the wrong element.

Make sure any radios or checkboxes with conditionally revealed content behave as expected. If you see unexpected behaviour, make sure the revealed content's id is unique within the page the content is on.

Few questions:

• In the title, is 'behaving as expected' a bit vague?
• In the second paragraph, is 'hide and reveal' the right order? Isn't conditional reveals content hidden until users reveal it?
• The second paragraph feels a bit non-sequitury in its current place. Could we add it to the end of the last paragraph, where the info kind of follows on from the sentence about making sure IDs are unique?
• Do you think we could remove "Make sure any radios or checkboxes with conditionally revealed content behave as expected", as it just repeats the title and arguably adds little value?

[EoinShaughnessy]

Alternative wording, based on questions from previous comment:

Make sure your conditional reveals JavaScript looks for the right content

On radios and checkboxes, the JavaScript now looks within the whole page for conditionally revealed content. Before, it only looked within the same set of radios or checkboxes.

If you see unexpected behaviour, make sure the revealed content's id is unique within the page the content is on. Reusing the same id within a page could cause a radio or checkbox to reveal and hide the wrong element.

[36degrees]

@EoinShaughnessy that looks pretty good, but I really trip over the heading when reading it. I think because you naturally read 'condition reveals JavaScript' with 'reveals' being a verb, rather than 'conditional reveals Javascript' as a compound noun?

What about something like 'Make sure radios or checkboxes that conditionally reveal other questions still work as expected'?

[EoinShaughnessy]

@36degrees Good point! Yeah, your suggestion removes that ambiguity. Want me to add something like the below to the Changelog?

Make sure components that conditionally reveal other questions still work as expected

On radios and checkboxes, the JavaScript now looks within the whole page for conditionally revealed content. Before, it only looked within the same set of radios or checkboxes.

If you see unexpected behaviour, make sure the revealed content's id is unique within the page the content is on. Reusing the same id within a page could cause a radio or checkbox to reveal and hide the wrong element.