Media document file link formatting

[Adnan-cds]

Media documents currently use the Generic file field formatter which uses a file icon (e.g. a PDF icon) to denote the file type. These links are also rendered as block items within an article tag (e.g. <article...><span...><a...>...</a></span></article>). Instead of this, file links shown as part of Media documents should:

• Include the file type and file size in clear text.
• No icons.
• Appear as inline elements (e.g. <span...>...</span>).

Example: 2020 annual report (PDF, 42KB)

Some more explanation and examples from the Croydon Design and content guidelines.

We have already implemented this in localgov_theme_croydon. The task here is to copy and rename the necessary bits including:

• localgov_theme_croydon_preprocess_file_link
• file-link.html.twig
• media--document.html.twig

Summary: File icons shown before Media document file links will be replaced with filetype and filesize in text shown after the link.

FAO @willguv @andybroomfield @finnlewis @cjstevens78 @clearspotmedia @danchamp

[danchamp]

Thanks @Adnan-cds, looks good.

For accessibility the file type and size should be included in the anchor text, otherwise screenreaders and other assistive techs will not announce the information to many users who navigate by link or access a list of links on a page.

[Adnan-cds]

Hi Dan, I am not sure about including file metadata as part of the file link. Neither the Croydon design system nor examples in gov.uk include metadata in the anchor text. Is there any other way we can highlight the presence of this metadata to assistive technologies? Could the aria-describedby property be of any use here?

[danchamp]

There are also authorities recommending the inclusion of this information in visible link text: NHS, NZ Gov, Queensland Gov, WebAIM, Deque.

Our own project accessibility standards say the same: Localgov Drupal Link purpose guidelines.

If we're not going to include it in the visible link text by default, then aria-label is probably the best non-visible alternative, with a value of the document title + file type and size. (There are reported issues using aria-describedby, with most screenreaders not using the description in lists of links.)

My preference is still to include it in the visible link text: who does it disadvantage by including it in the visible link text? If it's information that is useful to all users (I'd argue strongly that it is), we take an inclusive approach by including it in the link text rather than relying on assistive technologies to access a redundant ARIA label.

[Adnan-cds]

Thanks Dan. The evidence looks definitive. I will see what can be done about it.

[Adnan-cds]

Hello Dan,
People here at Croydon have agreed to your suggestion. The subsequent code change was trivial. But I am keen to preserve the semantic markup of the file meta data. I was thinking of using markup like the following where the file metadata markup becomes part of the link:

<a href="https://example.net/files/..." ...>
    Link text goes here
    <small class="file-meta...">
        <span class="file-type">File extension goes here</span>
        <span class="file-size">File size goes here</span>
    </small>
</a>

Do you see any issue with this?

[danchamp]

I think that's ideal Adnan, thanks. It gives the flexibility of presenting the metadata (and each element of the metadata) differently if required.