Contribute to WP Rig

Once you start using WP Rig to develop your own themes, you may have questions, comments, suggestions and feature requests. You may even want to add or change something in WP Rig itself. In that case, there’s good news: WP Rig is open for contributions! 

The purpose of WP Rig is to give the WordPress community a robust theme development rig to build modern, progressive, performant themes. That is only possible with the contribution of people like you. 

Consider this your invitation to contribute back to the project in whatever way you want by: 

  • Filing or answering issues on the Github repo.
  • Writing documentation, tutorials or blog posts for the official site, or any other site.
  • Making video tutorials.
  • Doing conference talks, or in-person workshops.
  • Using WP Rig, and showing it off in the footer of your theme.

Whatever you like, WP Rig is your tool! It’s built by and for the people who use it, like you, and you can play a part in its future. 

Contributors welcome!

Advanced build features

For advanced users and advanced uses, there are some additional build processes. You can find them under package.json all the way at the bottom under scripts. 

Here we have all the different processes you can run using the “npm run” command. If you’ve followed the course, you should be familiar with two of these commands already: “npm run dev” and “npm run build”

“npm run dev” – This is the process that builds the entire theme, then spins up a browser sync and watches all of your files. 

“npm run bundle” – This bundles out the theme, and creates a separate folder and separate zip archive for when you’re done building. 

“npm run build” – This runs the entire build process without running browser sync and watch. So if you just want to spin up the theme once to see what it produces, you just say “npm-run build”, and you have “npm run gulp” if you want to target specific Gulp processes. 

You have the option to run any of the Gulp processes that sit inside the Gulp folder. Most of these processes are being run automatically in the other scripts, but if you want to target a Gulp process specifically, you can do this by running “npm run gulp [script]”. For example, to run the images Gulp processes, you will run “npm run gulp images”. Or to run the PHP process to check your code against current PHP coding standards, you’d run “npm run gulp php”.

These are advanced features which are for advanced purposes, but they are available to you. They’re also a good path into understanding how WP Rig works better. 

So if you’re ever curious about what’s going on, go check out “package.json” or the folder “/gulp” and see how the Gulp processes are built together to make everything work properly.

Build a basic component

(Note: click here to download the exercise files referenced in this video.)

Let’s start by wiring up the core related post component. Under template-parts/content, you’ll find entry_related.php. It’s a new file that contains what you see below: it’s just an h2 that gets output:

Then, there is an entry.php file in the same folder. Down below the article element, there is a conditional statement that says if we’re on a single post, then get the template part entry_related. (Which is the one we just looked at that outputs the h2.)

Next, start a development process by running “npm run dev” in your terminal so you can see the output in the browser. You should see a “Related posts” section appears after the main post, but before the previous and next navigation:

In this video, we’re going to build the basic component that exposes a template function we can use in entry_related.php to pull in some content. The first step is to create component folder and file. You’ll remember, all components sit under the “/inc” folder. You can see them here, and each component contains a folder and then a file inside just called “components”.

Next, create a new folder called “Related_Posts” and inside it, create a new file called “Component”. (Make sure to capitalize both the folder name and Component.php.)

Now, we want to introduce you to one of the most advanced coding techniques out there: stealing code. There is no point writing code from scratch if part of the work is already done, and you just need to modify that work.

What we need to start is a different component that does something similar to what we want to do, and there are several options available here.

The one I’m going to use is the Comments component. The reason is the Comments component does the two things I need the most in my component:

-First, it exposes a function, so it creates a new template tag that is used somewhere else in the theme, and I need to do the same: I need to expose the template tag I can use.

-Second, it enqueues a script: in action_enqueue_comment_reply_script(), it enqueues a script. The functionality is going to be Javascript-based, so we need to be able to enqueue a script.

I’m going to show you how that works. I’ll scroll down and highlight stuff I think I will need. Let’s see, we’ll go all the way down to here, this template_tags function, just copy it, paste it in, ah-ha, we have a new component! Well, not quite, we have to do some changes here. So off the top, we need to give it a proper name. So right now it’s Comments, we need it to be Related_Posts, and then we have to give it an actual name space. So again, Related_Posts. Then we have a list of all the dependencies and functions that are used inside this script, but since I don’t use any of these core functions here, I’m just going to take all of those out. But I’m going to leave Component_Interface and Templating_Component_Interface in place. That’s because I’m going to create a component, so Component_Interface needs to be there, and the Templating_Component_Interface is what allows us to expose template tags to the rest of the themes so we can actually use them. All right, scrolling down, you can see here it says class for managing component UI, I’m going to say class for related posts. Then it says that this class exposes a template tag called wp_rig the_comments, so I’m going to change this later, once I’ve created my function. Then we set up the actual class, and the entire component is wrapped inside this class, and you can see the class implements Component_Interface and Templating_Component_Interface, which are these two dependencies up here. Inside the class, there are a couple of things we need to do. First, we need to set up a unique identifier for this theme component, so I’m going to give this identifier related_posts so that it becomes an entity of its own right in WordPress. Then directly below, we have this initialize function that allows us to initialize different things, like add_action calls. I’m just going to take the actual call out but leave the initialize function in place, so we can use it later. Then scrolling down, we have this section, get template tags to expose as methods in the Template_Tags class. So this Template_Tags function is the one that allows us to build the custom function inside the component, and then expose it as a template tag to the rest of the theme. What we do here is give the new function a name or label, and that will be the label we use to actually call the template tag out in the theme, and then we point at a function inside the class here. And to make it simple, it’s a good idea to keep these the same. The function I’m going to build is called display_related_posts, and I’ll just take that and copy it and paste it in over here. And then of course I need to actually create that function, so directly underneath, I’ll set up a comment for myself. Display the related posts. I’m going to make some space so you can see what’s going on, and then here, I’ll set a public function display_related_posts, and inside this public function I want to just echo out, like that. Then I need to close my class so that my PHP is complete. And I can save the component file. Now that I’ve created this component, I need to register it with WordPress so it’s aware that this component exists in the first place. That’s done under the inc folder, in a file called theme.php. If you scroll to the very bottom of theme.php, you’ll find this protected functions get_default_components, and these are all the available components in the theme. So all you have to do here is add your new component to this list, and it is the folder name you’re looking for here, so mine is called Related_Posts. Then the final thing we need to do is call our new function, call display_related_posts. From entry_related, so in place of this call here, I’m going to go inside and say wp_rig, because we now have this function exposed, and output display_related_posts. And I can take away this, because that’s the end of the PHP file. Go back in my browser, and if everything works correctly, it’ll now say Related Posts here. Just to make sure this is actually the new code, I can say New Related Posts, like that. Let it reload, and it says New Related Posts. Okay, so now we have a component, we’ve exposed the function, and everything works the way it’s supposed to.

The role of PHP modules

 It’s one thing to get a full breakdown of how a starter theme works. It’s quite another to actually use the starter theme to build something, especially when that starter theme does things in new and different ways.

So, in this chapter, we’ll build a new component together from scratch using PHP, JavaScript, and CSS.

That way, you get hands-on experience on how all the things we’ve talked about up to this point actually fit together and work in production.

For this chapter, there are exercise files you can download here. For each movie, there’s a beginning branch marked “b” and an end branch marked “e”. You can open them up and follow along.

In this chapter, we’ll build a “Related posts” component that sits below the main post content:

This component is powered by JavaScript, uses the Rest API, and has some really snazzy features.

First of all, it finds the categories of the current post, and displays the three latest posts in any of the same categories. That’s why it’s called a related post component: it displays content that’s related to the current one you’re looking at.

Second, the related posts are only loaded if and when a user scrolls down to the related post section. If they don’t scroll that far, the query never happens, and the user saves that data.

Finally, the related post component uses the Rest API and JavaScript to make this query so it’s fully dynamic, which is pretty cool. We’ll get started in the next video by building a basic component.

Debug JavaScript

Out of the box, the JavaScript files in the /assets/js/src folder are compiled and minified before being placed in the /assets/js folder and served to the browser. This is sort of similar to what happens with CSS, but with some crucial differences.

First: all your JavaScript (and especially modern ES 2015 and ESNext) runs through Babel, which re-compiles it to work with older browsers. (In other words, the script that’s served to the browser is not the same as the script you wrote.)

Second: JavaScript minification is not just about removing spaces and commas. It actually involves rewriting the scripts to make it as small as possible, which makes it pretty much unreadable for humans — even if you un-minify it.

This is important, because in some rare cases, the script you write doesn’t work as expected once it’s gone through the Babel compilation, and you need to be able to figure out what’s going on in the compiled script.

For this reason, you can configure WP Rig to -not- minify JavaScript files during the build process. This is purely for development purposes, but it can be a useful tool for JavaScript debugging.

In this video, we review where and how to turn off JavaScript minification.

(Hint: it is similar to turning off minification for CSS. You can find the settings in config.default.json…but you cut, copy, paste and adjust those settings in your config.json file.