Builder Extensions

From IThemes Codex
Revision as of 02:45, August 9, 2012 by Sridhar (talk | contribs) (Example 1)
Jump to: navigation, search


An extension extends or overrides the structure and/or style of a child theme. This is done via functions.php (to alter the structure) and style.css (to alter the style). An extension is nothing but a directory which typically has functions.php (optional), style.css plus optionally a corresponding images directory.

By default, Builder ships with 6 extensions which are designed to be used for displaying a listing of entries like Posts page or a category page or a archive. The default extensions reside in extensions directory under parent Builder directory. If you would like to make any changes to the extension files, copy the extension directory from parent Builder into child theme under a directory named extensions.

An extension is applied to either a layout or a view.

For the sake of documentation, let us consider this site: http://localhost/builder3/

There is a category in this site named Issues and the URL of this category page is http://localhost/builder3/category/issues/


The reason why this category page is not using the default layout (Right Sidebar in this example) is because a view is present that associates Archives view with Full Width layout by default in Builder.

How to apply (use) a extension

Example 1


Front page shows a static page.

Page titled "Blog" is set as Posts page.

The above two can be set in WP dashboard at Settings -> Reading.

How to apply "Teasers Layout - left" extension to the Posts page:

Case A

You have created a layout named "Blog Layout" to be used for your site's Posts page, i.e., for

1. Go to My Theme -> Layouts & Views -> Views. Add a Blog view to specify that Posts page uses "Blog Layout" layout. More info on this here and here.

2. Edit "Blog Layout", select "Teasers Layout - left" from the Extension dropdown and save the layout.

Case B

You do not want to use a separate layout for the Posts page.

Go to My Theme -> Layouts & Views. Add a view as shown in the image below.

2012-08-09 12-46-23.png

Note: If the default layout uses an extension, that extension will take precedence over the one created in the above view. In such cases, create a separate layout for the Posts page and use it as explained in Case A above.

List of extensions that Builder comes with

Featured Image Grid & Showcase

To apply Featured Image Grid & Showcase extension to Issues category page, we should add a view like so:


Screenshot of the category page on site:



  1. The images that appear on the page are featured images added in the posts.
  2. The output will not show any post that does not have a featured image.

Featured Image Slider

Displays Featured Image & Post Title of first 6 posts in a custom slider and the Featured Image, Post Title & Excerpt for the remaining posts.


Page Not Found message appears below the slider because there are only 3 posts. If we add 1 more,


Magazine Layout


Portfolio Layout


Teasers Layout - Image Left


Teasers Layout - Image Right



  • It is not possible to override the parent or child theme's template files like index.php, archive.php, single.php, page.php. If any such files are present in an extension, they will simply be ignored.
  • When an extension has functions.php, it will be executed (for the page using that extension) after the theme's functions.php has been executed.

Examples of customizing Extensions

Styling ContactBuddy

Showing posts from a category on a separate Page and applying an extension

Every category in WordPress by default will have a auto-generated page visible at a URL like (where category-a is the slug for a category titled Category A). We call this category page. It is straight forward to use a extension on this page by going to My Theme -> Layouts and Views, then Views tab, and adding a view to set a layout for our desired category page.

For example,


applies "Full Width" layout to http://localhost/builder3/category/issues/ (http://localhost/builder3 is just for example, it can very well be and uses Magazine layout for the display of posts.

The result is:


Let's say we want to have all posts from Issues category appear on a Page titled Issues List and use Magazine extension, follow the steps below. i.e., the objective is to have http://localhost/builder3/issues-list/ appear like the above screenshot.

1. Copy the extension that you would like to be use from parent directory into child directory

Ex.: from wp-content/themes/Builder/extensions/magazine to wp-content/themes/BuilderChild-Thinner/extensions/magazine

Note: If the child theme directory does not contain extensions directory, create it.


a. Rename the extension.

b. Edit functions.php to remove the if ( ! is_singular() ) ... limitation. Add query_posts() call just above the loop to restrict the posts from your desired category.


a. Rename wp-content/themes/BuilderChild-Thinner/extensions/magazine to wp-content/themes/BuilderChild-Thinner/extensions/magazine-issues

