The Builder 3.0 launch has changed a number of things with the child themes. The following document was used by the iThemes team to prepare all the child themes for this release. While it is a big change, there are many benefits for making the changes.

Having all the child themes follow this format really helped get all of the child themes more in line on a standard structure. This makes it easier to modify the child themes as there is less to learn with each one. This is also a benefit for the Style Manager which will be able to rely on having a set of standard classes to target resulting in more consistent results across different child themes.

This standardization also paves the way for exploring posibilities that we couldn't possibly have gone after before. One example of this is LoopBuddy which really only works if there is a consistent base for it to work from. While this is but one example, the potential of it has gotten us very excited.

This document is best followed by intermediate to advanced designers and developers. If following the instructions presented here are more than you are willing to apply to your own child themes, you have two options: Do nothing as pre-Builder 3.0 child themes will still work propery on Builder 3.0 while only sacrificing compability with LoopBuddy and some potential future projects. Take an existing child theme that is already updated and modify it to match your child theme.

Enough of the chitchat. Time for getting some child themes updated.


A big part of the structure changes for the updated child themes is compliance with The Loop Standard. The Loop Standard divides a loop into two main concepts: a loop and one or more entries.

Both a loop and an entry have three sections: a header, a content section, and a footer. The header contains title information, any meta information, and any necessary navigation links. The content section contains the content relevant to that loop or entry. The footer section is a place to hold additional or duplicate meta information and navigation links.

The content of a loop is a bit more complex than the content of an entry as a loop's content contains the entries. To better visualize this, here is the basic structure described so far:

The idea is that each section is broken out in a repeatable pattern. This makes styling easier as any content that follows this form can be styled without having to first read through the code in order to understand the structure.

You may notice that there are titles, navigation, and meta for both the entries and the loop. This is because some titles, navigation, and meta are relevant to the loop (the title archive, navigating between pages of posts, or information about an author in an author archive) while other titles, navigation, and meta are relevant to the entry (the blog post's title, navigating through a page split into multiple pages, or a blog post's category information). The rule of thumb is that if the information is specific to an individual post's, page's, etc content, it is an entry-level structure; otherwise, it is a loop-level structure.

Each of these sections have a specific class in the Loop Standard. Here is the structure again with the classes replacing the names:

Notice the "hentry" class. This looks odd but is already produced by Builder and is actually generated by WordPress internally. It is produced by the post_class() function that is in all of our theme template files. So when you see "hentry", know that this is simply the div that looks like <div <?php post_class(); ?>>.

Currently, the Builder theme and child themes have a different structure. The goal is to change these structures to match this one so that LoopBuddy and other future plugins that use the Loop Standard can work seamlessly.

A typical Builder structure looks like the following:

Notice that it is similar but also much less consistent. Some similar elements have very different names and some elements don't really have a reliable name to reference them by. The Loop Standard aims to rid the structure of this ambiguity.

Now let's look at the previous structure after being updated to the Loop Standard structure. The elements in bold were added. The modified class names have their original names noted in parenthesis.

Not all the elements from above structure examples were used since not all were needed. In the end, only three elements had to be added. The rest of the changes were simply modifying or adding classes to conform to the Loop Standard structure. For some elements, such as "date", the "date" class remained while also getting the "entry-meta" class. This makes it clear what type of structure it is while still giving the additional meaning of it being a container for the date.

