/skela-wp-theme

An Upstatement-flavored starter theme for WordPress

Primary LanguagePHPMIT LicenseMIT

πŸ’€ Skela

An Upstatement-flavored starter theme for WordPress

Skela utilizes repositories, managers, services, and models for an object-oriented approach to organizing your WordPress data.

Note that this repository is just for your WordPress theme. The WordPress installation should live elsewhere.

Table of Contents

🎁 What's in the Box

πŸ’» System Requirements

Before you can start on your theme, you first need a way to run a LAMP/LEMP (Linux, Apache/nginx, MySQL, PHP) stack on your machine.

We recommend our very own Docker setup called Ups Dock. To install it follow these steps:

  1. Install Docker for Mac

  2. Install Ups Dock by following the installation steps in the README

πŸ›  Installation

  1. Ensure NVM and NPM are installed globally.

  2. Run nvm install to ensure you're using the correct version of Node.

  3. If you're not using Ups Dock, you can stop here! Otherwise...

  4. Duplicate the contents of .env.sample into a new .env file

    If you do not want to use Ups Dock, change the COMPOSE_FILE line in your .env to be:

    COMPOSE_FILE=docker-compose.yml

    TIP: To prevent build errors, make sure there are no commented out lines including the COMPOSE_FILE variable in your .env file.

Option 1: Contributing to Skela

  1. If you're installing this repository to contribute to Skela, all you need to do next is run the install command

    ./bin/install

  2. Once the install script succeeds, fire up your site with the start command

    ./bin/start

    Now you should be able to access your WordPress site on ups.dock!

    The default credentials for WP admin are admin / password (configurable via docker-compose.yml)

Option 2: Using Skela as a template for another project

If you're using Skela as a template for another project, there's a few more steps to go through in order to set up the project to use your desired theme name.

  1. Run the rename theme command and follow the prompt, which will set up the project with your desired theme name

    ./bin/rename-theme

  2. In package.json and composer.json, update repository and author information

  3. Run the install command

    ./bin/install

  4. Once the installation script has finished, run the start command

    ./bin/start

  5. In another terminal tab, run the setup theme command, which will activate your theme and update the seed database

    ./bin/setup-theme

The site should be up and running with BrowserSync at http://localhost:3000, which proxies http://skela.ups.dock if you're using Ups Dock, or http://localhost:8888 if you're not.

To access WP admin, visit /wp-admin. The default credentials are admin / password (configurable via docker-compose.yml)

(Optional) If you're running an Ups Dock build and you want to re-export the seed database without Ups Dock URLs, run the following command:

./bin/db-to-no-upsdock

Activating ACF & WP Migrate Plugins (Optional)

If you would like to use the Advanced Custom Fields (ACF) and WP Migrate DB Pro plugins, follow these steps:

  1. Purchase license keys from ACF and WP Migrate DB Pro

  2. In composer.json add the following to the "repositories" array

    {
  "type": "composer",
  "url": "https://composer.deliciousbrains.com"
},
{
  "type": "package",
  "package": {
    "name": "advanced-custom-fields/advanced-custom-fields-pro",
    "version": "5.12.3",
    "type": "wordpress-plugin",
    "dist": {
      "type": "zip",
      "url": "https://connect.advancedcustomfields.com/index.php?a=download&p=pro&k=ACF_KEY&t=5.12.3"
    }
  }
},

  3. Replace ACF_KEY with your license key

  4. Create a file called auth.json in the root directory and populate it with your API credentials from your Account settings page

    {
  "http-basic": {
    "composer.deliciousbrains.com": {
      "username": "COMPOSER_API_KEY_USERNAME",
      "password": "COMPOSER_API_KEY_PASSWORD"
    }
  }
}

  5. In composer.json add the following to the "require" object

    "advanced-custom-fields/advanced-custom-fields-pro": "5.11.1",
"deliciousbrains-plugin/wp-migrate-db-pro": "^2.2",
"deliciousbrains-plugin/wp-migrate-db-pro-cli": "^1.6",
"deliciousbrains-plugin/wp-migrate-db-pro-media-files": "^2.1",

  6. While the container is up, run ./bin/composer update

