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.
wp-cli commandsBefore 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:
Install Docker for Mac
Install Ups Dock by following the installation steps in the README
Run nvm install to ensure you're using the correct version of Node.
If you're not using Ups Dock, you can stop here! Otherwise...
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.ymlTIP: To prevent build errors, make sure there are no commented out lines including the COMPOSE_FILE variable in your .env file.
If you're installing this repository to contribute to Skela, all you need to do next is run the install command
./bin/installOnce the install script succeeds, fire up your site with the start command
./bin/startNow 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)
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.
Run the rename theme command and follow the prompt, which will set up the project with your desired theme name
./bin/rename-themeIn package.json and composer.json, update repository and author information
Run the install command
./bin/installOnce the installation script has finished, run the start command
./bin/startIn another terminal tab, run the setup theme command, which will activate your theme and update the seed database
./bin/setup-themeThe 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-upsdockIf you would like to use the Advanced Custom Fields (ACF) and WP Migrate DB Pro plugins, follow these steps:
Purchase license keys from ACF and WP Migrate DB Pro
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"
}
}
},Replace ACF_KEY with your license key
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"
}
}
}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",While the container is up, run ./bin/composer update
Run nvm use to ensure you're using the correct version of Node
Run the start command to start the container and webpack server
./bin/startVisit 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)
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
https://timber.github.io/docs/guides/debugging/#enable-debugging
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 }}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/logsFor more in-depth information like showing query, cache, and other helpful debugging information, this repository includes the Debug Bar and Timber Debug Bar plugins.
wp-cli commandsIf 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 updateTo export the database:
./bin/wp db export - > docker/conf/mysql/init-ups-dock.sqlTo export the database and gzip it:
./bin/wp db export - | gzip -3 > docker/conf/mysql/init-ups-dock.sql.gzTo SSH into the WordPress container:
docker-compose exec wordpress /bin/bashWhen 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.
This theme utilizes repositories, managers, services and models for a very object-oriented approach to organizing your WordPress data.
Managers do things like:
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 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 are for more low-lying functions, like routing.
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
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_headlineandsome_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.
Create a new twig file to render the ACF fields.
The example block fields are rendered in the file templates/components/acf-block.twig.
Invoke the ACF block class in /src/Blocks/Blocks.php.
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
Two custom Gutenberg blocks are included:
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:
Advanced Custom Fields -> Tools, import the JSON file in /gutenberg-acf-backups/Advanced Custom Fields -> Tools and generate the PHP code/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.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.
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 ignoreignore.selectors (array): CSS selectors to ignoreYou 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.
By default, multisite is configured to run in subdirectory mode:
skela.ups.dock/site-1
skela.ups.dock/site-2If 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.dockUncomment the following environment variable in docker-compose.yml
WORDPRESS_MULTISITE_SUBDOMAIN_INSTALL: 1Update 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.dockUpdate 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-dockb. 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.dockc. Regenerate certs and restart Ups Dock
./bin/gen-certs.sh
docker-compose up -dlocalhostFor more details about everything these config vars do under the surface, consult MULTISITE.md.
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.
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.
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!