Builder Documentation

From iThemes Codex
Revision as of 17:13, 26 May 2011 by Sridhar (talk | contribs) (How to upgrade Builder)
Jump to: navigation, search

Builder Basics Videos

It is highly recommended that anyone new to iThemes Builder watch recording of the online workshop (webinar) done through training division by Benjamin Bradley.

Please click on the link below:

iThemes Builder Basics Webinar

How to install Builder

  1. Download the latest Builder zip file from the member panel.
  2. Log into your WordPress admin area, go to Appearance -> Themes. Click on Install Themes, then on Upload. Browse to the folder where you have downloaded, select it and click Install Now. There is no need to activate Builder.
  3. While it is not compulsory, it is highly recommended to use a child theme of Builder as the active theme and not Builder directly. The idea behind this is to protect theme customizations from being erased during Builder upgrades.
    1. Download Builder Child Theme - Default from the members area.
    2. Note: If you would like to start with one of the pre-designed child themes as your theme, download and use the corresponding theme from the member panel. The Child Themes page lists all the Builder child themes that are available.
  4. Go to Appearance -> Themes. Click on Install Themes, then on Upload. Browse to the folder where you have downloaded (or whichever child theme you have chosen), select it and click Install Now.
  5. Activate your child theme.

The rest of this documentation assumes that Builder Child Theme - Default is being used.

Screenshot showing a child theme of Builder set as active theme - Click to enlarge

Now your Builder is set up in such a way that changes to the theme can be made without worrying about upgrades overwriting changed files.

If you are new to WordPress, My Theme -> Start Here is a good starting point. It links to several useful video tutorials.


  1. Ensure that there are no spaces in the name of your child theme's directory. For example, BuilderChild-Default is fine, but not Builder Child - Default
  2. Contents of the theme must be directly inside the theme's directory and not nested i.e., inside another directory. This applies both to Builder and Builder's child theme.

How to upgrade Builder


  1. Make sure that you have first upgraded any Builder-related plugins such as Style Manager and Builder SEO to their latest versions before attempting to upgrade Builder.
  2. Before you attempt to upgrade Builder, ensure that you are not using it as your site's active theme. Otherwise, customizations and changes you might have done to Builder files will be lost during upgrade. You must always use a child theme of Builder as your site's active theme.


The easiest way to upgrade Builder and any WordPress plugin is by using Easy Theme and Plugin Upgrades plugin. You do not need to manually delete your current version before uploading the most current version.

Here are the steps:

  1. Download and install the Easy Theme and Plugin Upgrades plugin.
  2. Go to Appearance -> Add New Themes. Click on Upload.
  3. Browse to and locate the zip file of the latest Builder that you downloaded from the member panel. Change the Upgrade existing theme? setting to Yes and click Install Now button.
  4. Once the theme has been successfully installed, return to themes page. Do not activate Builder as you should always be using a child theme of Builder as your active theme and not Builder directly.

Note: You might NOT want to upgrade child theme of Builder. If you do so, keep in mind that changes that you have made to it, if any, will be lost.

My Theme -> Settings

Go to My Theme -> Settings.

Menu Builder: There are two types of horizontal navigation bars that can be shown on your site. One is Pages navigation and the other is Categories Navigation. In this Menu Builder section you can select the pages and categories that should appear as menu items in the corresponding navigation bars.

Note: The pages selected in this section will be used only if Builder Settings Pages is selected in the settings of Navigation module of the layout. This is the default setting.

Social Media Tabs: This section is theme specific and as of today appears only if you use Astro child theme. You can fill in the URLs to profiles of your social media sites like Twitter and Facebook. These appear as icons in the right side of the site.

Screenshot showing how social media buttons appear on the site

Identify Widget Areas: Leave this setting to Yes. Once your entire site is set up, you may want to come back to this and set it to No.

Tracking Code: If you use Google Analytics or any other similar service, certain tracking code will be provided by those services which should be put in your site's footer. You can paste that code in this field.

Search Engine Optimization: Even though it is specified as recommended for Would You like to use post tags as META keywords on single posts?, it is suggested for now that you set this to No and instead use a SEO plugin like All in one SEO plugin. It gives a better control of SEO not only at the site level but also at individual posts and pages level.

You might want to leave the setting, Would you like your category archives to be indexed by search engines? to the default No.

Click on Save Options button.

My Theme -> Layouts

Go to My Theme -> Layouts to access the Layout Manager.

A layout is an arrangement of modules. Think of modules as building blocks for the layout. Builder comes with 4 layouts by default. You can create any number of layouts and apply layouts to individual pages, individual posts, front page, blog page, archives view, tag view etc.

You may want to follow these steps:

  1. Pick a layout that's closest to how you want your site to be and create its duplicate.
    • 960 Home is typically what you would want to start off with. Place the mouse cursor on 960 Home and the link to Duplicate it will be visible. Click on it, provide a new name (say, Main Layout) and click Create Layout.
  2. Set your new layout as the default. Place the mouse cursor next to the new layout you just created under the Default Layout column and Set as default link will appear. Click on it.
  3. Hide widget areas of all the layouts except the default layout (since it is the layout you are going to work with, it makes sense to just see the widget areas for this layout when you go to Appearance -> Widgets).


