From 38236e8438d07a583a4aedbba904655ae82460ea Mon Sep 17 00:00:00 2001 From: jrbarnes9 Date: Fri, 11 Feb 2022 16:24:22 +0000 Subject: [PATCH 01/33] added document component first draft --- src/components/document/_macro-options.md | 26 ++++++ src/components/document/_macro.njk | 87 +++++++++++++++++++ src/components/document/document.scss | 48 ++++++++++ .../examples/document-multiple/index.njk | 65 ++++++++++++++ .../document-single-noimage/index.njk | 16 ++++ .../examples/document-single/index.njk | 20 +++++ src/components/document/index.njk | 55 ++++++++++++ src/components/downloads/_downloads.scss | 2 +- src/scss/main.scss | 1 + src/scss/vars/_colors.scss | 5 +- 10 files changed, 322 insertions(+), 3 deletions(-) create mode 100644 src/components/document/_macro-options.md create mode 100644 src/components/document/_macro.njk create mode 100644 src/components/document/document.scss create mode 100644 src/components/document/examples/document-multiple/index.njk create mode 100644 src/components/document/examples/document-single-noimage/index.njk create mode 100644 src/components/document/examples/document-single/index.njk create mode 100644 src/components/document/index.njk diff --git a/src/components/document/_macro-options.md b/src/components/document/_macro-options.md new file mode 100644 index 0000000000..6c7d3cdee5 --- /dev/null +++ b/src/components/document/_macro-options.md @@ -0,0 +1,26 @@ +| Name | Type | Required | Description | +| -------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------- | +| title | string | true | The title for the document | +| titleTag | string | false | The HTML heading tag to wrap the title text in for it’s correct semantic order on the page. Will default to an `h2` | +| description | string | true | A short extract of text (for example, a short sentence to give some context of the document) | +| url | string | true | The url for the document document (for example, a pdf file, zip file) | +| type | string | true | Type of file (for example, Poster, Booklet, Flyer) | +| classes | string | false | Custom classes to add to the documents | +| thumbnail | `Thumbnail` | true | An object containing path and filename attributes for the image | +| metadata | `Metadata` | true | An object containing information about file type, size and number of pages | +| placeholderURL | string | false | Optional base path for placeholder image | + +## Thumbnail + +| Name | Type | Required | Description | +| -------- | ------ | -------- | ------------------------------------------- | +| smallSrc | string | true | Path to the non-retina version of the image | +| largeSrc | string | true | Path to the retina version of the image | + +## Metadata + +| Name | Type | Required | Description | +| --------- | ------ | -------- | ---------------------------------------- | +| fileType | string | true | File type (for example, PDF, DOC, XLS) | +| fileSize | string | true | Size of file (for example, 850kb, 1.5mb) | +| filePages | string | false | Quantity of pages | diff --git a/src/components/document/_macro.njk b/src/components/document/_macro.njk new file mode 100644 index 0000000000..47e5e196ab --- /dev/null +++ b/src/components/document/_macro.njk @@ -0,0 +1,87 @@ +{% macro onsDocument(params) %} + + +{% endmacro %} diff --git a/src/components/document/document.scss b/src/components/document/document.scss new file mode 100644 index 0000000000..2f6a225510 --- /dev/null +++ b/src/components/document/document.scss @@ -0,0 +1,48 @@ +.ons-document-list { + @extend .ons-list--bare; + + &__item { + display: flex; + margin: 0; + + & + & { + border-top: 1px solid $color-borders-list; + margin: 1.5rem 0 0; + padding: 1.5em 0 0; + } + } + + &__item-image { + flex: 0 0 auto; + margin-right: 1.5rem; + width: 96px; + } + + &__image-link { + border: 2px solid $color-borders-document-image; + box-sizing: content-box; + display: block; + width: 100%; + + &:focus { + border-color: $color-borders-document-image-focus; + box-shadow: none; + outline: 4px solid $color-focus !important; + outline-offset: 0; + } + } + + &__item-metadata { + @extend .ons-list--bare; + } + + &__item-attribute { + color: $color-grey-100; + display: block; + } + + &__item-description { + margin-bottom: 0; + max-width: 660px; // Equivalent to 8 Columns + } +} diff --git a/src/components/document/examples/document-multiple/index.njk b/src/components/document/examples/document-multiple/index.njk new file mode 100644 index 0000000000..bcc9164593 --- /dev/null +++ b/src/components/document/examples/document-multiple/index.njk @@ -0,0 +1,65 @@ +{% from "components/document/_macro.njk" import onsDocument %} +{{ onsDocument({ + "documents": [ + { + "thumbnail": { + "smallSrc": '/patternlib-img/download-resources/img/small/census-2021-matters-to-everyone.png', + "largeSrc": '/patternlib-img/download-resources/img/large/census-2021-matters-to-everyone.png' + }, + "url": '/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf', + "title": 'Census 2021 matters to everyone', + "type": 'Poster', + "metadata": { + "fileType": 'PDF', + "fileSize": '866KB', + "filePages": '1 page' + }, + "description": 'By taking part and encouraging others to do the same, you’ll make sure your community gets the services it needs.' + }, + { + "thumbnail": { + "smallSrc": '/patternlib-img/download-resources/img/small/including-everyone-in-census-2021-v2.png', + "largeSrc": '/patternlib-img/download-resources/img/large/including-everyone-in-census-2021-v2.png' + }, + "url": '/patternlib-img/download-resources/documents/Print-Ready-A4EB1-2021-v1-0-120620.pdf', + "title": 'Including everyone in Census 2021', + "type": 'Poster', + "metadata": { + "fileType": 'PDF', + "fileSize": '499KB', + "filePages": '1 page' + }, + "description": 'Empty belly poster, aimed at advertising census events.' + }, + { + "thumbnail": { + "smallSrc": '/patternlib-img/download-resources/img/small/including-everyone-in-census-2021.png', + "largeSrc": '/patternlib-img/download-resources/img/large/including-everyone-in-census-2021.png' + }, + "url": '/patternlib-img/download-resources/documents/A6PCA1-v1-0-Print-Ready-Pack1.pdf', + "title": 'Including everyone in Census 2021', + "type": 'Poster', + "metadata": { + "fileType": 'PDF', + "fileSize": '499KB', + "filePages": '1 page' + }, + "description": 'Generic poster advertising census 2021.' + }, + { + "thumbnail": { + "smallSrc": '/patternlib-img/download-resources/img/small/census-2021-community-handbook.png', + "largeSrc": '/patternlib-img/download-resources/img/large/census-2021-community-handbook.png' + }, + "url": '/patternlib-img/download-resources/documents/CHDE1-Community-Handbook-v0.6.pdf', + "title": 'Community handbook for Census 2021', + "type": 'Booklet', + "metadata": { + "fileType": 'PDF', + "fileSize": '3.3MB', + "filePages": '16 pages' + }, + "description": 'This handbook explains what the census is, why it matters to everyone and how we can work together to spread the word within your community.' + } + ] +}) }} diff --git a/src/components/document/examples/document-single-noimage/index.njk b/src/components/document/examples/document-single-noimage/index.njk new file mode 100644 index 0000000000..b1bd556e7c --- /dev/null +++ b/src/components/document/examples/document-single-noimage/index.njk @@ -0,0 +1,16 @@ +{% from "components/document/_macro.njk" import onsDocument %} +{{ onsDocument({ + "documents": [ + { + "url": '/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf', + "title": 'Census 2021 matters to everyone', + "type": 'Poster', + "metadata": { + "fileType": 'PDF', + "fileSize": '866KB', + "filePages": '1 page' + }, + "description": 'By taking part and encouraging others to do the same, you’ll make sure your community gets the services it needs.' + } + ] +}) }} diff --git a/src/components/document/examples/document-single/index.njk b/src/components/document/examples/document-single/index.njk new file mode 100644 index 0000000000..56a40c75e6 --- /dev/null +++ b/src/components/document/examples/document-single/index.njk @@ -0,0 +1,20 @@ +{% from "components/document/_macro.njk" import onsDocument %} +{{ onsDocument({ + "documents": [ + { + "thumbnail": { + "smallSrc": '/patternlib-img/download-resources/img/small/census-2021-matters-to-everyone.png', + "largeSrc": '/patternlib-img/download-resources/img/large/census-2021-matters-to-everyone.png' + }, + "url": '/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf', + "title": 'Census 2021 matters to everyone', + "type": 'Poster', + "metadata": { + "fileType": 'PDF', + "fileSize": '866KB', + "filePages": '1 page' + }, + "description": 'By taking part and encouraging others to do the same, you’ll make sure your community gets the services it needs.' + } + ] +}) }} diff --git a/src/components/document/index.njk b/src/components/document/index.njk new file mode 100644 index 0000000000..121d741f79 --- /dev/null +++ b/src/components/document/index.njk @@ -0,0 +1,55 @@ +--- +title: Document +synonyms: downloads, files, search result, article, publication, +--- + ++++ +{% from "views/partials/example/_macro.njk" import patternlibExample %} +{% from "components/external-link/_macro.njk" import onsExternalLink %} +{% from "components/panel/_macro.njk" import onsPanel %} ++++ + +Displays a link to document an attachment and metadata about the file. + +{{ + onsPanel({ + "body": "This component requires documentation." + }) +}} + +## Single document +{{ + patternlibExample({"path": "components/document/examples/document-single/index.njk"}) +}} + +## Single document (no image) +In situations an image is not used, we require a fallback image to prevent a broken link. +{{ + patternlibExample({"path": "components/document/examples/document-single-noimage/index.njk"}) +}} + +## Multiple documents +{{ + patternlibExample({"path": "components/document/examples/document-multiple/index.njk"}) +}} + +## How to use this component +We use two versions of the image, one for standard screens and the other for retina screens. + +Image dimension for: + +* standard screen is: `96px × 136px` +* retina screen is: `192px × 272px` + +We specify a folder path for both small and large images, which is defined in the macro as `smallSrc` and `largeSrc`. The filename is expected to be the same for both. + +The image used is considered decorative and does not convey important information, and as such should be hidden from screen readers. The image does not require an `alt` tag. + +## Help improve this component +Let us know how we could improve this component or share your user research findings. +{{ + onsExternalLink({ + "url": "https://github.com/ONSdigital/design-system/discussions/716", + "linkText": "Discuss the ‘Document’ component on GitHub" + }) +}} diff --git a/src/components/downloads/_downloads.scss b/src/components/downloads/_downloads.scss index b55829e288..ba2cb2a956 100644 --- a/src/components/downloads/_downloads.scss +++ b/src/components/downloads/_downloads.scss @@ -20,7 +20,7 @@ width: 100%; &:focus { - border-color: $color-document-border-focus; + border-color: $color-borders-document-image-focus; box-shadow: none; outline: 4px solid $color-focus !important; outline-offset: 0; diff --git a/src/scss/main.scss b/src/scss/main.scss index 355d9d6f55..505d4327c4 100644 --- a/src/scss/main.scss +++ b/src/scss/main.scss @@ -16,6 +16,7 @@ @import '../components/collapsible/collapsible'; @import '../components/content-pagination/content-pagination'; @import '../components/cookies-banner/cookies-banner'; +@import '../components/document/document'; @import '../components/download-resources/download-resources'; @import '../components/downloads/downloads'; @import '../components/external-link/external-link'; diff --git a/src/scss/vars/_colors.scss b/src/scss/vars/_colors.scss index 61dddaf13e..213d26e920 100644 --- a/src/scss/vars/_colors.scss +++ b/src/scss/vars/_colors.scss @@ -76,8 +76,9 @@ $color-highlight: $color-neon-yellow !default; // Borders $color-borders: $color-grey-75 !default; $color-borders-indent: $color-grey-35 !default; -$color-document-border: $color-grey-15 !default; -$color-document-border-focus: $color-black !default; +$color-borders-list: $color-grey-35 !default; +$color-borders-document-image: $color-grey-15 !default; +$color-borders-document-image-focus: $color-black !default; // Form elements $color-button: $color-leaf-green !default; From dc11da2944a8b3ed3a07d07ac8c1b165ac463887 Mon Sep 17 00:00:00 2001 From: jrbarnes9 Date: Fri, 11 Feb 2022 16:59:38 +0000 Subject: [PATCH 02/33] refector --- src/components/document/_macro.njk | 64 ++++++++++--------- src/components/document/document.scss | 2 +- .../examples/document-multiple/index.njk | 40 +++++++----- .../document-single-noimage/index.njk | 10 +-- .../examples/document-single/index.njk | 10 +-- 5 files changed, 71 insertions(+), 55 deletions(-) diff --git a/src/components/document/_macro.njk b/src/components/document/_macro.njk index 47e5e196ab..346b87bb92 100644 --- a/src/components/document/_macro.njk +++ b/src/components/document/_macro.njk @@ -19,13 +19,13 @@ <{{ titleTag }} class="ons-u-fs-m ons-u-mt-no ons-u-mb-xs"> {{ document.title }}, - {%- if document.metadata is defined and document.metadata %} + {%- if document.metadata.file is defined and document.metadata.file %} {% set fileMetadataItems = [] %} - {% if document.file.fileType is defined and document.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.file.fileType + ' document download'), fileMetadataItems) %}{% endif %} - {% if document.file.fileSize is defined and document.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.file.fileSize), fileMetadataItems) %}{% endif %} - {% if document.file.filePages is defined and document.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.file.filePages), fileMetadataItems) %}{% endif %} + {% if document.metadata.file.fileType is defined and document.metadata.file.fileType %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileType + ' document download'), fileMetadataItems) %}{% endif %} + {% if document.metadata.file.fileSize is defined and document.metadata.file.fileSize %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.fileSize), fileMetadataItems) %}{% endif %} + {% if document.metadata.file.filePages is defined and document.metadata.file.filePages %}{% set fileMetadataItems = (fileMetadataItems.push(document.metadata.file.filePages), fileMetadataItems) %}{% endif %} {{ fileMetadataItems | join(', ') }} @@ -34,45 +34,49 @@ - + + {% endif %} {% if document.description is defined and document.description %}

