name: Document list
description: An ordered list of documents including a document type, when updated and a link.
body: |
  Outputs a list to documents, based on an array of document data. This may include:

  * document title
  * link to the document
  * last updated date object
  * document type

  Tracking can be added to the links by supplying optional data attributes for each.

  Documents are presented in an ordered list as the component expects that the ordering of the documents is relevant.
accessibility_criteria: |
  The component must:

  * inform the user how many items are in the list
shared_accessibility_criteria:
  - link
examples:
  default:
    data:
      items:
      - link:
          text: 'Alternative provision'
          path: '/government/publications/alternative-provision'
        metadata:
          public_updated_at: 2016-06-27 10:29:44
          document_type: 'Statutory guidance'
      - link:
          text: 'Behaviour and discipline in schools: guide for governing bodies'
          path: '/government/publications/behaviour-and-discipline-in-schools-guidance-for-governing-bodies'
        metadata:
          public_updated_at: 2015-09-24 16:42:48
          document_type: 'Statutory guidance'
      - link:
          text: 'Children missing education'
          path: '/government/publications/children-missing-education'
        metadata:
          public_updated_at: 2016-09-05 16:48:27
          document_type: 'Statutory guidance'
  without_links:
    data:
      items:
      - link:
          text: 'Alternative provision'
        metadata:
          public_updated_at: 2016-06-27 10:29:44
          document_type: 'Statutory guidance'
      - link:
          text: 'Behaviour and discipline in schools: guide for governing bodies'
        metadata:
          public_updated_at: 2015-09-24 16:42:48
          document_type: 'Statutory guidance'
      - link:
          text: 'Children missing education'
        metadata:
          public_updated_at: 2016-09-05 16:48:27
          document_type: 'Statutory guidance'
  with_data_attributes_on_links:
    data:
      items:
      - link:
          text: 'School behaviour and attendance: parental responsibility measures'
          path: '/government/publications/parental-responsibility-measures-for-behaviour-and-attendance'
          data_attributes:
            track_category: 'navDocumentCollectionLinkClicked'
            track_action: 1.1
            track_label: '/government/publications/parental-responsibility-measures-for-behaviour-and-attendance'
            track_options:
              dimension28: 2
              dimension29: 'School behaviour and attendance: parental responsibility measures'
        metadata:
          public_updated_at: 2017-01-05 14:50:33
          document_type: 'Statutory guidance'
      - link:
          text: 'School exclusion'
          path: '/government/publications/school-exclusion'
          data_attributes:
            track_category: 'navDocumentCollectionLinkClicked'
            track_action: 1.2
            track_label: '/government/publications/school-exclusion'
            track_options:
              dimension28: 2
              dimension29: 'School exclusion'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Statutory guidance'
  with_description:
    description: Documents can be passed to the component with a description. This is for use on topic pages, to display lists of mainstream services.
    data:
      items:
      - link:
          text: 'Become an apprentice'
          path: '/become-an-apprentice'
          description: 'Becoming an apprentice - what to expect, apprenticeship levels, pay and training, making an application, complaining about an apprenticeship.'
      - link:
          text: 'Become a journeyman'
          path: '/become-a-journeyman'
          description: 'Becoming a journeyman - what to expect, what to take, pay and training, making an application, complaining about being a journeyman.'
  with_description_and_metadata:
    data:
      items:
      - link:
          text: 'School behaviour and attendance: parental responsibility measures'
          path: '/government/publications/parental-responsibility-measures-for-behaviour-and-attendance'
          description: 'The responsibilities parents have relating to school behaviour and attendance.'
        metadata:
          public_updated_at: 2017-01-05 14:50:33
          document_type: 'Statutory guidance'
      - link:
          text: 'School exclusion'
          path: '/government/publications/school-exclusion'
          description: 'Rules governing school exclusion.'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Statutory guidance'
  with_branding:
    description: Where this component could be used on an organisation page (such as the [Attorney General's Office](https://www.gov.uk/government/organisations/attorney-generals-office)) branding can be applied for link colours and border colours. See the [branding documentation](https://github.com/alphagov/govuk_publishing_components/blob/master/docs/component_branding.md) for more details.
    data:
      brand: 'attorney-generals-office'
      items:
      - link:
          text: 'School behaviour and attendance: parental responsibility measures'
          path: '/government/publications/parental-responsibility-measures-for-behaviour-and-attendance'
        metadata:
          public_updated_at: 2017-01-05 14:50:33
          document_type: 'Statutory guidance'
      - link:
          text: 'School exclusion'
          path: '/government/publications/school-exclusion'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Statutory guidance'
  with_only_link:
    data:
      items:
      - link:
          text: 'School behaviour and attendance: parental responsibility measures'
          path: '/government/publications/parental-responsibility-measures-for-behaviour-and-attendance'
      - link:
          text: 'School exclusion'
          path: '/government/publications/school-exclusion'
  with_context:
    description: Context can be provided to render next to the item title.
    data:
      items:
      - link:
          text: 'Forestry Commission'
          path: '/government/organisations/forestry-commission'
          context: 'separate website'
      - link:
          text: 'Advisory Committee on the Microbiological Safety of Food'
          path: '/government/organisations/advisory-committee-on-the-microbiological-safety-of-food'
          context: 'moving to GOV.UK'
          description: "Works with 4 agencies and public bodies"
  with_subtext:
    description: This is used on finders to highlight search results from past governments.
    data:
      items:
      - link:
          text: 'Department for Education – Statistics at DfE'
          path: '/government/organisations/department-for-education/about/statistics'
          description: 'The Department for Education publishes official statistics on education and children.'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Corporate information'
        subtext: 'First published during the 2007 Labour Government'
      - link:
          text: 'State-funded school inspections and outcomes: management information'
          path: '/government/organisations/department-for-education/about/statistics'
          description: 'Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015.'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Statistical data set'
        subtext: 'First published during the 1996 Conservative Government'
  without_underline:
    description: The current search design does not include underlines on links and has been tested without underlines. Other uses will require further user testing.
    data:
      remove_underline: true
      items:
      - link:
          text: 'Department for Education – Statistics at DfE'
          path: '/government/organisations/department-for-education/about/statistics'
          description: 'The Department for Education publishes official statistics on education and children.'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Corporate information'
        subtext: 'First published during the 2007 Labour Government'
      - link:
          text: 'State-funded school inspections and outcomes: management information'
          path: '/government/organisations/department-for-education/about/statistics'
          description: 'Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015.'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Statistical data set'
        subtext: 'First published during the 1996 Conservative Government'
  highlighted_result:
    description: Highlight one or more of the items in the list. This is used on finders to provide a 'top result' for a search. The `highlight_text` parameter is optional.
    data:
      items:
      - link:
          text: 'Department for Education – Statistics at DfE'
          path: '/government/organisations/department-for-education/about/statistics'
          description: 'The Department for Education publishes official statistics on education and children.'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Corporate information'
        subtext: 'First published during the 2007 Labour Government'
        highlight: true
        highlight_text: 'Most relevant result'
      - link:
          text: 'State-funded school inspections and outcomes: management information'
          path: '/government/organisations/department-for-education/about/statistics'
          description: 'Management information published monthly and a one-off publication of inspections and outcomes from 2005 to 2015.'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Statistical data set'
        subtext: 'First published during the 1996 Conservative Government'
  right_to_left:
    data:
      items:
      - link:
          text: 'School behaviour and attendance: parental responsibility measures'
          path: '/government/publications/parental-responsibility-measures-for-behaviour-and-attendance'
          description: "Statutory guidance for schools, local authorities and the police on dealing with poor attendance and behaviour in school"
        metadata:
          public_updated_at: 2017-01-05 14:50:33
          document_type: 'Statutory guidance'
      - link:
          text: 'Forestry Commission'
          path: '/government/organisations/forestry-commission'
          context: 'separate website'
        metadata:
          public_updated_at: 2017-07-19 15:01:48
          document_type: 'Organisation'
    context:
      right_to_left: true