jon-heller/skela-wp-theme

Skela is an opinionated but still fairly barebones WordPress theme.

Skela

Skela is an opinionated but still fairly barebones WordPress theme

Skela is an opinionated but still fairly barebones WordPress theme. Skela utilizes repositories, managers, services and models for a very object-oriented approach to organizing your WordPress data (more on that here).

Table of Contents

• Skela
  • Table of Contents
  • What's in the Box
  • System Requirements
  • Installation
  • Getting Started
  • Object-Oriented Approach
  • Gutenberg
  • Contributing
  • Code of Conduct
  • About Upstatement

🎁 What's in the Box

• Full Timber integration (of course)
• Built-in support for Ups Dock, so you can get a full WordPress site up a running with a few commands
• Easy documentation creation with Flatdoc
• Webpack via Laravel Mix
  • Comes packed with autoprefixer, vendor file extraction, Browsersync!
• Some really great WordPress plugins (and plugin management provided by Composer)
  • Advanced Custom Fields (ACF)
  • WP Migrate DP Pro
  • WP Environment Indicator
• Some useful PHP libraries
  • phpdotenv
  • carbon
  • whoops
• Linting and testing
  • JS, and PHP linting thanks to Prettier, ESLint, and phpcs
  • Accessibility testing with pa11y
  • Bundle size limiting with bundlesize
  • Husky to automatically run these lints and tests!
• CI setup for Travis (with deployment)

💻 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, we neatly packed into something called Ups Dock. To install it follow these steps:

1. Install Docker for Mac

2. Install ups-dock (Note that you can stop after the installation steps and come back to this README)

🛠 Installation

Clone the repository

This repository is just for your WordPress theme. WordPress itself lives elsewhere.

If you are using ups-dock, you can clone this repository to anywhere (i.e. your /Sites// folder).

If you are using another local development solution, or if you're a madman and are cloning this directly to a live server, it might live in the /wp-content/themes directory.

Updating theme name

In order to make this theme your own, do a case-sensitive search-and-replace of

• skela
• Skela
• SKELA

with your new and exciting theme name!

ACF and WP Migrate DB Pro

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

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

2. In composer.json, search-and-replace ACF_KEY and WP_MIGRATE_KEY with the respective license keys

Note: if opting out of one or both of these plugins, remove the desired entries from the repositories and require sections in composer.json

Setup

1. Ensure NVM and NPM are installed globally.

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

   Note: If you are switching to projects with other versions of Node, we recommend using something like Oh My Zsh which will automatically run nvm use

3. Run composer update

4. If you're not using ups-dock, you can stop here! Otherwise...

5. Copy the .env.sample into a new .env file

6. Run the install command:

   $ ./bin/install

Once completed, you should be able to access your WordPress installation via ups.dock!

If prompted for a login, the default in your .env file is admin / password

🏃‍ Getting Started

Development workflow

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

2. Run the start command to start the backend / static build server:

   $ ./bin/start

   Not using ups-dock? You can instead npm run watch

3. Open the Local URL that appears below [Browsersync] Access URLs: in your browser (https://localhost:3000/)

Quitting this process (Ctrl-C) will shut down the container.

Common wp-cli commands

If you've installed this theme using ups-dock, you can run wp-cli by typing ./wp-docker [command]

$ docker-compose exec wordpress wp [command]

To export the databse, use the following command:

$ docker-compose exec wordpress wp db export - > dbdump.sql

To SSH into the WordPress container, use the following command:

$ docker-compose exec wordpress /bin/bash

🔄 Object-Oriented Approach

Skela 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

Skela 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

Included Custom Blocks

Two custom Gutenberg blocks are included with Skela:

• 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.

👨‍👩‍👧‍👦 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!