The following steps describe the basic process of updating Builder child theme template files to be compliant with the Loop Standard that LoopBuddy requires to function.

  1. Wrap everything inside the if ( have_posts() ) if block in a div with a class of loop. This is different for search.php templates. For an example of how to modify those templates, see the Builder theme.

    The following is an unmodified template:

    <?php if ( have_posts() ) : ?>
        <h4 class="page-title">Archive</h4>
        
        <?php while ( have_posts() ) : // The Loop ?>
            <?php the_post(); ?>
            
            <div <?php post_class(); ?>>
                <?php the_content(); ?>
            </div>
        <?php endwhile; ?>
    <?php endif; ?>

    The modified version looks like the following:

    <?php if ( have_posts() ) : ?>
        <div class="loop">
            <h4 class="page-title">Archive</h4>
            
            <?php while ( have_posts() ) : // The Loop ?>
                <?php the_post(); ?>
                
                <div <?php post_class(); ?>>
                    <?php the_content(); ?>
                </div>
            <?php endwhile; ?>
        </div>
    <?php endif; ?>
  2. The next big step is get the template into the basic structure needed by the Loop Standard.

    The following is a template that has only had the loop div added:

    <?php if ( have_posts() ) : ?>
        <div class="loop">
            <h4 class="page-title">Archive</h4>
            
            <?php while ( have_posts() ) : // The Loop ?>
                <?php the_post(); ?>
                
                <div <?php post_class(); ?>>
                    <!-- title, meta, and date info -->
                    <div class="title clearfix">
                        <div class="post-title">
                            <h3 id="post-<?php the_ID(); ?>"><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
                        </div>
                        
                        <div class="post-meta">
                            <?php printf( __( 'By %s', 'LION' ), '<span class="meta-author">' . builder_get_author_link() . '</span>' ); ?>
                            <?php do_action( 'builder_comments_popup_link', '<span class="meta-comments">· ', '</span>', __( 'Comments %s', 'LION' ), __( '(0)', 'LION' ), __( '(1)', 'LION' ), __( '(%)', 'LION' ) ); ?>
                        </div>
                        
                        <div class="date">
                            <span class="weekday"><?php the_time( 'l' ); ?><span class="weekday-comma">,</span></span>
                            <span class="month"><?php the_time( 'F' ); ?></span>
                            <span class="day"><?php the_time( 'j' ); ?><span class="day-suffix"><?php the_time( 'S' ); ?></span><span class="day-comma">,</span></span>
                            <span class="year"><?php the_time( 'Y' ); ?></span>
                        </div>
                    </div>
                    
                    <!-- "Read More" link -->
                    <div class="post-content">
                        <?php the_content( __( 'Read More→', 'LION' ) ); ?>
                    </div>
                    
                    <!-- categories, tags and comments -->
                    <div class="meta-bottom clearfix">
                        <?php do_action( 'builder_comments_popup_link', '<div class="alignright"><span class="comments">', '</span></div>', __( 'Comments %s', 'LION' ), __( '(0)', 'LION' ), __( '(1)', 'LION' ), __( '(%)', 'LION' ) ); ?>
                        <div class="meta-bottom-left">
                            <div class="categories"><?php printf( __( 'Categories : %s', 'LION' ), get_the_category_list( ', ' ) ); ?></div>
                            <?php the_tags( '<div class="tags">' . __( 'Tags : ', 'LION' ), ', ', '</div>' ); ?>
                        </div>
                    </div>
                </div>
                <!-- end .post -->
                
                <?php comments_template(); // include comments template ?>
            <?php endwhile; // end of one post ?>
            
            <!-- Previous/Next page navigation -->
            <div class="paging clearfix">
                <div class="alignleft"><?php previous_posts_link( __( '« Previous Page', 'LION' ) ); ?></div>
                <div class="alignright"><?php next_posts_link( __( 'Next Page »', 'LION' ) ); ?></div>
            </div>
        </div>
    <?php else : // do not delete ?>
        <?php do_action( 'builder_template_show_not_found' ); ?>
    <?php endif; // do not delete ?>

    Our task is to apply the basic structure. Let's focus on the "loop-header", "loop-content", and "loop-footer" first.

    The "loop-content" wrapper is easy to add. Simply start it before the main while loop and end it just after the loop finishes (at endwhile). The "loop-header" then contains everything inside the "loop" div that is before "loop-content" while "loop-footer" contains everything after "loop-content" and before the end of the "loop" div.

    For example:

    <?php if ( have_posts() ) : ?>
        <div class="loop">
            <div class="loop-header">
                <h4 class="page-title">Archive</h4>
            </div>
            
            <div class="loop-content">
                <?php while ( have_posts() ) : // The Loop ?>
                    <?php the_post(); ?>
                    
                    <div <?php post_class(); ?>>
                        <!-- title, meta, and date info -->
                        <div class="title clearfix">
                            <div class="post-title">
                                <h3 id="post-<?php the_ID(); ?>"><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
                            </div>
                            
                            <div class="post-meta">
                                <?php printf( __( 'By %s', 'LION' ), '<span class="meta-author">' . builder_get_author_link() . '</span>' ); ?>
                                <?php do_action( 'builder_comments_popup_link', '<span class="meta-comments">· ', '</span>', __( 'Comments %s', 'LION' ), __( '(0)', 'LION' ), __( '(1)', 'LION' ), __( '(%)', 'LION' ) ); ?>
                            </div>
                            
                            <div class="date">
                                <span class="weekday"><?php the_time( 'l' ); ?><span class="weekday-comma">,</span></span>
                                <span class="month"><?php the_time( 'F' ); ?></span>
                                <span class="day"><?php the_time( 'j' ); ?><span class="day-suffix"><?php the_time( 'S' ); ?></span><span class="day-comma">,</span></span>
                                <span class="year"><?php the_time( 'Y' ); ?></span>
                            </div>
                        </div>
                        
                        <!-- "Read More" link -->
                        <div class="post-content">
                            <?php the_content( __( 'Read More→', 'LION' ) ); ?>
                        </div>
                        
                        <!-- categories, tags and comments -->
                        <div class="meta-bottom clearfix">
                            <?php do_action( 'builder_comments_popup_link', '<div class="alignright"><span class="comments">', '</span></div>', __( 'Comments %s', 'LION' ), __( '(0)', 'LION' ), __( '(1)', 'LION' ), __( '(%)', 'LION' ) ); ?>
                            <div class="meta-bottom-left">
                                <div class="categories"><?php printf( __( 'Categories : %s', 'LION' ), get_the_category_list( ', ' ) ); ?></div>
                                <?php the_tags( '<div class="tags">' . __( 'Tags : ', 'LION' ), ', ', '</div>' ); ?>
                            </div>
                        </div>
                    </div>
                    <!-- end .post -->
                    
                    <?php comments_template(); // include comments template ?>
                <?php endwhile; // end of one post ?>
            </div>
            
            <div class="loop-footer">
                <!-- Previous/Next page navigation -->
                <div class="paging clearfix">
                    <div class="alignleft"><?php previous_posts_link( __( '« Previous Page', 'LION' ) ); ?></div>
                    <div class="alignright"><?php next_posts_link( __( 'Next Page »', 'LION' ) ); ?></div>
                </div>
            </div>
        </div>
    <?php else : // do not delete ?>
        <?php do_action( 'builder_template_show_not_found' ); ?>
    <?php endif; // do not delete ?>
  3. Let's continue from the previous example and add the "entry-header", "entry-content", and "entry-footer" sections.

    <?php if ( have_posts() ) : ?>
        <div class="loop">
            <div class="loop-header">
                <h4 class="page-title">Archive</h4>
            </div>
            
            <div class="loop-content">
                <?php while ( have_posts() ) : // The Loop ?>
                    <?php the_post(); ?>
                    
                    <div <?php post_class(); ?>>
                        <!-- title, meta, and date info -->
                        <div class="entry-header clearfix">
                            <div class="post-title">
                                <h3 id="post-<?php the_ID(); ?>"><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
                            </div>
                            
                            <div class="post-meta">
                                <?php printf( __( 'By %s', 'LION' ), '<span class="meta-author">' . builder_get_author_link() . '</span>' ); ?>
                                <?php do_action( 'builder_comments_popup_link', '<span class="meta-comments">· ', '</span>', __( 'Comments %s', 'LION' ), __( '(0)', 'LION' ), __( '(1)', 'LION' ), __( '(%)', 'LION' ) ); ?>
                            </div>
                            
                            <div class="date">
                                <span class="weekday"><?php the_time( 'l' ); ?><span class="weekday-comma">,</span></span>
                                <span class="month"><?php the_time( 'F' ); ?></span>
                                <span class="day"><?php the_time( 'j' ); ?><span class="day-suffix"><?php the_time( 'S' ); ?></span><span class="day-comma">,</span></span>
                                <span class="year"><?php the_time( 'Y' ); ?></span>
                            </div>
                        </div>
                        
                        <!-- "Read More" link -->
                        <div class="entry-content">
                            <?php the_content( __( 'Read More→', 'LION' ) ); ?>
                        </div>
                        
                        <!-- categories, tags and comments -->
                        <div class="entry-footer clearfix">
                            <?php do_action( 'builder_comments_popup_link', '<div class="alignright"><span class="comments">', '</span></div>', __( 'Comments %s', 'LION' ), __( '(0)', 'LION' ), __( '(1)', 'LION' ), __( '(%)', 'LION' ) ); ?>
                            <div class="meta-bottom-left">
                                <div class="categories"><?php printf( __( 'Categories : %s', 'LION' ), get_the_category_list( ', ' ) ); ?></div>
                                <?php the_tags( '<div class="tags">' . __( 'Tags : ', 'LION' ), ', ', '</div>' ); ?>
                            </div>
                        </div>
                    </div>
                    <!-- end .post -->
                    
                    <?php comments_template(); // include comments template ?>
                <?php endwhile; // end of one post ?>
            </div>
            
            <div class="loop-footer">
                <!-- Previous/Next page navigation -->
                <div class="paging clearfix">
                    <div class="alignleft"><?php previous_posts_link( __( '« Previous Page', 'LION' ) ); ?></div>
                    <div class="alignright"><?php next_posts_link( __( 'Next Page »', 'LION' ) ); ?></div>
                </div>
            </div>
        </div>
    <?php else : // do not delete ?>
        <?php do_action( 'builder_template_show_not_found' ); ?>
    <?php endif; // do not delete ?>

    The sections should already be there. The classes simply need to be updated to reflect the new class name structure.

  4. Continuing, it is time to fill out the title, utility, and meta sections.

    <?php if ( have_posts() ) : ?>
        <div class="loop">
            <div class="loop-header">
                <h4 class="loop-title">Archive</h4>
            </div>
            
            <div class="loop-content">
                <?php while ( have_posts() ) : // The Loop ?>
                    <?php the_post(); ?>
                    
                    <div id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
                        <!-- title, meta, and date info -->
                        <div class="entry-header clearfix">
                            <h3 class="entry-title"><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
                            
                            <div class="entry-meta">
                                <?php printf( __( 'By %s', 'LION' ), '<span class="meta-author">' . builder_get_author_link() . '</span>' ); ?>
                                <?php do_action( 'builder_comments_popup_link', '<span class="meta-comments">· ', '</span>', __( 'Comments %s', 'LION' ), __( '(0)', 'LION' ), __( '(1)', 'LION' ), __( '(%)', 'LION' ) ); ?>
                            </div>
                            
                            <div class="entry-meta date">
                                <span class="weekday"><?php the_time( 'l' ); ?><span class="weekday-comma">,</span></span>
                                <span class="month"><?php the_time( 'F' ); ?></span>
                                <span class="day"><?php the_time( 'j' ); ?><span class="day-suffix"><?php the_time( 'S' ); ?></span><span class="day-comma">,</span></span>
                                <span class="year"><?php the_time( 'Y' ); ?></span>
                            </div>
                        </div>
                        
                        <!-- "Read More" link -->
                        <div class="entry-content">
                            <?php the_content( __( 'Read More→', 'LION' ) ); ?>
                        </div>
                        
                        <!-- categories, tags and comments -->
                        <div class="entry-footer clearfix">
                            <?php do_action( 'builder_comments_popup_link', '<div class="entry-meta alignright"><span class="comments">', '</span></div>', __( 'Comments %s', 'LION' ), __( '(0)', 'LION' ), __( '(1)', 'LION' ), __( '(%)', 'LION' ) ); ?>
                            <div class="entry-meta alignleft">
                                <div class="categories"><?php printf( __( 'Categories : %s', 'LION' ), get_the_category_list( ', ' ) ); ?></div>
                                <?php the_tags( '<div class="tags">' . __( 'Tags : ', 'LION' ), ', ', '</div>' ); ?>
                            </div>
                        </div>
                    </div>
                    <!-- end .post -->
                    
                    <?php comments_template(); // include comments template ?>
                <?php endwhile; // end of one post ?>
            </div>
            
            <div class="loop-footer">
                <!-- Previous/Next page navigation -->
                <div class="loop-utility clearfix">
                    <div class="alignleft"><?php previous_posts_link( __( '« Previous Page', 'LION' ) ); ?></div>
                    <div class="alignright"><?php next_posts_link( __( 'Next Page »', 'LION' ) ); ?></div>
                </div>
            </div>
        </div>
    <?php else : // do not delete ?>
        <?php do_action( 'builder_template_show_not_found' ); ?>
    <?php endif; // do not delete ?>

    I cheated a bit here. I do apologize for that. Notice that I moved id="post-<?php the_ID(); ?>" from the title's h3 tag to the div tag containing the post_class() function. This not only makes the h3 tag much cleaner, it puts that ID on an element that makes more sense.

    Another big change I made was to remove the "post-title" div and add the "entry-title" class to the h3 tag directly. The rest of the changes are simply modifying existing classes to conform to the new structure.

  5. The above steps will need to be done for each of the template files in the child theme.

  6. After updating the template files, go through the theme's style.css file in order to update class references to match the new ones. Here are some basic replacements to make:

    Of course, additional modifications may need to be made depending on the structure of the child theme being modified. Test your changes to make sure that everything looks as it should. Yes, this does mean cross-browser testing the theme again just to make sure.

  7. Since Builder 3.0 introduces the new Header module, this will need to be styled as well. The module has a base class of builder-module-header. Inside the Header module output are the title and tagline text. These elements have classes of site-title and site-tagline.

    Here is an example of styling you can use. This seems to work well in many themes:

    /*********************************************
        Header Module
    *********************************************/
    .builder-module-header {
        background: #FFFFFF;
    }
    .builder-module-header .builder-module-element {
        padding: 1.5em;
    }
    .builder-module-header .builder-module-sidebar {
        background: none;
    }
    
    .site-title {
        font-size: 3em;
        line-height: 1;
        margin: 0 0 .5em 0;
    }
    .site-tagline {
        font-size: 2em;
        line-height: 1;
        margin: 0;
    }

    Here is another example used in Anchor:

    /*********************************************
        Header Module
    *********************************************/
    .site-title,
    .site-title a,
    .site-title a:hover,
    .site-tagline,
    .site-tagline a,
    .site-tagline a:hover {
        color: #D0ECF3;
        font-family: "Trebuchet MS", Helvetica, sans-serif;
        font-size: 1em;
        font-style: italic;
        font-weight: bold;
        line-height: 1;
        height: auto;
        margin: .5em 0;
        padding: 0;
        text-shadow: 2px 2px 2px #333333;
    }
    .site-title a:hover,
    .site-tagline a:hover {
        color: #FFFFFF;
    }
    .widget .site-title,
    .widget .site-title a,
    .widget .site-title a:hover,
    .widget .site-tagline,
    .widget .site-tagline a,
    .widget .site-tagline a:hover {
        color: #335C7C;
        font-style: normal;
        text-shadow: 2px 2px 2px #999999;
        text-shadow: none;
    }
    .widget .site-title a:hover,
    .widget .site-tagline a:hover {
        color: #333333;
    }
    .site-title {
        font-size: 3em;
    }
    .site-tagline {
        font-size: 2em;
    }

    The main thing I modify in each theme is the background color. Sometimes a child theme has a background image on Widget Bar modules, and I will use that style in the Header if it looks good. The larger example has some more advanced styling such as matching some text shadows and other elements. So some child themes deserve more specific styling. To test this, I have a layout with Header, Navigation, Widget Bar, Content, and Footer setup from top to bottom. This setup is likely to be similar to what many users will use.

  8. Builder 3.0 adds IDs to the html tag for IE 6 - IE 9. These can be used to make targetted CSS modifications as a replacement for the IE-specific stylesheets. For example, if you want to target IE 6, use the #ie6 ID as part of a CSS selector.

    While removing the IE-specific stylesheets isn't necessary, to keep in line with how Builder core applies these specific rules, the change should be made.

    I have been adding these browser-specific rules at the bottom of the stylesheet in their own section, such as:

    /*********************************************
        Browser-Specific Fixes
    *********************************************/
    
    #ie6 .hentry img {
        max-width: 100%;
    }
    #ie7 .hentry img {
        max-width: none;
    }
  9. Builder 3.0 also adds the option to add specific styling for Gravity Forms that will only be used if Gravity Forms is enabled and the site administrator hasn't disabled the Plugin Features feature of Builder 3.0.

    To add the Gravity Forms styling to the child theme, create a style.css file containing the Gravity Forms-specific styling and put it in a new directory structure named plugin-features/gravity-forms/ (eg: BuilderChild-Example/plugin-features/gravity-forms/style.css). You can also add a script.js file to this directory structure if you want to run JavaScript that should only run when Gravity Forms is active.

  10. Add add_theme_support( 'builder-3.0' ); to the functions.php file. It can be added at the top just below the <?php tag. The release version of Builder 3.0 will check for this to enable the new template files.

  11. Builder 3.0 has an advanced header.php file that supports many new actions and filters that will make it easier to introduce new features without requiring child theme modification. Most of the time, the custom header.php file in the child theme can be removed without any different in functionality. If this is the case, simply remove the header.php file. If the file contains necessary elements, first copy the new Builder 3.0 header.php file into your child theme and then re-add your customizations.


That's it. You're done. Well... The changes are done, but now it is time to check your work.

Download the Loop Standard Test Plugin and activate it on the site you are making the theme changes on. When viewing a page generated by an updated template, you should see a bit of rainbow coloration. These colors help make sure that your modifications were made properly.

If everything is set up properly, you should see rainbow colors (Roy G Biv - Red, Orange, Yellow, Green, and Blue) going from the outside to the inside of the structure.

If there isn't an issue, the colors should flow from one to the other without skipping and there should not be any part of the structure that does not have a border around it.

For example, if red is touching yellow, you have an issue such as missing the "loop-content" wrapper.

Here is an example of a successful test: