Best Practices

One of the questions that we are asked most often is how to alter the way a page is structured. It could be something as simple as removing an unwanted element, rearranging the order of elements on a page, or completely overhauling the page and starting from scratch. Whatever your goal, you'll definitely want to take advantage of the techniques laid out in this article to ensure you are doing things correctly and to keep your alterations safe from being overwritten in the event that you update your theme later on.

It's All a Point of "Views"

To effectively manage the architecture of all Stacks within X or Pro, we break down the theme into smaller pieces. This makes things much easier to work with rather than having to scan a huge file for a tiny part you're looking for. We call these small pieces of X and Pro Views and they are the building blocks for working with X and Pro. The structure of any given page is output by taking a selection of Views and piecing them together. Think of each View as a Lego brick, which can be used in conjunction with other bricks to build a more complex structure. All Views for X and Pro are stored in the following directory:

For the X header/Footer and Pro default Header/Footer (If you do not use the Header/Footer Builder) you can see the views in:

If you take a look at this directory in the theme, you will notice that there are more directories within. In the next section, we'll cover how each of these groupings of Views works.

Getting Granular

The Stack selection you have chosen in the Theme options will determine which folder most of your Views are going to come from. For example, if you are using the Integrity Stack, you would find most of the Views relevant to this Stack in the following directory:

As you might have guessed, if you were to choose Renew in the Theme Options, most of your Views would be found here:

Most of Icon views can be found here:

And finally, most of Ethos views can be found here:

We mentioned that most of the views for each of these Stacks can be found in these directories because there is one more that is very important, and that is the global directory found at the following location:

Global Views are elements that are the same throughout each Stack. A great example of this is the content-404.php View found in this directory. The 404 page for all three Stacks is the exact same structurally, it is merely styled differently to support the aesthetic of each Stack. Because of this, instead of writing out a 404 Page Not Found View for each Stack three times over, we utilize it in one place and import it into all of our Stacks, making things much more efficient and easier to keep up with over time.

The same structure is used in the legacy folder for the headers and footers. For example, you can find the same navbar.php file available in the global folder which will be available for all the stacks:

Overwriting Output via Child Themes

Now that we understand what Views are and how X and Pro utilize them to structure output of pages and posts, let's see how we can modify them ourselves. The first and most important step in this entire process is setting up a child theme. Child themes are vitally important in the customization process as they keep your alterations safe from being overwritten when you update the parent theme and will keep everything organized and manageable. If you are unfamiliar with child themes or how to set one up, be sure to read through our Docs article on how to do this.

Once you have set everything up, you can now begin to modify core files from the safety of your child theme. Doing so is surprisingly simple as it is effectively a slightly more involved version of copy and paste. What you will need to do is find the View that you plan on modifying in X or Pro, and then copy that View and its exact path over to your child theme. Let's take a look at an example of how we would accomplish this.

Let's say that we're using Integrity and we want to modify the way our video post format is laid out. The first thing we would need to do is figure out which View outputs our video post format. As it turns out, all individual bits of content for individual pages and posts feature the content prefix. In this particular example, we're going to want to copy this file (parent theme directory for context):

We will need to make a duplicate of this file and place it in the exact same file path in our child theme. Doing so would look like this (child theme directory for context):

We will need to create the necessary folders in the Child Theme.

Now that we have done this, WordPress will only look to our child theme file instead of the parent theme file. We can now easily alter anything we want about this post format in our child theme and it will be reflected as if we were updating a core file directly. This step can be repeated for anything from the /framework/legacy/cranium/headers/views/ directory. For example, if we wanted to update the way the navbar.php file in the global legacy Views directory functions, we would need to copy this file:

To this location:

That's all there is to it! A couple new directories and a few clicks later, we are on our way to creating customized markup for our project.

By Legacy folder we don't mean that there will be limited support. It is merely a wording choice to differentiate between the Pro Header/Footer Builder and normal X and Default Pro header/footer system. The default header/footers in X and Pro will be supported.

Creating and Using Your Own Views

But the fun doesn't stop there! You can take things a step further and create your own views if you desire. Let's say that you wanted to create an alert that you want to be able to display at the top of your site. The first thing you would need to do is copy the file that outputs your header from the parent theme to your child theme. In this case, it would be this file:

Which you would then place here:

After you have done that, you would then need to create your file for the alert and place it in the proper location in your child theme:

After you have added the content that you want to output with this file, the next step would be to add it to your header file. To do so, we'll take advantage of the x_get_view() function, which pretty much does exactly what it sounds like it will do. We'll be using the following code:

The first argument of this function tells WordPress which View directory our file is stored in, and the second is the slug for the file itself. Finally, we will need to take this and actually add it to our wp-header.php file in our child theme. The original markup of this file looks like this:

And adding the alert might look something like this:

You can see that just above the <?php x_get_view( 'global', '_slider-revolution-above' ); ?> line we've added in our global alert, easy peasy! Hopefully, you now have a better understanding of not only how simple it is to implement changes to the markup of the theme, but how beneficial it can be if you need to add your own unique markup as well.

Each example which we used in this article can be applied also to Pro theme with the same folder structures.

Summary

You now know the best way to customize any of our themes.