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. The work required to successfully implement the NYSDS on webform components relies on the developer's expertise with twig debugging. Understanding which templates to alter and which variables to apply in the components is essential.

Incorporate existing templates with an include statement (recommended)

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. We recommend using this method wherever possible.

Here's a general example:

  {% include 'nys_ds:componentName' 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:icon' with {
          name: alertIcon,
          color: '#000',
          size: '24',
          ariaLabel: alertType
        } %}
      </span>
      <h3 class="label-text">{{ alertLabel }}</h3>
    </div>
    <div class="alert-message">
      {{ fields.field_alert_message.content }}
    </div>
  </div>

As you can see above, the include references 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.

Some of the components have properties that require full HTML markup and even other components. You can pass full render objects into these properties or you can simply set them.

For example, assume we have a block that we've created for a modal popup. In the block's template, we have created a markup block called modalActions and we have passed that to the modal's actions property which renders the buttons our modal needs. We are also simply passing the entire content object which will render all of the block's fields inside the modal's content slot.

  {% set modalActions %}
    {% include 'nys_ds:button' with {
      label: "Check it out!",
      href: "/check-this-out",
    } %}
  {% endset %}
  {% include 'nys_ds:modal' with {
    id: "check-this-out",
    heading: "You wanna see this!",
    markup: content,
    actions: modalActions,
  } %}

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.