DFE-Digital/govuk-components

View on GitHub
guide/content/helpers/link.slim

Summary

Maintainability
Test Coverage
---
title: Link helpers
---

markdown:
  In addition to the components, this gem also comes with link helpers that are
  often reimplemented across projects.

== render('/partials/example.*',
  caption: "Regular link",
  code: govuk_link_to_normal) do

  markdown:
    Regular links are just plain [anchor elements][0]
    with the `govuk-link` class.

    [0]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a

== render('/partials/example.*',
  caption: "Inverse hyperlink",
  code: govuk_link_to_inverse,
  inverse: true) do

  p.govuk-body
    | Use inverse hyperlinks on dark backgrounds.

== render('/partials/example.*',
  caption: "Other link styles",
  code: govuk_link_other_styles)

== render('/partials/example.*',
  caption: "Links with visually hidden text",
  code: govuk_link_with_visually_hidden_text) do

  markdown:
    When space is limited we sometimes rely on the link's position to provide
    context about its target. An example of this is in admin interfaces where rows
    in a table often have a 'View' link, or a 'Delete' button.

    Omitting the extra text entirely leaves users of assistive technologies like
    screen readers at a disadvantage, as they can't infer that context. We can
    solve this problem using visually hidden text that isn't visible on the screen
    but will be read out by screen readers.

    The keyword arguments automatically add a space between the visually
    hidden and regular text.

== render('/partials/example.*',
  caption: "Links that open in a new tab",
  code: govuk_link_to_new_tab) do

  markdown:
    You can use the `new_tab` parameter to automatically set the `target` and
    `rel` [attributes as suggested by the design system][0].

    When the link text is passed in as a string argument, 'opens in new tab' is
    added to the end automatically. No suffix is added when the helper is used
    in block mode.

    The default text can be set using the `default_link_new_tab_text` configuration option
    and it can be suppressed by setting it to an empty string.

    If you don't want any extra text to be rendered you suppress the behaviour
    with `new_tab: ""`.

    [0]: https://design-system.service.gov.uk/styles/links/#opening-links-in-a-new-tab

hr.govuk-section-break.govuk-section-break--xl.govuk-section-break--visible

== render('/partials/example.*',
  caption: "Class helpers",
  code: govuk_link_classes_multiple) do

  p.govuk-body
    markdown:
      Rails has [lots of link helpers][0]
      and only the most frequently used are wrapped by this library. If you need
      to use another variant, like `link_to_if`, you can use the
      `govuk_link_classes` and `govuk_button_classes`
      helpers to ensure the correct classes are assigned.

      When no arguments are provided to `govuk_link_classes`, only
      the default `govuk-link` will be added. Alternate styles
      can be passed in as a snake cased array of variants.

      [0]: #{rails_docs_url_helper}