Theme Setup

Underscores _s

This section dives a little deeper into how we've configured the Underscores theme for our WordPress site builds and how we actually use it.

If you've cloned the WordPress instance or the Underscores theme from our Github Repository you'll notice it comes prepackaged with everything you need to start building. This includes the latest version of Bootstrap and a sample ACF Block to use within the Gutenburg Editor.

Throughout this documentation we will be referencing the default folder and file structure of the Underscores theme by Automatic. To view and/or download the latest version of this theme head to their website.

Folder Structure

When you first open up the theme folder you'll notice we've added a few directories. We'll take a look at these one by one and explain why they exist. In order of appearance:

/blocks

This folder contains the custom blocks created using Advanced Custom Fields PRO. As we mentioned earlier, we rely heavily on ACF PRO to create custom Gutenburg blocks for use within the page admin. To learn more about how to utilize the 'Blocks' feature with ACF PRO read their official documentation.

Inside of the /blocks folder you will see an acf-blocks.php file and a /sample-block folder. You can think of the acf-blocks.php file as the main config file for all things ACF. (This file is pulled into WordPress using a "require" statement in the functions.php file). This is where we setup caching optimization for our custom fields, add a custom "Block Category" so we can group together the custom blocks we create, and most importantly, register our custom blocks. You'll notice all of these hooks are already in place, including registering our first "sample-block".

Inside of the /sample-block folder you will see 3 files:

• block.json

• sample-block.css

• sample-block.php

block.json is used to setup the basic parameters for our custom block like the name, title, description and the path to the blocks template file.

sample-block.css is used to contain any styles specifically related to our block.

sample-block.php is the main template file for our block. This is where we pull in the custom fields, push them through some logic and print them to the screen.

This /sample-block can be used as a template for creating more blocks. Simply copy the entire /sample-block folder, rename it along with any other references to "sample-block" and register the block in the acf-blocks.php file.

/css

This folder contains all of our css files except for the main style.css file in the theme root. There are currently 3 files in this folder.

• style-defaults.css

• style-editor.css

• style-login.css

style-defaults.css houses some of the default normalization styles used in the main underscores theme. It also provides a few of the basic styles for default WordPress blocks. This file is enqueued by default in the functions.php file but it is not required.

style-editor.css is used to bring your custom front-end styles into the page admin. This helps when building out a page and gives you an accurate preview of any custom blocks that you have created. By default we're only including the Bootstrap CSS in this file. Any other custom styles required for preview will need to be added manually at your discretion. This file is enqueued by default in the functions.php file but it is not required.

style-login.css is used for styling the wp-login.php page. On occasion a client will request to have the loin page match the branding of the rest of the site. This file is enqueued by default in the functions.php file but it is not required.

/images

This folder contains all of the image assets related to your theme.

As a general rule of thumb we recommend that any images directly related to the theme (backgrounds, accents, etc.) be placed in this folder. This keeps those important images outside of the main media library where they could be edited by a user. It ensures that the styling elements for the custom theme remain protected and only accessible to the developers working with the theme.

/js

This is where we keep our custom Javascript and jQuery. You'll notice there is currently just one file in this folder, main.js. This file is enqueued with WordPress by default. Any Javascript or jQuery related to the theme can be kept in this file. Things like initializing custom sliders and adding toggle and dropdown functionality to a menu are acceptable scenarios.

What is not included in this folder are any 3rd party libraries or plugins. We have a special folder just for those in /lib. Keep reading...

/lib

This is where you'll host any 3rd party libraries used for the theme. Libraries like Bootstrap, Slick Slider or Masonry should be included here. You'll notice one folder already living in this directory, Bootstrap. By default we're enqueuing 2 files within this Bootstrap folder in our functions.php file. bootstrap.min.css and bootstrap.min.js You can follow a similar pattern when enqueuing files for other libraries. Simply pace the library in the /lib directory and enqueue the required files in the functions.php file.