Creating a Theme with USWDS

3rd Party JS frameworks with Liferay DXP

What is USWDS?

USWDS is the United States Web Design System, a JavaScript framework created by the US Federal Government to have a standard framework and look and feel for US Federal Government websites. With all the numerous department, sub groups, and websites that the US Government maintains, it makes sense to have a standard framework. Note that this is on the Federal level, not the State or local level.

What is it comparable to?

USWDS is comparable to ReactJS and AngularJS. While at the global commercial/enterprise level, the main options are ReactJS or AngularJS, the US Fed Gov uses USWDS.

How does that work in with Liferay?

USWDS would be integrated into Liferay the same way one would integrate AngularJS or ReactJS: include the libraries in the Liferay theme. You can do this when the Liferay theme is built and it's not too hard when using something like NPM. The USWDS webpage has steps and information on how to use NPM to download the package, or via zip file if you're in a situation where NPM is not allowed.

What are the steps?

Prerequisites (Have these installed before starting)

  1. Run the Liferay theme generator
    • Run yo liferay-theme

    • The theme generator will ask you for certain bits of info, such as the name, theme ID, version of DXP, and app server path. Fill it in as needed.

  2. Run the USWDS framework installation
    • Run npm init
    • From the theme directory, run npm install --save uswds@latest
  3. Create and style theme using Liferay best practices and the files found in the Liferay DXP Theme
    • Liferay uses FreeMarker as a templating language
    • Liferay theme changes are found in "portal_normal.ftl" and "navigation.ftl"

For reference:

Creating a theme for Liferay DXP
USWDS documentation

What does it look like?

Examples? Code repos?

You can find the code repos for the example theme here. Note, this is a POC, and is missing a few things that would be needed for a fully functional theme, but it shows that you can use the USWDS framework with Liferay.

How do I know if a theme uses USWDS?

A theme using USWDS will have certain tag markers, all namespaced with "usa-". Here's an example from the navigation section of the above page.

<nav aria-label="<@liferay.language key="site-pages" />" class="usa-nav">

<button class="usa-nav__close"><img src="${images_folder}/uswds/close.svg" alt="close"></button>

There's several instances of "usa-nav" and "usa-nav__close" in regards to how the Liferay navigation is done. We can also see it's using Liferay language keys.

Thanks

Many thanks to Evan Thibodeau, who did most of the work and advised me on understanding how it all came together.