Edit wp-content/themes/BuilderChild-Thinner/extensions/magazine-issues/style.css.


Name: Magazine Layout


Name: Magazine Layout for Issues List Page

b. Edit wp-content/themes/BuilderChild-Thinner/extensions/magazine-issues/functions.php.


// Calling only if not on a singular
			if ( ! is_singular() ) {
				add_action( 'builder_layout_engine_render', array( &$this, 'change_render_content' ), 0 );


// Calling only if not on a singular
			//if ( ! is_singular() ) {
				add_action( 'builder_layout_engine_render', array( &$this, 'change_render_content' ), 0 );


<?php $paged = (get_query_var('paged')) ? get_query_var('paged') : 1; query_posts("cat=18&paged=$paged"); ?> <!-- Change 18 to ID of category from which posts should be shown -->

immediately above

<?php while ( have_posts() ) : // the loop ?>
2012-02-27 12-51-10.png

3. Create a layout and apply the extension from the previous step.



4. Create a Page in which you would like to have the posts from the specific category appear and set the layout to the one created in above step.



That's it!

If you would like to show posts from another category similarly on another Page, repeat the above process to create a new extension while remembering to specify the category ID and apply it to the Page.


One extra step has to be done in addition to the above to apply the above method in the case of Featured Image Grid & Showcase.


global $post, $wp_query;
			$args = array(
				'ignore_sticky_posts' => true,
				'posts_per_page'      => 9,
				'meta_key'            => '_thumbnail_id',
				'paged'               => get_query_var( 'paged' ),
			$args = wp_parse_args( $args, $wp_query->query );
			query_posts( $args ); // Query only posts with a feature image set.


global $post/*, $wp_query;
			$args = array(
				'ignore_sticky_posts' => true,
				'posts_per_page'      => 9,
				'meta_key'            => '_thumbnail_id',
				'paged'               => get_query_var( 'paged' ),
			$args = wp_parse_args( $args, $wp_query->query );
			query_posts( $args );*/ // Query only posts with a feature image set.

Modifying Portfolio extension so that 2 images appear per row rather than 3






  1. The width and height values used in the steps below are to be taken only as an example and are not to be treated absolute. They may have to be changed depending on child theme you are using and the layout width.
  2. We are going to edit the extension in parent theme directly. When Builder is updated, our custom edits will be erased. Therefore you have to either take a backup of the extension before updating and re-apply the changes or duplicate the extension, place it in child theme while making sure function names are changed.

Child theme: BuilderChild-Acute

Layout width: 980px

1. Edit wp-content/themes/Builder/extensions/portfolio/lib/image-size.php


add_image_size( 'it-portfolio-thumb', 350, 150, true );


	//add_image_size( 'it-portfolio-thumb', 350, 150, true );
	add_image_size( 'it-portfolio-thumb', 450, 193, true );

2. Edit wp-content/themes/Builder/extensions/portfolio/style.css


.portfolio-post-wrap {
	display: inline-block;
	width: 32.8%;
	vertical-align: top;


.portfolio-post-wrap {
	display: inline-block;
/* 	width: 32.8%; */
	width: 49%;
	vertical-align: top;


.portfolio-post img {
	width: 100%;
	max-width: 350px;
	height: auto;
	margin: 0;


.portfolio-post img {
	/*width: 100%;
	max-width: 350px;*/
	max-width: 450px;
	height: auto;
	margin: 0;

3. Refresh the page on the front-end for which Portfolio extension is being applied. If the new sized thumbnails do not appear, install and run Regenerate Thumbnails plugin.

Displaying archive/category title above the output of Portfolio extension

2012-06-22 10-03-56.png

1. Copy the extension from parent Builder directory into the child theme under extensions directory so that wp-content/themes/BuilderChild-themename/extensions/portfolio is present.

2. Edit wp-content/themes/BuilderChild-themename/extensions/portfolio/functions.php.


<div class="loop-content">


<div class="loop-header">
				<h4 class="loop-title">
						if ( is_category() ) { // Category Archive
							$title = sprintf( __( 'Archive for %s', 'it-l10n-Builder' ), single_cat_title( '', false ) );
						else if ( is_tag() ) { // Tag Archive
							$title = sprintf( __( 'Archive for %s', 'it-l10n-Builder' ), single_tag_title( '', false ) );
						else if ( is_tax() ) { // Tag Archive
							$title = sprintf( __( 'Archive for %s', 'it-l10n-Builder' ), builder_get_tax_term_title() );
						else if ( is_day() || is_time() ) { // Day-Specific Archive
							$title = sprintf( __( 'Archive for %s', 'it-l10n-Builder' ), get_the_time() );
						else if ( is_month() ) { // Month-Specific Archive
							$title = sprintf( __( 'Archive for %s', 'it-l10n-Builder' ), get_the_time( 'F Y' ) );
						else if ( is_year() ) { // Year-Specific Archive
							$title = sprintf( __( 'Archive for %s', 'it-l10n-Builder' ), get_the_time( 'Y' ) );
						else if ( is_author() ) { // Author Archive
							$title = sprintf( __( 'Author Archive for %s', 'it-l10n-Builder' ), get_the_author() );
						else if ( function_exists( 'is_post_type_archive' ) && is_post_type_archive() && function_exists( 'post_type_archive_title' ) ) { // Post Type Archive
							$title = post_type_archive_title( '', false );
						else { // Default catchall just in case
							$title = __( 'Archive', 'it-l10n-Builder' );
						if ( is_paged() )
							printf( '%s – Page %d', $title, get_query_var( 'paged' ) );
							echo $title;

How to change number of posts when using Featured Image Grid & Showcase extension

Copy the extension to your child theme and edit its functions.php.

Ex.: Copy wp-content/themes/Builder/extensions/image-grid to wp-content/themes/BuilderChild-Default/extensions/image-grid (create extensions directory in child theme directory if doesn't exist) and edit wp-content/themes/BuilderChild-Default/extensions/image-grid/functions.php.

Set your desired number of posts in the following line:

'posts_per_page'      => 6,

Showing products from a specific WP e-Commerce category in Slider extension

2012-07-24 20-41-37.png

When Slider extension is applied to a layout or view and that layout is used in a listing page (Ex.: Posts page, archives), the sliding images will be featured images attached to the blog posts. When you have WP e-Commerce plugin activated and would like to show images attached to products belonging to a specific WPEC category in the Slider, follow this:

Copy the extension to your child theme and edit its functions.php.

Ex.: Copy wp-content/themes/Builder/extensions/slider to wp-content/themes/BuilderChild-Depot/extensions/slider (create extensions directory in child theme directory if doesn't exist) and edit wp-content/themes/BuilderChild-Depot/extensions/slider/functions.php.


$args = array(
						'posts_per_page' => 6,
						'order'          => 'date',
						'meta_key'       => '_thumbnail_id'


$args = array(
						'posts_per_page' => 6,
						'order'          => 'date',
						'meta_key'       => '_thumbnail_id',
						'post_type'      => 'wpsc-product',
						'wpsc_product_category' => 'product-category'

In the above replace product-category with the slug of WP e-Commerce category from which you would like Product Thumbnails to be shown in the slider.

If you would like to know how to replace the standard blog posts that appear below the slider with products added in WP e-Commerce (screenshot below), see this forum topic.

My Test Site 2012-07-24 21-26-07.png

Displaying Slideshow at the top of Magazine layout

2012-08-08 10-16-27.png

If you would like to display PluginBuddy Slideshow above the posts when using Magazine extension, follow this:

Copy the extension to your child theme and edit its functions.php.

Ex.: Copy wp-content/themes/Builder/extensions/magazine to wp-content/themes/BuilderChild-Expansion-Blue/extensions/magazine (create extensions directory in child theme directory if doesn't exist) and edit wp-content/themes/BuilderChild-Expansion-Blue/extensions/magazine/functions.php.


<?php if ( have_posts() ) : ?>


<div id="my-slideshow-container"><?php echo do_shortcode('[pb_slideshow group="0"] '); ?></div>

In the above replace 0 with the ID of Slideshow group that you would like to be shown.

The following has been added at the end of child theme's style.css (WP dashboard -> Appearance -> Editor) in this particular example:

#my-slideshow-container {
    margin-bottom: 4em;

.magazine-post-wrap {
    width: 43% !important;