Home

wd_s

Hi. I'm a starter theme called wd_s, or wdunderscores. I'm a theme meant for hacking so don't use me as a Parent Theme. Instead, try turning me into the next, most awesome, WordPress theme out there. That's what I'm here for!

I feature some of the web's most proven technologies like: Tailwind, npm, webpack, Sass, and PostCSS. To help you write clean code (that meets WordPress standards), we tap into @wordpress/scripts for linting CSS and JavaScript. Did I mention that I'm also accessible? Yup. I pass both WCAG 2.1AA and Section 508 standards out of the box.

I also support Selective Refresh and Live Preview in the Theme Customizer.

Not to mention, I use Browsersync so you can watch your project update in real-time while you work.

Looking to use some of our custom Gutenberg blocks? It's easy! Add the WDS Blocks plugin for a quick starter including our Accordion and Carousel blocks.

Looking to use some of our Advanced Custom Fields Gutenberg Blocks? It's also easy! Add the WDS ACF Blocks plugin for a whole set of blocks built with ACF including: Accordion, Carousel, Call To Action, Fifty/Fifty, Hero, Recent Posts, and Related Posts.

Getting Started

1. Download and extract the zip into your wp-content/themes folder and rename wd_s to fit your needs.

2. Find & Replace

You'll need to change all instances of the name: wd_s.

• Search for: @package wd_s and replace with: @package project_name to capture the package name
• Update "WebDevStudios\wd_s,wd_s" to: "CompanyName\project_name,project_name" (with double quotes) in phpcs.xml.dist
• Search for: WebDevStudios\wd_s and replace with: CompanyName\project_name to capture the namespaces
• Update "webdevstudios/wd_s" to "companyname/project_name" (with double quotes) in composer.json
• Search for: , 'wd_s' and replace with: , 'project_name' (inside backticks) to capture the text domain
• Update Text Domain: wd_s to: Text Domain: project_name in style.css
• Update "wd_s" to: "project_name" (with double quotes) in phpcs.xml.dist and package.json
• Update 'wd_s' to: 'project_name' (with single quotes) in inc/setup/setup.php
• Search for: wd_s_ and replace with: project_name_ to capture all the function names
• Search for: 'wd_s- and replace with: 'project_name- to capture prefixed handles
• Search for wd_s.pot and replace with: project_name.pot to capture translation files
• Search for wdunderscores.test and replace with: project_name.test to match your local development URL
• Edit the theme information in the header of style.css to meet your needs

wd_s Folder Restructuring

If you've used wd_s in the past, you may notice that some things have changed; all the functions can now be found inside organized folders inside the /inc folder.

wd_s still works as it did previously, with all of the same functions available to you. However, most files inside the newly organized folders contain only a single function. This improves the clarity on what each function's purpose is, as well as avoids merge conflicts if you have a team working on a project using this theme.

Included PHP Files

Use the /inc folder to declare any theme functionality. All files in this folder are imported inside of functions.php.

Folders

The /inc folder is organized into subfolders based on the functionality/purpose of the code. These folders can be modified as needed, but the following structure is recommended:

inc/
└─── customizer/    (functions relating to the theme customizer)
└─── functions/     (general functions that don't fit into any other folder)
└─── hooks/         (theme hooks)
└─── post-types/    (theme post type registrations & functions)
└─── scaffolding/   (theme scaffolding functions)
└─── setup/         (functions relating to the theme setup)
└─── shortcodes/    (shortcode registrations)
└─── template-tags/ (functions that render markup for use in theme templates)
└─── README.md

Filenames

As a general rule, each .php file should contain a single function/action which should match the name of the file (replacing underscores with hyphens in the filename).

For example, function demo_function() {...} would be declared in a file named demo-function.php and stored inside an appropriate /inc subfolder.

Adding New Functions

To add a new function to wd_s, simply decide where it makes most sense for it to be placed.

Is it a hook? The /inc/hooks folder makes sense. A general function? It probably should go into /inc/functions. Feel free to add new folders as you see fit for organizational purposes.

New functions added as files will automagically be available to the theme. However, remember to correctly add the Theme's namespace to be able to use your new function in your template files (see below).

Function Naming Conventions

We have updated the function names across the board to be more descriptive of that function's purpose. This allows you to more easily scan the list of files inside a folder and know what you're able to do.

If you're getting a value (ie: expecting a return), we've named the function (and file) appropriately: get_trimmed_title() & get-trimmed-title.php.

If you're displaying something, we've used the term print: print_post_author() & print-post-author.php.

The goal was to use action words where possible to indicate what the function was doing, ie: get, print, disable, include, etc.

Namespacing

The Fine Print

We've moved away from function prefixing (_s_ or wd_s_) as a means to avoid function naming collisions and have adopted a more modern approach. You can find more information (Highly recommended reading) about PHP namespaces at Sal Ferrarello's blog here and here.

If you've used PHP Namespaces in the past, you know what to do. If they're new to you, read more below.

How to add a new function to wd_s

As mentioned above, create a new file inside a folder in the /inc folder with a descriptive name, then add your function to that file.

Above the function, add the namespace declaration: namespace WebDevStudios\wd_s; (or whatever you have customized it to).

If you're adding an action or a filter, add the __NAMESPACE__ constant to the add_action or add_filter method: add_action( 'wp_footer', __NAMESPACE__ . '\print_customizer_footer_scripts', 999 );

Note: Make sure you have a \ before the function name!

That's it! Your function is now available to use in a template part.

Calling a Namespaced function inside a template part

There is more than one way to do this (See Sal Ferrarello's blog post above), but we are using the Use method.

When calling a function inside a template part, ie: print_global_scaffolding_section(), make sure you have added the "use namespace" call at the top of that template part:

use function WebDevStudios\wd_s\print_global_scaffolding_section;

And you're done! Your newly-added function has now been called inside your file.

Installation

1. From the command line, change folders to your new theme folder

cd /your-project/wordpress/wp-content/themes/your-theme

2. Install theme dependencies and trigger initial build.

npm i --legacy-peer-deps

Development

From the command line, type any of the following to perform an action:

Command	Action
npm run watch	Builds assets and starts Live Reload and Browsersync servers
npm run start	Builds assets and starts Live Reload server
npm run build	Builds production-ready assets for a deployment
npm run lint	Check all CSS, JS, MD, and PHP files for errors
npm run format	Fix all CSS, JS, MD, and PHP formatting errors automatically

Contributing and Support

Your contributions and support tickets are welcome. Please see our contributing guidelines before submitting a pull request.

wd_s is free software, and is released under the terms of the GNU General Public License version 2 or any later version. See LICENSE.md for complete license.