WordPress Development Guide

Owned by Alex Struk
Last updated: Jul 21, 2023
4 min read

GDX Team Contacts

  • Shawn Turple - PO for Custom Web - in charge of the GDX Block Theme

  • Divid Kelsey - Server side/deveops

  • Howard Steve - Engagement

Experimental Branch - Deprecated

An experimental branch of the GDX theme has been created to support digital.gov.bc.ca: GitHub - bcgov/bcgov-wordpress-block-theme at experimental/digimod-digital-government. Features that are specific to the digital.gov.bc.ca functionality have been embedded into this branch. This branch should be kept up to date with the primary branch of the GDX block theme. Custom CSS and JavasScript is under sites/ folder. This mimics the original way in which Clean BC site was structured.

Asset Loader Mechanism (for reference only)

Due to the limitations of the network installation multi-site configuration used by GDX Custom Web team, customizations for specific sites are done via the BCGov Assets Loader plugin. This plugin allows the queuing of CSS and JavaScript assets via the media library. To allow this functionality, the user must be allowed to perform this action, this is done via the “Enable Asset Loader” checkbox on the user profile administration page. To use the asset loader, upload JavaScript/CSS to the media library and use the media library interface to enqueue the files into production. Typically the custom assets are developed as a supplemental project, with JavaScript being built with Veet builder. For example, see GitHub - codewisenate/digital-gov-block-theme-supplemental: Additional scripts and styles for the WordPress digital.gov.bc.ca block theme added with the Assets Loader plugin. This repository contains supplemental code used for digital.gov.bc.ca before it got moved into the experimental branch.

Content Development

Ensure that content appears normal on both large and small screens, this is a common issue. If the font appears too large on small screen, verify that rem’s are not set too high. For padding around groups, use the slider control (“2” is normally used - note it doesn’t correspond to 2 rems). Note that padding of “2” will be applied automatically for any groups with a background color.

Font sizes should always be in rems. Note that anytime a font size is set, either via a typography swatch or custom rem setting, CSS clamp is applied to the font size to allow fluid typography. For example “medium” text is defined as clamp(1.125rem, 1.125rem + ((1vw - 0.48rem) * 0.24), 1.25rem) for min/actual/max values.

Side scroll navigation pages

To create a page with a side scroll navigation, create a blank page and insert a pattern from Custom: DigitalGov General called Custom: Scrolling Sticky Navigation

Custom Blocks

Custom blocks should only be created for elements with novel functionality that cannot be accomplished with DOM manipulations. For the most part everything should be accomplished with default blocks and patterns.

JavaScript

JavaScript is used for various interactive components as well as basic DOM manipulation. DOM manipulations are done with modular vanilla JavaScript, no libraries are used. The files are built into minified versions during a production build.

CSS Development

A convenient way to develop CSS is through Appearance → Options → Additional CSS. Paste compiled, minified CSS into the window to apply it globally across the site. Note that this should no be used for production as the result is not cached and will be retrieved every time.

Custom styles don’t carry over into the administration interface (Block Editor), so if this is required, CSS must be copied into admin styles SCSS file.

Query Loader

To layout repeated elements created via ACF Forms, use the Query Loader block to create aggregations. To create the design for the elements, add Post Template block to create the layout. If it’s a list of cards that need to be made clickable, a DOM manipulation script converts links in the headings to instead having links wrap the entire card element.

Building

For development run

npm start

This will start a watcher using wp-scripts and will compile the project in real time. Note that linting in this mode is not active, so even if the project is functional, it may later fail during the production build process.

composer phpcbf

The above command will perform automatic linting of the PHP code.

composer phpcs

The above command will check PHP code for any rule breaks. May find things that weren’t fixed by phpcbf.

Runs previous 2 commands, plus other tasks: php tests, linting of JS, linting of CSS. Then it produces a checklist - versions must be up to date across the project in package.json and style.css and reminds you to update other items (composer.json, changelog.md, readme.md, include jira tickets, build assets if applicable, was documentation updated?). The output gets generated into checklist.md file.

Development Environment

Setup an instance of WordPress using localwp. Clone the theme into wp-content/themes. Depending if the development is done on the main branch of the experimental branch, a multisite configuration must be set or not, respectively. This is done via the wp-config setting.

Important

When the project is first pulled, must run composer install. Note that the version of node must be 18.