feat: file download documentation (#539)

* add markdown

* Add example + properties

* add line breaks

* temp fix id error

* update download link to njk component, update params

* update default download link text

* update properties + example

* add njk example props + markup

* remove br

Co-authored-by: Houston <[email protected]>
Co-authored-by: Dayle Salmon <[email protected]>

src/wmnds/components/file-download/_example.njk

@@ -0,0 +1,13 @@
+{% raw %}
+{% from "wmnds/components/file-download/_file-download.njk" import wmndsFileDownload %}
+
+{{
+    wmndsFileDownload({
+        fileName: "example file",
+        fileType: "pdf",
+        fileSize: "1MB",
+        downloadLinkText: "Download file",
+        accessible: true
+    })
+}}
+{% endraw %}

src/wmnds/components/file-download/_file-download.njk

@@ -1,11 +1,14 @@
 {% macro wmndsFileDownload(params) %}
 {# Imports #}
 {% from "wmnds/components/icon/_icon.njk" import wmndsIcon %}
+{% from "wmnds/components/link/link/_link.njk" import wmndsLink %}
 {# Set #}
 {% set fileName = params.fileName or 'file name' %}
 {% set fileType = params.fileType or 'filetype' %}
-{% set fileSize = params.fileSize or 'filesize' %}
+{% set fileSize =  ", " + params.fileSize if params.fileSize else '' %}
 {% set accessibleClass = " wmnds-file-download--non-accessible" if params.accessible === false else "" %}
+{% set downloadLinkText = params.downloadLinkText if params.downloadLinkText else "Download '" + fileName + "' (" + fileType + fileSize + ")" %}
+
 
 <div class="wmnds-file-download{{accessibleClass}}">
     {{
@@ -15,9 +18,13 @@
         }) | trim | indent(4)
     }}
     <div class="wmnds-file-download__desc">
-        <a href="#" download="{{ fileName|replace(' ', '_') + '.' + fileType|lower }}" class="wmnds-link">
-            Download '{{fileName}}' ({{fileType}}, {{fileSize}})
-        </a>
+        {{    
+            wmndsLink({
+                contentText: downloadLinkText,
+                download: fileName|replace(' ', '_') + '.' + fileType|lower,
+                link: "#"
+            })
+        }}
         {% if params.accessible === false -%}
         <p class="wmnds-file-download__warning">
             This file may not be suitable for users of assistive technology. <br>

src/wmnds/components/file-download/_properties.njk.json

@@ -0,0 +1,29 @@
+{
+  "wmndsFileDownloadProps": [
+    {
+      "name": "fileName",
+      "type": "string",
+      "description": "<strong>Required.</strong> The file name of the download."
+    },
+    {
+      "name": "fileType",
+      "type": "string",
+      "description": "<strong>Required.</strong> The file type of the download e.g. doc, pdf."
+    },
+    {
+      "name": "fileSize",
+      "type": "string",
+      "description": "The size of the file"
+    },
+    {
+      "name": "downloadLinkText",
+      "type": "string",
+      "description": "Custom text to be displayed in the download link."
+    },
+    {
+      "name": "accessible",
+      "type": "boolean",
+      "description": "Determines whether to display the file as an accessible or non-accessible file component. Defaults to <code class='wmnds-website-inline-code'>true</code>."
+    }
+  ]
+}

src/wmnds/components/link/link/_link.njk

@@ -12,12 +12,14 @@
 {% set withChevronRight = params.withChevronRight if params.withChevronRight else false %}
 {% set _linkRel = "noopener noreferrer" if linkTarget === "_blank" %} {# if target is blank then add rel noopener noreferrer to link #}
 {% set _content = contentHTML | safe if contentHTML else contentText %} {# change content based on what user has input #}
+{% set _download = params.download if params.download %}  {# set download attr if param is specified #}
+
 
 {# Class modifiers #}
 {% set class = ' ' + params.classes if params.classes %}
 {% set class = class + " wmnds-link--with-chevron" if withChevronLeft or withChevronRight else class %}
 
-<a href="{{ link }}" title="{{ linkTitle }}" target="{{ linkTarget }}" class="wmnds-link{{class}}" {% if _linkRel %}rel="{{linkRel}}"{% endif %}>
+<a href="{{ link }}" title="{{ linkTitle }}" target="{{ linkTarget }}" class="wmnds-link{{class}}" {% if _linkRel %}rel="{{_linkRel}}"{% endif %} {% if _download %}download="{{_download}}"{% endif %}>
   {% if withChevronLeft -%}
     {{ wmndsIcon({ icon: "general-chevron-right", class: "wmnds-link__chevron wmnds-link__chevron--left" })}}
   {%- endif %}

src/www/pages/components/file-download/index.njk.md

@@ -0,0 +1,101 @@
+{% extends "www/_layouts/layout-left-pane.njk" %}
+{% set pageTitle = "File download" %}
+{% from "www/_partials/component-example/component-example.njk" import compExample %}
+{# Macros #}
+{% from "wmnds/components/file-download/_file-download.njk" import wmndsFileDownload %}
+
+{% block content %}
+
+{% markdown %}
+{# About #}
+
+## About
+
+{# What #}
+
+### What does it do?
+
+- Allows users to download an offline version of the on-page content.
+- Allows users who rely on assistive technology to access an offline version of the on-page content.
+- Shows users how big the file is so they can decide if they want to download it.
+
+---
+
+{# Accessible file #}
+
+## Accessible file
+
+{# When to #}
+
+### When to use it?
+
+- When you have an accessible, offline version of the on-page content.
+- When you have additional information within an accessible document.
+
+{# When not to #}
+
+### When not to use it?
+
+- If the download document is not accessible to users with assistive technology. In that instance, use the non-accessible file component.
+
+{% endmarkdown %}
+
+{{
+    compExample([
+        wmndsFileDownload({
+            fileName: "example file",
+            fileType: "pdf",
+            fileSize: "3MB"
+        })
+    ], {
+        componentPath: "wmnds/components/file-download/",
+        njk: true,
+        njkProps: wmndsFileDownloadProps,
+        js: false,
+        iframe: false
+    })
+}}
+
+{% markdown %}
+{# Non-accessible file #}
+
+## Non-accessible file
+
+{# What #}
+
+### What does it do? <a name="non-accessible-what-does-it-do"></a>
+
+- Shows the user that the file is not accessible
+- Offers the user a way to get the file in a different format
+
+{# When to #}
+
+### When to use it? <a name="non-accessible-when-to-use-it"></a>
+
+- When you have an offline version of the on-page content which is not accessible
+- When the file cannot be made accessible. For example, complex maps.
+
+{# When not to #}
+
+### When not to use it? <a name="non-accessible-when-not-to-use-it"></a>
+
+- If the document is accessible to users with assistive technology. In that instance, use the accessible file component.
+- You still need to make the document accessible as soon as possible. Ideally before publishing it.
+
+{% endmarkdown %}
+
+{{
+    compExample([
+        wmndsFileDownload({
+            accessible: false
+        })
+    ], {
+        componentPath: "wmnds/components/file-download/",
+        njk: true,
+        njkProps: wmndsFileDownloadProps,
+        js: false,
+        iframe: false
+    })
+}}
+
+{% endblock %}