Click on the newly created layout to arrange and configure the modules that make up this layout.

These are the different types of modules:

Visit your site in a new tab/window to see how the modules of your layout are displayed. You might be wondering as to why the Categories navigation module is not appearing. It is actually visible but it does not contain any menu items as no category is checked in the Menu Builder section at My Theme -> Settings.

Navigation Module

Screenshot of pages and categories navigation bar modules - Click to expand

A Navigation bar module can be one of these four types:

  • Builder Settings Pages
  • Builder Settings Categories
  • WordPress Pages
  • Custom Menu

Builder Settings Pages

This module shows the page titles as menu items. Only those page titles will be shown in the navigation bar that have been ticked in the Menu Builder section at My Theme -> Settings. Child pages are displayed as sub menus. The default menu item in this type of navigation module is Home that links to your site's front page.

The order of pages in the menu can be changed by setting page Order for the pages (either in the page editor screen or at Pages -> Edit -> Quick Edit). A page with lower order number will be shown first (left) compared to a page with higher order.

Builder Settings Categories

This module shows the category titles as menu items. Only those category titles will be shown in the navigation bar that have been ticked in the Menu Builder section at My Theme -> Settings. Child categories are displayed as sub menus.

The order of categories in the menu can be changed by using Category Order plugin.

WordPress Pages

This module uses the output of wp_list_pages function. Child pages are displayed as sub menus.

The order of pages in the menu can be changed by setting page Order for the pages (either in the page editor screen or at Pages -> Edit -> Quick Edit). A page with lower order number will be shown first (left) compared to a page with higher order.

Custom Menu

This module uses custom menu that is created at Appearance -> Menus.

Image Module

Image module is typically used to display header images. In the module's settings, we can upload an image, set its height (default is 150px), specify Link URL and whether or not the linked URL should open in a new window (default is to open in the same window). We can also specify any of these for sidebars:

  • No Sidebars (default)
  • 1 Left
  • 2 Left
  • 1 Right
  • 2 Right
  • Split (1 Left & 1 Right)
Screenshot of an image uploaded via image module - Click to expand


  1. To avoid resizing of the image after upload, ensure that width of image is exactly equal to Layout width minus the total width of sidebar(s) (if any). Also ensure that the height of the image is the same as the height value specified in the module's setting.
  2. If the uploaded image is not appearing on the site, make sure that uploads folder is set to wp-content/uploads at Settings -> Miscellaneous. If the issue continues, ensure that GD image library is present in your hosting environment.

Tip: A HTML module or widget bar module will give you better control if you want to use a sidebar.

Widget Bar Module

HTML Module

Content Module

Footer Module

Apply Layouts to Specific Views

The power of Builder (layouts) can selectively be applied to specific sections of your WordPress site called Views.

To apply layouts to specific views, go to layout manager (My Theme -> Layouts) and click on Configure Views button. Then click Add View button.


These are the available views:

  1. 404: This view represents (web)pages (controlled by 404.php) that come up when a non-existent (in your site) URL is accessed.
  2. Archives: This view represents pages (controlled by archive.php) that come up when a archive link is clicked.
  3. Attachment: This view represents pages (controlled by attachment.php) that come up when any attachment (files like images that can be seen in WordPress Media Library ) is viewed.
  4. Author: This view represents pages that come up when link to a author is clicked.
  5. Blog: This option appears only when a Page has been set as Posts page at Settings -> Reading i.e., when a static page is set to appear on Front page. This view represents the Posts page (Example: /blog or /news) which uses index.php (unless an extension is used in which case, extension's functions.php will be used)
  6. Category: When this view is selected, another dropdown named "Category" appears from which a category can be selected to which the layout should be applied. This view represents any page that lists posts belonging to a particular category. Category-view-expanded.png
  7. Date Archive: This view represents the date-based archives list pages (controlled by date.php).
  8. Home: This view represents the front page.
  9. Page: This view represents a Page.
  10. Post: This view represents a Post.
  11. Post Type - Widget Content: This view represents the page that lists "Widget Content" custom post types. Widget Content comes by default in Builder. Each custom post type (Ex.: Projects in Covell child theme) will automatically appear in the View selection dropdown.
  12. Search: This view represents the search results page (controlled by search.php)
  13. Singular: This view represents Any post, page, or attachment. Post, Page, Attachment views if present will take precedence over this.
  14. Tag: This view represents that page that comes up when a tag is clicked.

Applying Layouts to Specific posts/Pages

A layout can be applied to any post or Page while that post or Page is being added/edited.


Note: When Front page is set to display a static Page at Settings -> Reading, a layout applied to Home will not get applied. Same is the case with Posts page.

In this case, views must be used.

Differences between Views, Layouts and Extensions

Go to

CSS - Identifying the modules

Builder CSS Guide