feat: content card documentation (#553)

* add markdown

* add example + properties

* update param name

* update content card params

* removed br tags

* improve indentation

* fix content card param

src/wmnds/components/content-card/_content-card.njk

@@ -1,12 +1,13 @@
 {% macro wmndsContentCard(params) %}
 {# Set #}
-{% set variantModifier = " " + params.variant if params.variant else "" %}
+{% set classes = " " + params.classes if params.classes else "" %}
 {% set yellowModifier = " wmnds-content-card--yellow" if params.yellow else "" %}
 {# Opening & closing tags #}
-{% set tag = "a" if params.clickable else "div" %}
-{% set attributes = " href=\"#\" target=\"_self\"" if params.clickable else "" %}
+{% set tag = "a" if params.href else "div" %}
+{% set href = params.href if params.href else "#" %}
+{% set _attributes = " href=\"" + href + "\" target=\"_self\"" if params.href else "" %}
 {# HTML content #}
-{% set html = params.html if params.html else "
+{% set contentHTML = params.contentHTML if params.contentHTML else "
     <div class=\"wmnds-p-sm\">
         <h2>Where the adventure starts</h2>
         <p>Whatever your plans this holiday, get there with our great range of family tickets and discount vouchers.</p>
@@ -15,11 +16,11 @@
 
 {# This macro checks if it's being called inside a {% call %} tag #}
 {# It's an easier way to pass in larger html content  #}
-<{{tag}}{{attributes | safe}} class="wmnds-content-card{{variantModifier + yellowModifier}}">
+<{{tag}}{{_attributes | safe}} {% if params.id %}id="{{ params.id }}"{% endif %} class="wmnds-content-card{{classes + yellowModifier}}">
 {%- if caller -%}
     {{ caller() }}
     {%- else -%}
-    {{ html | safe }}
+    {{ contentHTML | safe }}
 {%- endif -%}
 </{{tag}}>
 {% endmacro %}

src/wmnds/components/content-card/_example.njk

@@ -0,0 +1,12 @@
+{% raw %}
+{% from "wmnds/components/content-card/_content-card.njk" import wmndsContentCard %}
+
+{{
+   wmndsContentCard({
+      id: null,
+      href: "https://designsystem.wmnetwork.co.uk/components/content-card/",
+      yellow: false,
+      classes: null
+   })
+}}
+{% endraw %}

src/wmnds/components/content-card/_properties.njk.json

@@ -0,0 +1,24 @@
+{
+  "wmndsContentCardProps": [
+    {
+      "name": "id",
+      "type": "string",
+      "description": "The id of the content card"
+    },
+    {
+      "name": "href",
+      "type": "string",
+      "description": "Specifies the link to display the content card component as a clickable navigation card."
+    },
+    {
+      "name": "classes",
+      "type": "string",
+      "description": "Classes to add to the content card component."
+    },
+    {
+      "name": "yellow",
+      "type": "boolean",
+      "description": "Displays the content card with a highlighted (yellow) background. Default value is <code class='wmnds-website-inline-code'>false</code>"
+    }
+  ]
+}

src/wmnds/patterns/content-cards/travel-updates/_travel-updates.njk

@@ -8,7 +8,7 @@
 {% set largeDisruptionsAreas = ["Hagley Road", "Ring Road"] %}
 {% set buses = ["9", "10", "12", "12A", "13", "13A", "126", "X8", "X10", "23"] %}
 
-{% call wmndsContentCard({ variant: "wmnds-content-card--travel-updates"}) %}
+{% call wmndsContentCard({ classes: "wmnds-content-card--travel-updates"}) %}
     <div class="wmnds-p-sm wmnds-col-1">
         <h2 class="wmnds-content-card__title">Travel updates</h2>
         <p>All routes through this disruption</p>

src/www/pages/components/content-card/index.njk.md

@@ -0,0 +1,133 @@
+{% extends "www/_layouts/layout-left-pane.njk" %}
+{% set pageTitle = "Content card" %}
+{% from "www/_partials/component-example/component-example.njk" import compExample %}
+{# Imports #}
+{% from "wmnds/components/content-card/_content-card.njk" import wmndsContentCard %}
+
+{% block content %}
+
+{% markdown %}
+{# About #}
+
+## About
+
+Content cards contain components and text. Against the page background, they help to draw the users attention to important information and help users to navigate content.
+The cards have many common use cases and applications, all of which can be found on the <a href="/patterns/content-cards" target="_self">content cards pattern page</a>.
+
+---
+
+{# Content card #}
+
+## Content card
+
+{# What #}
+
+### What is it?
+
+- A container with a white background and purple underline.
+- Any components and text can be used within a card.
+
+{# When not to #}
+
+### When not to use it?
+
+- When it is used in a set of cards for navigation purposes. Instead, use a Navigation card.
+
+{% endmarkdown %}
+
+{{
+    compExample([
+        wmndsContentCard()
+    ], {
+        componentPath: "wmnds/components/content-card/",
+        njk: true,
+        njkProps: wmndsContentCardProps,
+        js: false,
+        iframe: false
+    })
+}}
+
+{% markdown %}
+{# Navigation card #}
+
+## Navigation card
+
+{# What #}
+
+<h3>What is it?</h3>
+
+- A variation of the Content card where the whole card area is clickable.
+
+{# When to #}
+
+<h3>When to use it?</h3>
+
+- When it is part of a set of cards used for navigation.
+- When the whole card needs to be clickable.
+
+{# When not to #}
+
+<h3>When not to use it?</h3>
+
+- When multiple interactive components within the card are used. Instead, use a Content card.
+
+{% endmarkdown %}
+
+{{
+    compExample([
+        wmndsContentCard({
+            href: "https://designsystem.wmnetwork.co.uk/components/content-card/"
+        })
+    ], {
+        componentPath: "wmnds/components/content-card/",
+        njk: true,
+        njkProps: wmndsContentCardProps,
+        js: false,
+        iframe: false
+    })
+}}
+
+{% markdown %}
+{# Yellow modifier #}
+
+## Yellow modifier
+
+{# What #}
+
+<h3>What is it?</h3>
+
+- The styling of the card changes to match disruption yellow branding
+- The styling helps users through their journey to major roadworks and events information
+
+{# When to #}
+
+<h3>When to use it?</h3>
+
+- When you are linking to a disruptions (major roadworks and events) page
+- Only one card should be yellow on a page
+
+{# When not to #}
+
+<h3>When not to use it?</h3>
+
+- When you are not linking to a disruptions (major roadworks and events) page
+- To attract the user's attention to a campaign other than disruptions
+- When there is another yellow card on the page
+
+{% endmarkdown %}
+
+{{
+    compExample([
+        wmndsContentCard({
+            yellow: true
+        })
+    ], {
+        componentPath: "wmnds/components/content-card/",
+        njk: true,
+        njkProps: wmndsContentCardProps,
+        js: false,
+        iframe: false
+    })
+}}
+
+{% endblock %}

src/www/pages/index.njk

@@ -24,7 +24,7 @@
         <div class="wmnds-col-1">
         {{
           wmndsContentCard({
-            html: "<div class=\"wmnds-p-sm\"><h2>Current release</h2><p>The current release is <a href=\"https://github.com/wmcadigital/wmn-design-system/releases/tag/v$*version\" title=\"View release notes for version $*version on GitHub\" target=\"_blank\" rel=\"noopener noreferrer\">version $*version</a> which was released on $*releaseDate.</p><p>You can get alerts about new releases by <a href=\"https://docs.github.com/en/free-pro-team@latest/github/managing-subscriptions-and-notifications-on-github/viewing-your-subscriptions\" target=\"_blank\" rel=\"noopener noreferrer\">watching the design system on GitHub</a>.</p></div>"
+            contentHTML: "<div class=\"wmnds-p-sm\"><h2>Current release</h2><p>The current release is <a href=\"https://github.com/wmcadigital/wmn-design-system/releases/tag/v$*version\" title=\"View release notes for version $*version on GitHub\" target=\"_blank\" rel=\"noopener noreferrer\">version $*version</a> which was released on $*releaseDate.</p><p>You can get alerts about new releases by <a href=\"https://docs.github.com/en/free-pro-team@latest/github/managing-subscriptions-and-notifications-on-github/viewing-your-subscriptions\" target=\"_blank\" rel=\"noopener noreferrer\">watching the design system on GitHub</a>.</p></div>"
           })
         }}
         </div>