Builder Tips and Tricks

From iThemes Codex
Revision as of 07:48, 1 January 2013 by Sridhar (talk | contribs) (Modified How to have full width (100% wide background) modules)
Jump to: navigation, search

Create custom blog page template for Builder

  • Why: Although builder generates a blog index page using the content module, in some cases you might want to create your own listing of blog posts. Perhaps to select posts only from a specific category, or for whatever other reasons you can think of.
  • How: query_posts is a WordPress function that allows you to write your own WordPress loop. In Builder, the easiest way to create such a blog page is to
    • create a page template,
    • upload to your WordPress site,
    • write a new page (no need to add content),
    • select the newly created page template,
    • and publish the page.

Your page template should look something like this:

Template Name: Custom Blog Index Page

function render_content() {

<?php $paged = ( get_query_var('paged') ) ? get_query_var( 'paged' ) : 1; ?>
<?php query_posts( 'paged='. $paged . '&posts_per_page=' . get_option( 'posts_per_page' ) ); ?>

<?php if ( have_posts() ) : ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <?php if ( current_theme_supports( 'post-thumbnails' ) ) : ?>
            <?php the_post_thumbnail( array( 125, 125 ), array( 'class' => 'thumb' ) ); ?>
        <?php endif; ?>
        <h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
        <?php the_time( __( 'l, F j, Y', 'it-l10n-Builder' ) ); ?>
        <?php the_content_limit( 250, "more »" ); ?>
    <?php endwhile; ?>

    <div class="alignleft"><?php previous_posts_link('« Previous Page') ?></div>
    <div class="alignright"><?php next_posts_link('Next Page »') ?></div>
<?php endif; ?>



add_action( 'builder_layout_engine_render_content', 'render_content' );

do_action( 'builder_layout_engine_render', basename( __FILE__ ) );


Important Note 1: the actual content part (post header, date and content) is simplified, refer to the Child Themes index.php to see how it is actually coded for that specific Child Theme. Important Note 2: the content is displayed using the_content_limit(250, "more »") (see highlighted line), a function described in another tip on this page. You can use the_content() or the_excerpt(), depending on your requirements.

Limit the content of a post that is displayed on a blog index page

  • Why: In some cases, the_content() or the_excerpt() just don't fit your requirements.
  • How: Using a new function allows you to specify the number of characters you want to display on the blog index page, and what to use as the "more" text. Add the following function to your child theme's functions.php.
function the_content_limit($max_char, $more_link_text = '(more...)', $stripteaser = 0, $more_file = '') {
    $content = get_the_content($more_link_text, $stripteaser, $more_file);
    $content = apply_filters('the_content', $content);

   if (strlen($_GET['p']) > 0) {
      echo $content;
   else if ((strlen($content)>$max_char) && ($space = strpos($content, " ", $max_char ))) {
        $content = substr($content, 0, $space);
        echo $content = $content . " <a href='"; the_permalink(); echo "'>".$more_link_text."</a>";
   else {
      echo $content;

(Note: 95% of the code is based on this plugin by Alfonso Sanchez-Paus Diaz and Julian Simon de Castro).

Add a full width Header and/or Footer to your Builder theme

  • Why: Because you want to
  • How: Detailed instructions in this article.

Note: See for updated code.

How to have full width (100% wide background) modules

Add the following at the end of child theme's functions.php (WP dashboard -> Appearance -> Editor):

add_theme_support( 'builder-full-width-modules' );


  1. For simplicity sake, we say "full width modules". Technically speaking, it is not the modules that become full width, but their background wrappers.
  2. Few child themes like Expansion have the above line in their functions.php out of the box. In such cases, do not add it again.
  3. All custom CSS code should be placed at end of child theme's style.css.
Before & After screenshots showing the effect of adding above line of code in Default child theme
Before After
My Test Site 2013-01-01 10-49-01.png
My Test Site 2013-01-01 10-49-27.png

Structural change as a result of adding above line of code


.builder-container-outer-wrapper {
    max-width: 960px;
    width: 100%;

(where 960 is the layout width)


.builder-container-outer-wrapper {
    width: 100%;

How to set background of full width modules

All modules

If you would like to set the same background to every module of all layouts, i.e., throughout the site in a single shot, use the following sample CSS:

.builder-module-background-wrapper {
    background: gray;
My Test Site 2013-01-01 11-42-10.png

A specific module based on its ID

If you would like to set a background to a specific full width module, use the following sample CSS:

#builder-module-50842a8824755-background-wrapper {
    background: yellow;

where 50842a8824755 is the ID of module in question.

My Test Site 2013-01-01 11-19-53.png

The easiest way to obtain the CSS ID is by using Firebug. Below screenshot shows where builder-module-50842a8824755-background-wrapper can be found.

2013-01-01 11-15-31.png

A specific module based on its position

It is also possible to set background of a full width module based on its position in the layout from top. For example, the following sample CSS sets yellow background to top most modules of all layouts i.e, throughout the site.

.builder-module-1-background-wrapper {
    background: yellow;
2013-01-01 11-35-10.png

All modules of a certain type

It is also possible to set background of full width modules based on module type. For example, the following sample CSS sets yellow background to all widget bar modules in all layouts i.e, throughout the site.

.builder-module-widget-bar-background-wrapper {
    background: yellow;
My Test Site 2013-01-01 11-38-02.png

To change widget titles from the default h4 to any other heading tag

Go to

How to extend sidebar and/or content background so they reach till the bottom

Create a 1px tall image and set it to vertically repeat as background for .builder-module-content. This image can either be created from scratch or by taking a screenshot of the site and editing in Photoshop.

The 10 min video below shows how this can be done. It shows how to create an image in Photoshop which can be set using CSS as background for Builder's content module so the sidebar(s) and element (the actual content) appear to extend all the way to the bottom.

Tip: To watch the video in full screen, go to and click the small 4-arrow button.

Relevant forum topics:

How to add code just after <body> and just before </body>

Add the following in your child theme's functions.php. If the child theme does not contain this file, a new one can be created and the below code pasted.

add_action('builder_layout_engine_render_header', 'add_after_opening_body', 20 );
function add_after_opening_body() { ?> 
	HTML code that you want just after the opening body tag should be placed here 
<?php }

add_action('builder_finish', 'add_before_closing_body', 0 );
function add_before_closing_body() { ?> 
	HTML code that you want just before the closing body tag should be placed here 
<?php }

Sources: 1, 2.

How to add code before and after each widget

Here's an example that shows how we can add

<div class="custom_top"></div>

before every widget and

<div class="custom_bottom"></div>

after every widget.

Add the following to the child theme's functions.php:

function custom_filter_register_sidebar_options( $options ) { 
    $options['before_widget'] = $options['before_widget'] .'<div class="custom_top"></div>';
    $options['after_widget'] = '<div class="custom_bottom"></div>' . $options['after_widget'];
    return $options;
add_filter( 'builder_filter_register_sidebar_options', 'custom_filter_register_sidebar_options' );


How to replace H4 tags around widget titles with divs

The following code can be added before the closing PHP tag in your child theme's functions.php file to remove the H4 tags from around the widget titles:

function custom_modify_widget_wrappers( $options ) { 
    $options['before_title'] = '<div class="widget-title">';
    $options['after_title'] = '</div>';
    return $options;
add_filter( 'builder_filter_register_sidebar_options', 'custom_modify_widget_wrappers' );


Another example:

To replace h4 tags around widget titles with say h2, the following code can be used:

function custom_modify_widget_wrappers( $options ) { 
    $options['before_title'] = '<h2 class="widget-title">';
    $options['after_title'] = '</h2>';
    return $options;
add_filter( 'builder_filter_register_sidebar_options', 'custom_modify_widget_wrappers' );

How to add a search form at the right side in a nav bar

1. At Appearance -> Menus, build a custom menu having the items you would like to be shown on the nav bar.

2. Edit your layout and add a navigation module. Set it to show your custom menu.

3. Add the following before closing PHP tag in child theme's functions.php:

add_filter('wp_nav_menu_top-1_items','add_search_box', 10, 2);
function add_search_box($items, $args) {
        $searchform = ob_get_contents();
        $items .= '<li class="my-search-form">' . $searchform . '</li>';
    return $items;	

In the above replace "top-1" with the slug of your custom menu.

4. Add the following at the end of your theme's style.css:

.builder-module-navigation {
    float: right;
    margin-right: 0.5em;
    border-right: none;

#builder-module-4d8f8f64596b7 ul {
    float: none;

In the above replace builder-module-4d8f8f64596b7 with the ID of this module.

If you are using BuilderChild-City-Church, see this forum topic for sample CSS.

That's it!


This method is also explained here.

Links to specific customization requests

Designing a widgetized footer

IWfo.16-04-2011 14-01-22.png

Forum post

Positioning images at a fixed location in all widgets

3wa5.16-04-2011 14-22-06.png

Forum post

Setting up Go To Top named anchor

Forum post

builder_comments_popup_link action explained

The builder_comments_popup_link action triggers the builder_comments_popup_link() function by default. This function calls the comments_popup_link() function of WordPress but it also ensures that the link should be shown. For instance, the link should not be shown if the comments have been disabled for that content type per Builder's settings, if both comments and pings are disabled, or if a password is required in order to view the content and it has not been entered yet.

So keeping that call in place is very important. It can still be customized in the same way a comments_popup_link() function call is customized. Let's break out the arguments to see how that is done:

        '<div class="alignright_comments"><span class="comments">',
        __( 'Add Your Comment %s', 'it-l10n-Builder' ),
        __( '(0)', 'it-l10n-Builder' ),
        __( '(1)', 'it-l10n-Builder' ),
        __( '(%)', 'it-l10n-Builder' )

Now let's see that listing again while replacing the arguments with their meaning:

        action name,
        content to add before link,
        content to add after link,
        template which has %s replaced with the output from comments_popup_link,
        comments_popup_link argument zero comments,
        comments_popup_link argument one comment,
        comments_popup_link argument more than one comment,

So if you know how to modify comments_popup_link, you should now see how you can modify this action call.

Note that all the __( 'text', 'it-l10n-Builder' ) stuff is just for translation purposes. So __( '(%)', 'it-l10n-Builder' ) just means '(%)'.

Usage Example

To have an image and the words "Add your Comment" with the image and text being a link:

Since the comments_popup_link() arguments are the ones added to the link, to add an image to the link, we need to modify those arguments. Here's a quick example:

    $image_url = get_bloginfo( 'template_directory' ) . '/images/folder.png';
    $image = "<img src='$image_url' alt='comments' />";
        '<div class="alignright_comments"><span class="comments">',
        'Add Your Comment %s',
        "$image (0)",
        "$image (1)",
        "$image (%)"

Of course, this adds the folder icon and not a comment icon, but hopefully you can see what we are doing here and use it to add your own image. Note that get_bloginfo( 'template_directory' ) returns the base URL to the Builder directory. To get your child theme's directory URL, you can use get_bloginfo( 'stylesheet_directory' ).


How to show "My Theme" menu only to specific users

If the following section of code is added to your child theme's functions.php file, "My Theme" menu will only be shown to the user with a username of "admin".

function child_theme_restrict_my_theme_menu() {
    $user = wp_get_current_user();
    if ( 'admin' !== $user->user_login )
        remove_theme_support( 'builder-my-theme-menu' );
add_action( 'builder_customize_theme_features', 'child_theme_restrict_my_theme_menu' );

If you want to use a different username, replace "admin" text on the fourth line with the username you want to use. For example, to make it only show for username "james", it would look like:

function child_theme_restrict_my_theme_menu() {
    $user = wp_get_current_user();
    if ( 'james' !== $user->user_login )
        remove_theme_support( 'builder-my-theme-menu' );
add_action( 'builder_customize_theme_features', 'child_theme_restrict_my_theme_menu' );

The sample code below shows how to hide "My Theme" menu from everyone except Super Admins. This is a feature specific to multisite WordPress installations.

function child_theme_restrict_my_theme_menu() {
    if ( ! is_super_admin() )
        remove_theme_support( 'builder-my-theme-menu' );
add_action( 'builder_customize_theme_features', 'child_theme_restrict_my_theme_menu' );

How to redirect attachment links to corresponding posts

Search engine results might show links from your site leading to attachment pages which are not really that useful to the visitors. If you would like to have these links redirect to their corresponding post pages, follow this:

Duplicate image.php from Builder Parent theme into your child theme directory, then replace the entire content of image.php (the one in your child theme directory) with:

<?php wp_redirect(get_permalink($post->post_parent)); ?>

Forum topic:

More: and

How to view debug info in page source

Add ?builder_debug=1 at the end of webpage URL.

Ex.: If the page URL is, visit and view the page source. It should show Builder specific info like this:

2012-04-03 20-25-50.png

How to remove Header widget

Adding the following code in child theme's functions.php at the end (before closing PHP tag, if present) will remove Builder's Header widget from Appearance -> Widgets.

function unregister_some_widgets() {
add_action('widgets_init', 'unregister_some_widgets', 1);

How to set up print stylesheet such that only the content gets printed

1. Copy header.php from parent Builder directory into the child theme directory and edit it.


<link rel="stylesheet" type="text/css" media="print" href="<?php bloginfo( 'stylesheet_directory' ); ?>/print.css" />


<?php builder_add_stylesheets(); ?>

2. Create a file named print.css in child theme directory having this code:

.builder-module {
	display: none;

.builder-module-content .builder-module-sidebar-outer-wrapper {
	display: none;

.builder-module-content {
	display: block;