nys_ds
About the NYSDS
From the NYSDS website: "The New York State Design System helps teams rapidly design and build accessible, mobile-friendly web applications and sites."
The NYSDS incorporates the State of New York's design philosophy and policies into a library of web components that developers can use to quickly create accessible applications that adhere to the state's guidelines.
Purpose of this module
This module's purpose is to provide an easy way to incorporate components from the NYSDS into existing Drupal websites that still feature a traditional frontend using a traditional theme. This module isn't intended for use with detached frontends; for that you should simply include the entire design system as a part of your project.
Although it would be, in some ways, cleaner to incorporate the components in a new base theme, the use cases here are to:
- Make it easy to include the NYSDS in new sites with as little guess-work as possible while maintaining a basic standard of implementation from site to site.
- Include the NYSDS in existing sites with as little configuration as possible.
Methodology
This module contains a separate js file for each of the NYSDS web components along with a small list of shared dependencies. With each version of this module, the maintainers will run a fresh build of the included js components. You can see the separate documentation for building assets in the assets folder. if you want to contribute to this project or try things out for yourself.
Each js file in the components folder are represented by a Drupal library. This allows us to only include the code which is necessary to operate a component when it is actually needed. This helps cut down on page load times and it's simply the Drupal way.
Each library is paired with a default template found in this module's templates/components/[component] folders. This allows developers to incorporate the NYSDS web components without duplicating code. It also makes it easier to upgrade if changes are ever made to the components themselves.
Drawbacks of this methodology
Client-side rendering: Using the NYSDS components in the way we're using them in this module does mean they are rendered in the end-users' browsers. As such, some functional and visual regression tests will need special tools in order to render the pages.
Complex forms: Drupal form elements, particularly webform elements, are quite tricky to replace with web components.In particular, the NYSDS textinput component incorporates a lot of logic internally such as managing the label, description, error message, and hard-codes the placement of these elements. In drupal, these elements are often rendered separately and have their own separate templates. To work around this, you may need to forego some webform functionality (such as multiple values) and/or invoke the nysds/label component separately. At the moment, it is recommended that you save the NYSDS form components for simple or custom forms while relegating the rendering of more complex webforms to the webform module's built-in theme layer. It's likely a separate module will be needed to fully incorporate the NYSDS (or any web components really) into drupal/webform.
Dependencies
This module contains all the code necessary to incorporate NYSDS web components on a website; there is no need to download additional libraries. Moreover, this module does not rely on active connections to a CDN to run the libraries it uses.
This decision has been made deliberately. Each version of this module will follow specific releases of the NYSDS library and each release of this module will test any changes made in the NYSDS.
In this way, developers can rest assured that every change and feature has gone through a basic round of Drupal-specific testing before they upgrade the module on their own site. Still, it's always a good idea to read the NYSDS and this module's release notes before doing so.
Installing the module
composer require drupal/nys_ds:[specific version of the NYSDS you want to incorporate]
We do not recommend you use a ^ or a ~ to maintain the most recent version of this module. Instead, we recommend you treat each upgrade as a deliberate act and you test any changes in that version's changelog prior to upgrading.
After you install the module, we recommend you add it as a dependency for any of your themes and modules in which you intend on using the NYSDS web components.
Using the components
You can incorporate the NYSDS componets on your site in two ways -- either by using the component templates that come packaged with this module or by directly including the web component manually. In both cases, the components are added in twig templates.
Using the component templates in this module
The component templates can be added to any of your own twig templates whether they be traditional templates or component templates. You will replace all the divs, spans, and other elements with one or more web component includes. The include needs to reference the template directly using the @nys_ds namespace and pass it the variables it needs to fill the props.
{% include '@nys_ds/components/componentName/componentName.twig' with {
componentProp: drupal_twig_variable,
componentProp2: 100,
componentProp3: "hard coded string",
componentProp4: true,
componentProp5: drupal_twig_variable_2,
etc...
} %}
For example, let's say you have a block view display that lists alerts on the page and you want to use NYSDS Icons in the display:
{#
/**
* @file
* views-view-fields--alerts--block.html.twig
*/
#}
{% set alertType = fields.field_alert_type.content %}
{% if alertType == 'Warning' %}
{% set alertIcon = "warning" %}
{% elseif alertType == 'Information' %}
{% set alertIcon = "info" %}
{% endif %}
{% set alertLabel = fields.field_alert_label.content %}
<div class="alert" style="background-color: #{{ alertColor }}">
<div class="alert-label">
<span class="alert-icon">
{% include '@nys_ds/components/icon/icon.twig' with {
name: alertIcon,
color: '#000',
size: '24',
ariaLabel: alertType
} %}
</span>
<h2 class="label-text">{{ alertLabel }}</h2>
</div>
<div class="alert-message">
{{ fields.field_alert_message.content }}
</div>
</div>
As you can see above, the include refrences the icon component's twig file and it used the variables coming in from the view display template to set the props of the icon. In this case, it alternates between the warning and info icons. Note that it isn't necessary to include props you don't intend on using.
Referencing the components directly
If you're creating a more complex feature, you may wish to directly reference the actual NYSDS web component. You can do that in the following way:
{{ attach_library('core/components.nys_ds--icon') }}
<nys-icon
{% if alertType %} aria-label="{{ alertType }}" {% endif %}
color="#000"
{% if alertIcon %} name="{{ alertIcon }}" {% endif %}
size="24"
></nys-icon>
Note that it is imperative that you include the library attachment whenever and wherever you use this method. Attaching the library isn't necessary with the default templates since they're already included there.
Drupal has a method for auto-detecting and registering web components. That is why the format of the library attachment **must** be core/components-nys_ds--componentname. This is the format used when components are auto-detected by Drupal's theme layer.
If you like, you can always override these components like any other Drupal component.