README

Installation

Prerequisites

PHP 8.1 or higher
Composer
Node.js version 20 (managed with nvm)
npm package manager
MySQL/MariaDB or PostgreSQL database
Web server (Apache/Nginx)

Setup Steps

Clone the repository

git clone [repository-url]
cd govcmstemplate

Install PHP dependencies
```
composer install
```

Install and build theme dependencies

cd web/themes/custom/uswds_extend_custom
nvm use 20
rm -rf node_modules
npm install
gulp build

Database setup

Create a new database for your site
Copy web/sites/default/default.local.settings.php to web/sites/default/local.settings.php
Configure database connection in web/sites/default/local.settings.php

Install Drupal with configuration sync

The site has a predefined UUID in the existing configuration, so we need to install a base configuration first, then sync the site UUID, and finally import the full configuration.
```
drush site:install --existing-config -y --site-name="[YOUR_SITE_NAME]" --account-name=admin --account-pass=[YOUR_ADMIN_PASSWORD]
```
UUID Synchronization Process: Use the process outline here to synchronize the UUID, or use the sync_site_uuid defined below.

Fetch the current site UUID:

drush cget system.site uuid --format=string

Back up existing system site config file:

cp config/sync/system.site.yml config/sync/system.site.yml.backup

Replace UUID in system site config file (replace [CURRENT_UUID] with the UUID from the first command):

sed -i.tmp "s/^uuid: .*/uuid: [CURRENT_UUID]/" "config/sync/system.site.yml"
rm "config/sync/system.site.yml.tmp"

Import the configuration:

The config_split module requires multiple import runs to fully process configuration splits:

drush cr
drush cim -y
drush cr
drush cim -y
drush cr
drush cim -y

Final theme build

cd web/themes/custom/uswds_extend_custom
npm run build

Set file permissions
```
chmod -R 755 web/sites/default/files
```

Optional: Enable Sample Content

The govcsm_sample_content module provides demonstration content showcasing the various paragraphs, blocks, menus, and other features available in this USWDS template. This is useful for:

Exploring the available content types and paragraph components
Understanding how different USWDS elements are implemented
Having example content to reference when building your own pages
Testing theme functionality with realistic data

To enable sample content:

drush en -y govcsm_sample_content

This will install:

Sample pages demonstrating various paragraph types and layouts
Taxonomy terms and vocabularies used by the content
Example menus and navigation structures
Demonstration data including tables and interactive elements
Content showcasing USWDS components like heroes, cards, accordions, and more

Note: Sample content is intended for development and demonstration purposes. You may want to disable or remove this module before deploying to production.

Development Environment

For local development:

# Start development server
../vendor/bin/drush runserver

# Watch for theme changes
cd web/themes/custom/uswds_extend_custom
npm run watch

Theme Architecture

This project uses a layered theme architecture built on the U.S. Web Design System (USWDS):

Theme Hierarchy

USWDS Base Theme (web/themes/contrib/uswds/)

Community contributed Drupal theme that serves as the foundation of our theme stack
Provides core USWDS functionality and components

USWDS Extend Theme (web/themes/govcms/uswds_extend/)

Inherits from the base uswds theme
Provides enhanced functionality and components based on the U.S. Web Design System
Acts as an intermediate layer between the base theme and custom implementations

USWDS Extend Custom Theme (web/themes/custom/uswds_extend_custom/)

Inherits from uswds_extend
Site-specific customization layer
This is the theme that should be extended and customized for individual sites
Contains project-specific styles, templates, and functionality

Theme Development

When customizing the theme for your site:

Make modifications in web/themes/custom/uswds_extend_custom/
Avoid directly modifying the base uswds or uswds_extend themes
Follow the USWDS Design System guidelines for consistent implementation

Advanced Setup

UUID Synchronization Helper Function

For easier UUID management, you can use this bash function (add to your .bashrc or .zshrc):

sync_site_uuid () {
  local config_file="config/sync/system.site.yml"
  if [ ! -f "$config_file" ]
  then
          echo "Error: Config file not found: $config_file"
          return 1
  fi
  echo "Getting current site UUID..."
  local current_uuid=$(drush cget system.site uuid --format=string)
  if [ $? -ne 0 ] || [ -z "$current_uuid" ]
  then
          echo "Error: Failed to get site UUID from drush"
          return 1
  fi
  echo "Current site UUID: $current_uuid"
  local config_uuid=$(grep "^uuid:" "$config_file" | sed 's/uuid: //')
  echo "Config file UUID: $config_uuid"
  if [ "$current_uuid" = "$config_uuid" ]
  then
          echo "UUIDs already match. No changes needed."
          return 0
  fi
  cp "$config_file" "${config_file}.backup"
  echo "Created backup: ${config_file}.backup"
  sed -i.tmp "s/^uuid: .*/uuid: $current_uuid/" "$config_file"
  rm "${config_file}.tmp"
  echo "Updated UUID in $config_file"
  echo "Old UUID: $config_uuid"
  echo "New UUID: $current_uuid"
  local new_config_uuid=$(grep "^uuid:" "$config_file" | sed 's/uuid: //')
  if [ "$new_config_uuid" = "$current_uuid" ]
  then
          echo "✓ UUID successfully updated in config file"
  else
          echo "✗ Error: UUID update failed"
          return 1
  fi
}

Visual Regression Testing

Install BackstopJS globally: npm install -g backstopjs
Navigate to the web/ directory
Run backstop reference to capture screenshots from production site
Run backstop test to capture screenshots from local site
View the report at https://[YOUR_LOCAL_DOMAIN]/backstop_data/html_report/

Theme Architecture

This project uses a layered theme architecture built on the U.S. Web Design System (USWDS):

Theme Hierarchy

USWDS Base Theme (web/themes/contrib/uswds/)

Community contributed Drupal theme that serves as the foundation of our theme stack
Provides core USWDS functionality and components

USWDS Extend Theme (web/themes/govcms/uswds_extend/)

Inherits from the base uswds theme
Provides enhanced functionality and components based on the U.S. Web Design System
Acts as an intermediate layer between the base theme and custom implementations

USWDS Extend Custom Theme (web/themes/custom/uswds_extend_custom/)

Inherits from uswds_extend
Site-specific customization layer
This is the theme that should be extended and customized for individual sites
Contains project-specific styles, templates, and functionality

Theme Development

When customizing the theme for your site:

Make modifications in web/themes/custom/uswds_extend_custom/
Avoid directly modifying the base uswds or uswds_extend themes
Follow the USWDS Design System guidelines for consistent implementation

emanaton / govcms-uswds-drupal

Maintainers

Details

README

Installation

Prerequisites

Setup Steps

Optional: Enable Sample Content

Development Environment

Theme Architecture

Theme Hierarchy

Theme Development

Advanced Setup

UUID Synchronization Helper Function

Visual Regression Testing

Theme Architecture

Theme Hierarchy

Theme Development