Developer information

If you are a developer on this project, this information is for you!

UW WordPress Theme was built using WP Rig

This theme was built using WP Rig (GitHub) 1.0.4. We have removed most references to WP Rig and most WP Rig functionality at this point (July 2023, version 2.3).

Requirements

The UW WordPress Theme theme requires the following dependencies. Full installation instructions are provided at their respective websites.

• PHP 7.2**
• npm
• Composer (installed globally)
• Node v14

**If you are on a Mac, you may also need PHP installed locally on your machine (not just in Local), to work with phpcs. The PHP version you have installed on your machine should match the version you are using in Local (and what is on CMS). Not sure how to install PHP? Install PHP on MacOS Monterey. (Is this a potential issue for Windows, too?)

Theme features

The UW WordPress Theme theme includes the following features.

• Bootstrap 4 integration
• Mobile-first
• Progressive enhancement
• Dynamic loading of JS/CSS files
• AMP-ready
• Component-based development

The UW WordPress Theme theme uses the following development tools. These will all be installed for you as part of the package installation. Note: if you already have Gulp installed, please make sure you are using version 4.

• BrowserSync
• Gulp 4
• WordPress coding standards
• Babel
• PostCSS
• ESLint
• VS Code integration

Installation

1. Clone or download this repository to the themes folder of a WordPress site on your development environment.
2. In command line, run npm install to install necessary node and Composer dependencies.
3. In command line, run npm run build to generate the theme.
4. In WordPress admin, activate the theme.
5. When you are ready to start development, run gulp.

Recommended code editor extensions

To take full advantage of the features in this theme, your code editor needs support for the following features:

• EditorConfig
• ESLint
• PHP CodeSniffer (phpCS)

Getting phpCS to work

Setting up phpCS is tricky and can be frustrating. Here are the steps that work for us. Please note these steps are for a Mac user. If you are on a PC, you may need to adjust.

1. Use Composer to install phpcs globally. If composer is not installed, use Homebrew to install it first (Note: if you already installed the theme, you should have Composer).

composer global require "squizlabs/php_codesniffer=*"

2. In your VS Code project directory, run:

composer require --dev squizlabs/php_codesniffer

3. Test to make sure it works:

phpcs --version

If you get an error, in /usr/local/bin make a symlink to /Users/<username>/.composer/vendor/bin/phpcs

ln -s ~/.composer/vendor/bin/phpcs /usr/local/bin/phpcs

(You may need to use sudo with this command)

4. Check for the WordPress coding standards installed in /Users/<username>/.composer/vendor/wp-coding-standards/wpcs before installing. If you do not have them in .composer, follow these steps to install the WordPress Standards files. Clone the WordPress standards repo into a wpcs directory in your home directory and add it to the config for phpcs

cd ~
git clone https://github.com/WordPress/WordPress-Coding-Standards.git wpcs
phpcs --config-set installed_paths /Users/<username>/wpcs

5. Test with phpcs -i to see if the WordPress standards were added. You should see something like this:

The installed coding standards are PEAR, Zend, PSR2, MySource, Squiz, PSR1, PSR12, WordPress, WordPress-Extra, WordPress-Docs and WordPress-Core

6. Install the VS Code phpcs extension
7. In the VS Code settings for phpcs, set the following:

Phpcs: Composer JSON Path: composer.json

Phpcs: Enable: check the box for "Control whether phpcs is enabled for PHP files or not"

Phpcs: Error Severity: 5

Phpcs: Executable path: /Users/username/.composer/vendor/squizlabs/php_codesniffer/bin/phpcs

Phpcs: Show Sources: check box for "Show sniff source codes in diagnostic messages"

Phpcs: Standard: You need to edit this in settings.json

settings.json:

"phpcs.enable": true,
"phpcs.standard": "WordPress",
"phpcs.executablePath": "/Users/<username>/.composer/vendor/squizlabs/php_codesniffer/bin/phpcs",
"phpcs.showSources": true

Note: you may have other configuration in settings.json but you'll need to set these for phpcs to work.

Working with the UW WordPress Theme theme

Please note some of this section has been copied from the WP Rig README.

You can install this theme in any development environment.

UW WordPress Theme uses BrowserSync to enable synchronized browser testing.

UW WordPress Theme uses a Gulp 4 build process to generate and optimize the code for the theme. All development is done in the /dev folder and Gulp preprocesses, transpiles, and compiles the files into the root folder. The root folder files become the active theme. WordPress ignores anything in the /dev folder.

Note: If you have previously used Gulp, you may encounter seemingly random errors that prevent the build process from running. To fix this issue, upgrade to Gulp 4 following the steps outlined in the WP Rig Wiki.

JavaScript files are automatically linted using ESLint in accordance with WordPress Coding Standards.

PHP and CSS files are automatically linted using PHP CodeSniffer in accordance with WordPress Coding Standards. To take full advantage of this setup, configure your code editor / IDE to automatically test for the WordPress Coding Standards.

Details on how to enable PHPCS in VS Code can be found in the WP Rig Wiki. More details on how to work with PHPCS and WordPress Coding Standards can be found at the WordPress Coding Standards Wiki. composer run-phpcs runs PHPCS locally. Note: It can be tricky to get this set up correctly in your environment but it's worth it!

build process

npm run build is the regular development process. While this process is running, files in the ./dev/ folder will be automatically compiled to the live theme and BrowserSync will update if it is enabled. Note: this is the same as running gulp.

bundle process

npm run bundle generates a [themename].zip archive containing the finished theme. This runs all relevant tasks in series ending with the translation task and the bundle task and stores a new zip archive in the root theme folder.

Component-based approach

Please note this section was copied from the WP Rig README.

UW WordPress Theme takes a component-based approach to WordPress themes. Out of the box, the compiled theme uses index.php as the core template file for all views (index, archives, single posts, pages, etc). The /optional folder holds optional template files that can be accessed via the WordPress Template Hierarchy. To activate these files, move or copy them into the root /dev folder. The /optional folder is ignored by the Gulp build process.

Global JavaScript files are placed in the /js folder and linted and optimized automatically. External JavaScript libraries are placed in the /js/libs folder. These files are not linted or optimized by the Gulp process.

Global stylesheets and stylesheets related to root-level php files are placed in the /css folder and are optimized automatically.

Content loop files are placed in the /template-parts folder.

style.css is loaded in <head> through a wp_enqueue_style() call in functions.php. It is the main stylesheet and serves up global styles and layouts only.

Progressive Features

Please note this section was copied from the WP Rig README.

Modern CSS, custom properties (variables), autoprefixing, etc

All CSS is processed through PostCSS and leveraging postcss-preset-env to allow the use of modern and future CSS markup like custom properties (variables).

postcss-preset-env (previously cssnext) passes all CSS through Autoprefixer to ensure backward compatibility. Target browsers are configured under browsers in the gulpfile.

Modern layouts through CSS grid, flex, and float

The theme generated by WP Rig is mobile-first and accessible. It uses the modern layout modules CSS grid and flex to support a minimalist HTML structure.

For backward compatibility with browsers who do not support modern layout modules, WP Rig provides the mobile-first layout across all screen widths and serves two-dimensional layouts as a progressive enhancement.