{{ document.description | safe }}

diff --git a/src/components/document/document.scss b/src/components/document/document.scss index 2f6a225510..5a5760d57b 100644 --- a/src/components/document/document.scss +++ b/src/components/document/document.scss @@ -38,7 +38,7 @@ &__item-attribute { color: $color-grey-100; - display: block; + display: inline-block; } &__item-description { diff --git a/src/components/document/examples/document-multiple/index.njk b/src/components/document/examples/document-multiple/index.njk index bcc9164593..4bddb91d8f 100644 --- a/src/components/document/examples/document-multiple/index.njk +++ b/src/components/document/examples/document-multiple/index.njk @@ -8,11 +8,13 @@ }, "url": '/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf', "title": 'Census 2021 matters to everyone', - "type": 'Poster', "metadata": { - "fileType": 'PDF', - "fileSize": '866KB', - "filePages": '1 page' + "file": { + "type": 'Poster', + "fileType": 'PDF', + "fileSize": '866KB', + "filePages": '1 page' + } }, "description": 'By taking part and encouraging others to do the same, you’ll make sure your community gets the services it needs.' }, @@ -23,11 +25,13 @@ }, "url": '/patternlib-img/download-resources/documents/Print-Ready-A4EB1-2021-v1-0-120620.pdf', "title": 'Including everyone in Census 2021', - "type": 'Poster', "metadata": { - "fileType": 'PDF', - "fileSize": '499KB', - "filePages": '1 page' + "file": { + "type": 'Poster', + "fileType": 'PDF', + "fileSize": '499KB', + "filePages": '1 page' + } }, "description": 'Empty belly poster, aimed at advertising census events.' }, @@ -38,11 +42,13 @@ }, "url": '/patternlib-img/download-resources/documents/A6PCA1-v1-0-Print-Ready-Pack1.pdf', "title": 'Including everyone in Census 2021', - "type": 'Poster', "metadata": { - "fileType": 'PDF', - "fileSize": '499KB', - "filePages": '1 page' + "file": { + "type": 'Poster', + "fileType": 'PDF', + "fileSize": '499KB', + "filePages": '1 page' + } }, "description": 'Generic poster advertising census 2021.' }, @@ -53,11 +59,13 @@ }, "url": '/patternlib-img/download-resources/documents/CHDE1-Community-Handbook-v0.6.pdf', "title": 'Community handbook for Census 2021', - "type": 'Booklet', "metadata": { - "fileType": 'PDF', - "fileSize": '3.3MB', - "filePages": '16 pages' + "file": { + "type": 'Booklet', + "fileType": 'PDF', + "fileSize": '3.3MB', + "filePages": '16 pages' + } }, "description": 'This handbook explains what the census is, why it matters to everyone and how we can work together to spread the word within your community.' } diff --git a/src/components/document/examples/document-single-noimage/index.njk b/src/components/document/examples/document-single-noimage/index.njk index b1bd556e7c..871869aebf 100644 --- a/src/components/document/examples/document-single-noimage/index.njk +++ b/src/components/document/examples/document-single-noimage/index.njk @@ -4,11 +4,13 @@ { "url": '/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf', "title": 'Census 2021 matters to everyone', - "type": 'Poster', "metadata": { - "fileType": 'PDF', - "fileSize": '866KB', - "filePages": '1 page' + "file": { + "type": 'Booklet', + "fileType": 'PDF', + "fileSize": '3.3MB', + "filePages": '16 pages' + } }, "description": 'By taking part and encouraging others to do the same, you’ll make sure your community gets the services it needs.' } diff --git a/src/components/document/examples/document-single/index.njk b/src/components/document/examples/document-single/index.njk index 56a40c75e6..619430cbd9 100644 --- a/src/components/document/examples/document-single/index.njk +++ b/src/components/document/examples/document-single/index.njk @@ -8,11 +8,13 @@ }, "url": '/patternlib-img/download-resources/documents/Print-Ready-A4GIP1-2021-v1-0-120620.pdf', "title": 'Census 2021 matters to everyone', - "type": 'Poster', "metadata": { - "fileType": 'PDF', - "fileSize": '866KB', - "filePages": '1 page' + "file": { + "type": 'Booklet', + "fileType": 'PDF', + "fileSize": '3.3MB', + "filePages": '16 pages' + } }, "description": 'By taking part and encouraging others to do the same, you’ll make sure your community gets the services it needs.' } From 604ec13fdce07a636975c1b0a4f45272c76a7501 Mon Sep 17 00:00:00 2001 From: jrbarnes9 Date: Fri, 11 Feb 2022 17:53:47 +0000 Subject: [PATCH 03/33] added date --- src/components/document/_macro.njk | 20 +++++++++++++++++-- .../document-single-noimage/index.njk | 6 ++++++ 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/src/components/document/_macro.njk b/src/components/document/_macro.njk index 346b87bb92..1be04010ee 100644 --- a/src/components/document/_macro.njk +++ b/src/components/document/_macro.njk @@ -37,6 +37,22 @@ {%- if document.metadata is defined and document.metadata %}