Customization Best Practices

This article was last updated on the January 2, 2017.

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 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, 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 Views and they are the building blocks for working with X. 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 are stored in the following directory:

/framework/views/

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 Customizer 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:

/framework/views/integrity/

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

/framework/views/renew/

Most of Icon’s views can be found here:

/framework/views/icon/

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

/framework/views/ethos/

I mention 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:

/framework/views/global/

Global Views are elements that are the same throughout each Stack. A great example of this is the _navbar.php View found in this directory. The navbar for all three Stacks is the exact same structurally, it is merely styled different to support the aesthetic of each Stack. Because of this, instead of writing out a navbar 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.

Overwriting Output via Child Themes

Now that we understand what Views are and how X utilizes 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 knowledge base article on how to do this.

Once you have set everything up, you can now begin to modify core files from the safety of you 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, 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 I’m using Integrity and I want to modify the way my video post format is laid out. The first thing I would need to do is figure out which View outputs my 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 over this file (parent theme directory for context):

/x/framework/views/integrity/content-video.php

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

/x-child-integrity-light/framework/views/integrity/content-video.php

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

/x/framework/views/global/_navbar.php

To this location:

/x-child-integrity-light/framework/views/global/_navbar.php

That’s all there is to it! A couple new directories and a few clicks later, you’re on your way to creating customized markup for your project.

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 over the file that outputs your header from the parent theme to your child theme. In this case, it would be this file:

/x/framework/views/integrity/wp-header.php

Which you would then place here:

/x-chlid-integrity-light/framework/views/integrity/wp-header.php

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:

/x-child-integrity-light/framework/views/integrity/global-alert.php

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:

<?php x_get_view( 'integrity', 'global-alert' ); ?>

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:

<?php

// =============================================================================
// VIEWS/INTEGRITY/WP-HEADER.PHP
// -----------------------------------------------------------------------------
// Header output for Integrity.
// =============================================================================

?>

<?php x_get_view( 'global', '_header' ); ?>

  <!--
  BEGIN #top.site
  -->

  <div id="top" class="site">

    <?php x_get_view( 'global', '_slider-revolution-above' ); ?>

    <header class="masthead" role="banner">
      <?php x_get_view( 'global', '_topbar' ); ?>
      <?php x_get_view( 'global', '_navbar' ); ?>
      <?php x_get_view( 'integrity', '_breadcrumbs' ); ?>
    </header>

    <?php x_get_view( 'global', '_slider-revolution-below' ); ?>
    <?php x_get_view( 'integrity', '_landmark-header' ); ?>

And adding in the alert might look something like this:

<?php

// =============================================================================
// VIEWS/INTEGRITY/WP-HEADER.PHP
// -----------------------------------------------------------------------------
// Header output for Integrity.
// =============================================================================

?>

<?php x_get_view( 'global', '_header' ); ?>

  <!--
  BEGIN #top.site
  -->

  <div id="top" class="site">

    <?php x_get_view( 'integrity', 'global-alert' ); ?>
    <?php x_get_view( 'global', '_slider-revolution-above' ); ?>

    <header class="masthead" role="banner">
      <?php x_get_view( 'global', '_topbar' ); ?>
      <?php x_get_view( 'global', '_navbar' ); ?>
      <?php x_get_view( 'integrity', '_breadcrumbs' ); ?>
    </header>

    <?php x_get_view( 'global', '_slider-revolution-below' ); ?>
    <?php x_get_view( 'integrity', '_landmark-header' ); ?>

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.