From adc7037c88aa942e3aa277e8de76c78ec7679cb2 Mon Sep 17 00:00:00 2001 From: Houston Blyden Date: Thu, 14 Jan 2021 14:52:38 +0000 Subject: [PATCH] feat: message documentation (#554) * convert to markdown * add examples + properties * convert to markdown * add examples + properties * added help examples + props * remove brs * fix examples * update params * amendsd prop descriptions * remove njk trim/indents * reorder example props Co-authored-by: Catia Costa <34938764+catiarodriguescosta@users.noreply.github.com> Co-authored-by: Dayle Salmon <13015201+daylesalmon@users.noreply.github.com> --- .../travel-updates/travel-updates.njk | 8 +- .../components/message/help/_example.njk | 11 + src/wmnds/components/message/help/_help.njk | 10 +- .../message/help/_properties.njk.json | 19 ++ .../components/message/summary/_example.njk | 15 ++ .../message/summary/_properties.njk.json | 39 ++++ .../components/message/summary/_summary.njk | 4 +- .../travel-updates/_travel-updates.njk | 24 +- .../_confirmation-message.njk | 8 +- src/www/pages/components/message/index.njk | 153 ------------ src/www/pages/components/message/index.njk.md | 220 ++++++++++++++++++ 11 files changed, 334 insertions(+), 177 deletions(-) create mode 100644 src/wmnds/components/message/help/_example.njk create mode 100644 src/wmnds/components/message/help/_properties.njk.json create mode 100644 src/wmnds/components/message/summary/_example.njk create mode 100644 src/wmnds/components/message/summary/_properties.njk.json delete mode 100644 src/www/pages/components/message/index.njk create mode 100644 src/www/pages/components/message/index.njk.md diff --git a/src/wmnds/components/content-tiles/travel-updates/travel-updates.njk b/src/wmnds/components/content-tiles/travel-updates/travel-updates.njk index d631dd4dd..bd8680689 100644 --- a/src/wmnds/components/content-tiles/travel-updates/travel-updates.njk +++ b/src/wmnds/components/content-tiles/travel-updates/travel-updates.njk @@ -168,9 +168,9 @@ {% from "wmnds/components/message/help/_help.njk" import wmndsMsgHelp %} {{ - wmndsMsgHelp({ - message: 'Save bus routes to your homepage by pressing the star icon' - }) - }} + wmndsMsgHelp({ + contentText: 'Save bus routes to your homepage by pressing the star icon' + }) + }} {% endmacro %} \ No newline at end of file diff --git a/src/wmnds/components/message/help/_example.njk b/src/wmnds/components/message/help/_example.njk new file mode 100644 index 000000000..8b9be7685 --- /dev/null +++ b/src/wmnds/components/message/help/_example.njk @@ -0,0 +1,11 @@ +{% raw %} +{% from "wmnds/components/message/summary/_summary.njk" import wmndsMsgHelp %} + +{{ + wmndsMsgHelp({ + contentText: "Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum text.", + contentHTML: null, + dismissable: false + }) +}} +{% endraw %} diff --git a/src/wmnds/components/message/help/_help.njk b/src/wmnds/components/message/help/_help.njk index 3f5976811..7e0ec8ddf 100644 --- a/src/wmnds/components/message/help/_help.njk +++ b/src/wmnds/components/message/help/_help.njk @@ -1,18 +1,22 @@ {% macro wmndsMsgHelp(params) %} {% from "wmnds/components/icon/_icon.njk" import wmndsIcon %} -{# Set vars and defaults #} +{# Set content #} +{% set _content = params.contentHTML | safe if params.contentHTML else params.contentText %} +{% set dismissable = params.dismissable if params.dismissable === false else true %}
+{% if dismissable %} - {{ params.message | safe }} + {% endif %} + {{ _content }}
{% endmacro %} \ No newline at end of file diff --git a/src/wmnds/components/message/help/_properties.njk.json b/src/wmnds/components/message/help/_properties.njk.json new file mode 100644 index 000000000..031bd9ebb --- /dev/null +++ b/src/wmnds/components/message/help/_properties.njk.json @@ -0,0 +1,19 @@ +{ + "wmndsMsgHelpProps": [ + { + "name": "contentText", + "type": "string", + "description": "Required. The text that displays in the help message component. You can use any string with this option. If you set contentHTML, this option is not required and is ignored." + }, + { + "name": "contentHTML", + "type": "string", + "description": "Required. The HTML to use within the help message component. You can use any string with this option. If you set contentHTML, contentText is not required and is ignored." + }, + { + "name": "dismissable", + "type": "boolean", + "description": "If dismissable is set to true, the component will display a close icon. Defaults to true" + } + ] +} diff --git a/src/wmnds/components/message/summary/_example.njk b/src/wmnds/components/message/summary/_example.njk new file mode 100644 index 000000000..3caa567d2 --- /dev/null +++ b/src/wmnds/components/message/summary/_example.njk @@ -0,0 +1,15 @@ +{% raw %} +{% from "wmnds/components/message/summary/_summary.njk" import wmndsMsgSummary %} + +{{ + wmndsMsgSummary({ + type: "info", + title: "Information about XXXXXXXXX was successfully updated!", + subtitle: null, + contentText: "Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum text.", + contentHTML: null, + dismissable: false, + classes: null + }) +}} +{% endraw %} diff --git a/src/wmnds/components/message/summary/_properties.njk.json b/src/wmnds/components/message/summary/_properties.njk.json new file mode 100644 index 000000000..7a11e7fde --- /dev/null +++ b/src/wmnds/components/message/summary/_properties.njk.json @@ -0,0 +1,39 @@ +{ + "wmndsMsgSummaryProps": [ + { + "name": "type", + "type": "string", + "description": "Type of the message component. As default it is info. Available types: info, success, success-fill-no-icon, warning, error" + }, + { + "name": "title", + "type": "string", + "description": "The title text for the message displayed as h3." + }, + { + "name": "subtitle", + "type": "string", + "description": "The subtitle text for the message." + }, + { + "name": "contentText", + "type": "string", + "description": "Required. The text that displays in the message component. You can use any string with this option. If you set contentHTML, this option is not required and is ignored." + }, + { + "name": "contentHTML", + "type": "string", + "description": "Required. The HTML to use within the message component. You can use any string with this option. If you set contentHTML, contentText is not required and is ignored." + }, + { + "name": "dismissable", + "type": "boolean", + "description": "If dismissable is set to true, the component will display a close icon." + }, + { + "name": "classes", + "type": "string", + "description": "Classes to add to the summary container." + } + ] +} diff --git a/src/wmnds/components/message/summary/_summary.njk b/src/wmnds/components/message/summary/_summary.njk index bc56af365..5dc49fe82 100644 --- a/src/wmnds/components/message/summary/_summary.njk +++ b/src/wmnds/components/message/summary/_summary.njk @@ -21,6 +21,8 @@ {% endif %} {# Set classes #} {% set classes = " " + params.classes if params.classes %} +{# Set content #} +{% set _content = params.contentHTML | safe if params.contentHTML else params.contentText %} {% from "wmnds/components/icon/_icon.njk" import wmndsIcon %}
@@ -45,7 +47,7 @@ {% endif %}
- {{ params.message | safe }} + {{ _content }}
{% endmacro %} diff --git a/src/wmnds/patterns/content-cards/travel-updates/_travel-updates.njk b/src/wmnds/patterns/content-cards/travel-updates/_travel-updates.njk index 250b927c2..01f5d5fbf 100644 --- a/src/wmnds/patterns/content-cards/travel-updates/_travel-updates.njk +++ b/src/wmnds/patterns/content-cards/travel-updates/_travel-updates.njk @@ -18,11 +18,11 @@
{{ largeDisruption({ - strongText: area, - text: "Usual traffic", - iconLeft: "modes-isolated-roads", - iconRight: "general-success" - }) | trim | indent(8) + strongText: area, + text: "Usual traffic", + iconLeft: "modes-isolated-roads", + iconRight: "general-success" + }) }}
{% endfor %} @@ -34,11 +34,11 @@
{{ mediumDisruption({ - text: bus, - classModifiers: "wmnds-disruption-indicator-medium--success wmnds-disruption-indicator-medium--narrow-travel-updates wmnds-disruption-indicator-medium--narrow-travel-updates-bus", - iconLeft: "modes-isolated-bus", - iconRight: "general-success" - }) | trim | indent(12) + text: bus, + classModifiers: "wmnds-disruption-indicator-medium--success wmnds-disruption-indicator-medium--narrow-travel-updates wmnds-disruption-indicator-medium--narrow-travel-updates-bus", + iconLeft: "modes-isolated-bus", + iconRight: "general-success" + }) }}
@@ -51,8 +51,8 @@ {{ wmndsMsgHelp({ - message: 'Save bus routes to your homepage by pressing the star icon' - }) | indent(12) | trim + contentText: 'Save bus routes to your homepage by pressing the star icon' + }) }}
{% endcall %} diff --git a/src/wmnds/patterns/question/confirmation-message/_confirmation-message.njk b/src/wmnds/patterns/question/confirmation-message/_confirmation-message.njk index 9741c8340..325f53411 100644 --- a/src/wmnds/patterns/question/confirmation-message/_confirmation-message.njk +++ b/src/wmnds/patterns/question/confirmation-message/_confirmation-message.njk @@ -2,14 +2,14 @@ {% from "wmnds/components/message/summary/_summary.njk" import wmndsMsgSummary %} -{{- +{{ wmndsMsgSummary({ type: 'success-fill-no-icon', title: 'Request complete', subtitle: 'You can now start using your Swift card', - message: 'Your reference number is 12345', + contentHTML: 'Your reference number is 12345', classes: 'wmnds-text-align-center' - }) | trim --}} + }) +}} {% endmacro %} \ No newline at end of file diff --git a/src/www/pages/components/message/index.njk b/src/www/pages/components/message/index.njk deleted file mode 100644 index 6cc10cfa7..000000000 --- a/src/www/pages/components/message/index.njk +++ /dev/null @@ -1,153 +0,0 @@ -{% extends "www/_layouts/layout-left-pane.njk" %} -{% set pageTitle="Message" %} - -{% from "wmnds/components/message/summary/_summary.njk" import wmndsMsgSummary %} -{% from "wmnds/components/message/help/_help.njk" import wmndsMsgHelp %} -{% from "www/_partials/component-example/component-example.njk" import compExample %} - -{% block content %} -{# About #} -

About

-

What does it do?

- - -

When to use it?

- -
-

-{# Info message #} -

Information

-{{ - compExample([ - wmndsMsgSummary({ - type: 'info', - title: 'Information about XXXXXXXXX was successfully updated!', - message: 'Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum text.' - }) - ]) -}} -{# End info message #} - -

-{# Success message #} -

Success

-{{ - compExample([ - wmndsMsgSummary({ - type: 'success', - title: 'Success confirmation', - message: 'Details added if needed to confirm action.' - }) - ]) -}} -{# End success message #} - -

-{# Success message #} -

Success (fill)

-{{ - compExample([ - wmndsMsgSummary({ - type: 'success-fill', - title: 'Success confirmation', - message: 'Details added if needed to confirm action.' - }) - ]) -}} -{# End success message #} - -

-{# Warning message #} -

Warning

-{{ - compExample([ - wmndsMsgSummary({ - type: 'warning', - title: 'Warning message', - message: 'Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum.' - }) - ]) -}} -{# End Warning message #} - -

-{# Error message #} -

Error

-{{ - compExample([ - wmndsMsgSummary({ - type: 'error', - title: 'Error message', - message: 'Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum.' - }) - ]) -}} - -{# End error message #} -

- -{# Close message variant #} -

Close message variant

- -

What does it do?

- - -

When to use it?

- -{{ - compExample([ - wmndsMsgSummary({ - type: 'info', - title: 'Information about XXXXXXXXX was successfully updated!', - dismissable: true, - message: 'Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum.' - }) - ]) -}} -{# End close message variant #} - -

-{# Help message #} -

Help

- -

When to use it?

- -{{ compExample([ wmndsMsgHelp({ message: 'Details added what happened and what to do next.
-Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum.' }) ]) }} {# End Help message #} {% endblock %} diff --git a/src/www/pages/components/message/index.njk.md b/src/www/pages/components/message/index.njk.md new file mode 100644 index 000000000..e58d739b3 --- /dev/null +++ b/src/www/pages/components/message/index.njk.md @@ -0,0 +1,220 @@ +{% extends "www/_layouts/layout-left-pane.njk" %} +{% set pageTitle="Message" %} + +{% from "wmnds/components/message/summary/_summary.njk" import wmndsMsgSummary %} +{% from "wmnds/components/message/help/_help.njk" import wmndsMsgHelp %} +{% from "www/_partials/component-example/component-example.njk" import compExample %} + +{% block content %} + +{% markdown %} +{# About #} + +## About + +### What does it do? + +- Gives user feedback during the interaction with a website (informs about error, warning, success). Messages are colour coded and use symbols to reinforce the message. The structure of the message: what happened? what does it mean? what can user do about it?) + +

When to use it?

+ +- When user needs explicit indication that something has gone wrong (user error or website/app error) +- When user is about to do something that is destructive or when the result of an action is unexpected but it is not an error (Warning Message) +- When user needs confirmation of success (Success message) +- When user needs key information about upcoming change (Information message). +- Real time inline validation to inform users about the correctness of provided data. + +--- + +{# Info message #} + +## Information + +{% endmarkdown %} +{{ + compExample([ + wmndsMsgSummary({ + type: 'info', + title: 'Information about XXXXXXXXX was successfully updated!', + contentText: 'Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum text.' + }) + ], + { + componentPath: "wmnds/components/message/summary/", + njk: true, + njkProps: wmndsMsgSummaryProps, + js: false, + iframe: false + }) +}} +{# End info message #} + +{% markdown %} + +{# Success message #} + +## Success + +{% endmarkdown %} +{{ + compExample([ + wmndsMsgSummary({ + type: 'success', + title: 'Success confirmation', + contentText: 'Details added if needed to confirm action.' + }) + ], + { + componentPath: "wmnds/components/message/summary/", + njk: true, + njkProps: wmndsMsgSummaryProps, + js: false, + iframe: false + }) +}} +{# End success message #} + +{% markdown %} + +{# Success message #} + +## Success (fill) + +{% endmarkdown %} + +{{ + compExample([ + wmndsMsgSummary({ + type: 'success-fill', + title: 'Success confirmation', + contentText: 'Details added if needed to confirm action.' + }) + ], + { + componentPath: "wmnds/components/message/summary/", + njk: true, + njkProps: wmndsMsgSummaryProps, + js: false, + iframe: false + }) +}} +{# End success message #} + +{% markdown %} + +{# Warning message #} + +## Warning + +{% endmarkdown %} + +{{ + compExample([ + wmndsMsgSummary({ + type: 'warning', + title: 'Warning message', + contentText: 'Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum.' + }) + ], + { + componentPath: "wmnds/components/message/summary/", + njk: true, + njkProps: wmndsMsgSummaryProps, + js: false, + iframe: false + }) +}} +{# End Warning message #} + +{% markdown %} + +{# Error message #} + +## Error + +{% endmarkdown %} + +{{ + compExample([ + wmndsMsgSummary({ + type: 'error', + title: 'Error message', + contentText: 'Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum.' + }) + ], + { + componentPath: "wmnds/components/message/summary/", + njk: true, + njkProps: wmndsMsgSummaryProps, + js: false, + iframe: false + }) +}} + +{# End error message #} + +{% markdown %} + +{# Close message variant #} + +## Close message variant + +

What does it do?

+ +- Allows the user to dismiss an Information, Success, Warning or Error message. + +

When to use it?

+ +- When the information in the message is a response to a users action, or if the information is of low importance and only applies to a small set of users. + +{% endmarkdown %} + +{{ + compExample([ + wmndsMsgSummary({ + type: 'info', + title: 'Information about XXXXXXXXX was successfully updated!', + dismissable: true, + contentText: 'Details added what happened and what to do next. Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum.' + }) + ], + { + componentPath: "wmnds/components/message/summary/", + njk: true, + njkProps: wmndsMsgSummaryProps, + js: false, + iframe: false + }) +}} +{# End close message variant #} + +{% markdown %} + +{# Help message #} + +## Help + +

When to use it?

+ +- The help message should be used when a user requires guidance on how to complete a digital task successfully. +- The user will be able to close the help message once they understand how to complete the task. + +{% endmarkdown %} + +{{ compExample + ([ + wmndsMsgHelp({ + contentHTML: 'Details added what happened and what to do next.
Lorem ipsum lorem ipsum. Lorem ipsum lorem ipsum.' + }) + ], + { + componentPath: "wmnds/components/message/help/", + njk: true, + njkProps: wmndsMsgHelpProps, + js: false, + iframe: false + }) +}} + +{# End Help message #} +{% endblock %}