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. 

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, as opposed to loading the entire NYSDS on every page load. This helps cut down on 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. We are looking into a way of rendering the components server-side without standing up a separate node server.

Complex forms: Drupal form elements, particularly webform elements, are quite tricky to replace with web components. See the section on webforms for more information. We are considering writing a separate NYSDS Webforms module to handle all this automatically.

Things you should know

• The <nys-globalheader> component currently only allows for a single-level main menu.
• The <nys-unavheader> component does not include NYS universal alerts.
• The <nys-unavheader> does not have the capacity to strip www from the translation urls.
• The <nys-unavfooter> component doesn't have the option to include a language access menu.
• The <nys-table> component could use a prop that inserts a pager based on a minimum number of rows.
• The <nys-textarea> adds its value as an element attribute instead of managing it with a slot. We are wondering how this will affect full HTML data entry when used for content management or low-risk html for front-end users.
• Slotted descriptions aren't available for some form components.
• None of the following components allow for the component to conform 100% to the widths of their container and instead have a defined maxwidth: <nys-unavheader>, <nys-unavfooter>, <nys-globalheader>, <nys-globalfooter>.
• The <nys-pagination> component does not accept actions for its buttons. Instead, it emits an event which the developer must listen for and tie to an action. In drupal, those actions are usually an href. Drupal developers could tie the name and/or id of their components to the heading_id of the Drupal pager and write code to tie them together. It would be most helpful for the pagination component to have a pagerFor or similar property at some point in the future. Barring that, the future NYSDS Helper submodule will have a helpful example.

Components not yet implemented

• We are not incorporating the <nys-fileinput> component at this time. The Drupal component is complex and may include security measures that it would be unwise to accidentally override. As such, adding this component would require a more involved development story.
• We are not incorprorating the <nys-stepper> component at this time. The work needed to do so warrants a separate developmenet story.

Bugs

• Review the NYSDS issue queue for the full bug list.