πŸƒβ€ Development Workflow

  1. Run nvm use to ensure you're using the correct version of Node

  2. Run the start command to start the container and webpack server

    ./bin/start

  3. Visit the localhost URL in your browser

    By default this is http://localhost:3000/, which proxies your project's Ups Dock URL (i.e. http://skela.ups.dock)

  4. Access the WP Admin Dashboard at /wp-admin (i.e. http://skela.ups.dock/wp-admin)

To shut down the container and development server, type Ctrl+C

Debugging

https://timber.github.io/docs/guides/debugging/#enable-debugging

Twig Functions

In twig files, there are two common function you can use to print variables to the page: dump() and print_r.

<pre>
  {{ dump(your_variable) }}
</pre>

{{ your_variable | print_r }}

Error Logs

The gitignored logs/error.log file is a good place to look when hitting β€œcritical error” screens during development. You can print to them using the error_log function, and can track updates to them in realtime using the following command:

./bin/logs

Debug Bar & Timber Debug Bar Plugins

For more in-depth information like showing query, cache, and other helpful debugging information, this repository includes the Debug Bar and Timber Debug Bar plugins.

Common wp-cli commands

If you've installed this theme using Ups Dock, you can use WP CLI with the wp script.

Start the Docker containers with ./bin/start and then run any of the following commands in a separate shell:

./bin/wp [command]

To update the local WordPress version:

./bin/wp core update

To export the database:

./bin/wp db export - > docker/conf/mysql/init-ups-dock.sql

To export the database and gzip it:

./bin/wp db export - | gzip -3 > docker/conf/mysql/init-ups-dock.sql.gz

To SSH into the WordPress container:

docker-compose exec wordpress /bin/bash

πŸš€ Deployment

When creating a deployment, we recommend generating a new release for your project with an appropriate version bump to the theme's version. This will help facilitate cache-busting for static assets, which receive the theme's version as a query string appended to the end of the path.

You can use the following script to bump the version numbers in this project's package.json and the theme's style.css (which is where the theme pulls the canonical version from):

./bin/versionbump [<newversionnumber> | major | minor | patch | premajor | preminor | prepatch | prerelease]

By default, running the script with no arguments will result in a patch version bump (so, from 1.0.1 to 1.0.2). The script utilizes npm-version behind the scenes to define the new version number; see those docs for more information on the available version options.

πŸ”„ Object-Oriented Approach

This theme utilizes repositories, managers, services and models for a very object-oriented approach to organizing your WordPress data.

Managers

Managers do things like:

  • set up your theme (register option pages, hide dashboard widgets, enqueue JS and CSS, etc.)
  • create custom post types and taxonomies
  • set up basic WordPress defaults

Models

Models hold and extend your data.

Have a press release post type that needs a bunch of extra functions? Create a class for them (extending Timber\Post) and put your logic there so you can keep your Twig clean!

Repositories

Repositories are a good place to put query related logic.

It could be used in situations like the following:

Let get me all the posts from September in the hot dog category!

Services

Services are for more low-lying functions, like routing.

πŸ“° Gutenberg

This theme has built-in support for easily creating custom Gutenberg blocks with the help of Advanced Custom Fields. Note that the pro version of ACF is required for this.

There is an example custom block under src/Blocks/SampleACFBlock/ACFBlock.php. This demonstrates creating a block using ACF functions that includes two fields. Those fields are rendered in the file templates/components/acf-block.twig.

Note that in order to get this example to work, you need to create a ACF field group containing two fields, some_headline and some_text, and then have the field group displayed if the block is equal to ACF block.

Read more details on creating Gutenberg blocks using ACF

Creating Custom ACF Blocks

  1. Create a new ACF block class file in /src/Blocks.

    There is an example custom block under src/Blocks/SampleACFBlock/ACFBlock.php. This demonstrates creating a block using ACF functions that includes two fields.

    Note that in order to get this example to work, you need to create an ACF field group containing two fields, some_headline and some_text, and then have the field group displayed if the block is equal to ACF Block. Be sure to keep your block name all lowercase. ACF drops all uppercase letters and your block might not appear as an option if the names are mismatched.

  2. Create a new twig file to render the ACF fields.

    The example block fields are rendered in the file templates/components/acf-block.twig.

  3. Invoke the ACF block class in /src/Blocks/Blocks.php.

  4. Add your new Gutenberg block to the array returned in the allowBlocks function in /src/Managers/GutenbergManager.php.

     public function allowBlocks($allowed_blocks)
 {
     return array(
         ...
         'acf/acf-block',
         ...
     );
 }

Read more about creating Gutenberg blocks using ACF

Included Custom Blocks

Two custom Gutenberg blocks are included:

  • Related Articles
  • Image Layout

These include basic styles so they can work out of the box. They require the Advanced Custom Field plugin to function. If you do not plan to use ACF, you can disable these blocks by removing the applicable lines in the constructor function of /src/Blocks/Blocks.php

These fields are managed using PHP in the file /src/Managers/ACFManager.php. You can make updates to the fields here. If you would rather using the ACF to make updates to these fields:

  1. Under Advanced Custom Fields -> Tools, import the JSON file in /gutenberg-acf-backups/
  2. Make updates to the fields
  3. Go to Advanced Custom Fields -> Tools and generate the PHP code
  4. Update the PHP code in /src/Managers/ACFManager.php. Make sure to only update the PHP code for one layout group at a time, as they are separated by function in the manager file.

β™Ώ Accessibility Testing

Pa11y is an automated tool that audits our website's pages for accessibility issues according to WCAG 2.1 AA standards. This tool captures machine detectable errors such as missing alt text, wrong heading order, browser errors, etc. For issues such as color contrast, keyboard navigation, or VoiceOver functionality, manual testing is advised.

To run the tests, run the following command:

npm run test:a11y <url>

where <url> is a valid URL, or one of local, staging or live. Running the command without specifying the url will default to local.

Configuring pa11y

The package.json file has preset configurations for pa11y under testing.accessibility.

  • paths (array): Paths appended to the specified URL.
  • ignore.codes (array): WCAG codes to ignore
  • ignore.selectors (array): CSS selectors to ignore

🌐 Configuring Multisite

You can configure your install for multisite by setting the following environment variables in docker-compose.yml:

services:
  wordpress:
    environment:
      ...

      # Configure WordPress for multisite
      WORDPRESS_MULTISITE: 1

      # Configure for subdomain routing
      # Leave this commented out for subdirectory routing
      # WORDPRESS_MULTISITE_SUBDOMAIN_INSTALL: 1

      ...

This can be done at anytime - before initial install or to convert an existing single site install to multisite. Note that if you are converting from single site to multisite you will need to restart your server with ./bin/start in order for the change to take effect.

For Subdomain

By default, multisite is configured to run in subdirectory mode:

skela.ups.dock/site-1
skela.ups.dock/site-2

If you are using Ups Dock, you can also configure it to run in subdomain mode with a few extra steps:

site-1.skela.ups.dock
site-2.skela.ups.dock

  1. Uncomment the following environment variable in docker-compose.yml

    WORDPRESS_MULTISITE_SUBDOMAIN_INSTALL: 1

  2. Update your VIRTUAL_HOST environment variable in docker-compose.ups-dock.yml

    For subdomain mode to work, you need to tell Ups Dock to route all subdomains of skela.ups.dock to this container:

    VIRTUAL_HOST: skela.ups.dock,*.skela.ups.dock

  3. Update the SSL certificates generated by Ups Dock to include your four level subdomains

    a. Navigate to your local copy of Ups Dock

    cd path/to/ups-dock

    b. Add your wildcard domain to the [ alternate_names ] section in config/openssl.conf

    DNS.1 = ups.dock
DNS.2 = *.ups.dock
DNS.3 = *.skela.ups.dock

    c. Regenerate certs and restart Ups Dock

    ./bin/gen-certs.sh
docker-compose up -d

Caveats

  • Subdomain installs won't work without Ups Dock (or another tool that allows you to map domains to Docker containers) as it will not work when your base domain is localhost

For more details about everything these config vars do under the surface, consult MULTISITE.md.

πŸ‘¨β€πŸ‘©β€πŸ‘§β€πŸ‘¦ Contributing

We welcome all contributions to our projects! Filing bugs, feature requests, code changes, docs changes, or anything else you'd like to contribute are all more than welcome! More information about contributing can be found in the contributing guidelines.

πŸ“— Code of Conduct

Upstatement strives to provide a welcoming, inclusive environment for all users. To hold ourselves accountable to that mission, we have a strictly-enforced code of conduct.

About Upstatement

Upstatement is a digital transformation studio headquartered in Boston, MA that imagines and builds exceptional digital experiences. Make sure to check out our services, work, and open positions!