Builder Documentation

(Difference between revisions)
Jump to: navigation, search
(Footer Module)
m (Apply Layouts to Specific Views)
(11 intermediate revisions by one user not shown)
Line 1: Line 1:
 +
== Getting started with Builder ==
 +
 +
This guide presents an introduction to basic Builder concepts and terms, as well as a beginner's overview on using Builder for the first time. We’ll walk step-by-step through installing and activating the Builder theme, as well as creating your first page Layout and View with Builder.
 +
 +
Click here -> [http://ithemes.com/publishing/getting-started-with-builder/ Getting Started with Builder]
 +
 +
Latest video version of this can be found at http://ithemes.tv/
 +
 
==Builder Basics Videos==
 
==Builder Basics Videos==
  
Line 12: Line 20:
 
# 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 ''Builder.zip'', select it and click ''Install Now''. There is no need to activate Builder.
 
# 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 ''Builder.zip'', select it and click ''Install Now''. There is no need to activate Builder.
 
# 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.
 
# 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.
## Download ''Builder Child Theme - Default'' from the members area.
+
## Download a child theme of your choice, say, ''Builder Child Theme - Default'' from the members area. In the steps below, "Builder Child Theme - Default" is merely used as an example. You are free to use any child theme (that appears in the Member Panel) of your choice.
 
## <u>Note</u>: 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 [[Builder Child Themes|Child Themes]] page lists all the Builder child themes that are available.
 
## <u>Note</u>: 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 [[Builder Child Themes|Child Themes]] page lists all the Builder child themes that are available.
 
# Go to Appearance -> Themes. Click on Install Themes, then on Upload. Browse to the folder where you have downloaded ''BuilderChild-Default.zip'' (or whichever child theme you have chosen), select it and click ''Install Now''.
 
# Go to Appearance -> Themes. Click on Install Themes, then on Upload. Browse to the folder where you have downloaded ''BuilderChild-Default.zip'' (or whichever child theme you have chosen), select it and click ''Install Now''.
Line 41: Line 49:
 
'''WARNING''':  
 
'''WARNING''':  
  
# '''Make sure that you have first upgraded any Builder-related plugins such as Style Manager, Builder SEO and Builder Blocks to their latest versions before attempting to upgrade Builder'''.
+
# '''Make sure that you have first upgraded any Builder-related plugins in use such as Style Manager, Builder SEO and Builder Blocks to their latest versions before attempting to upgrade Builder'''.
 
# Ensure that you are not using Builder (core/parent) 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.
 
# Ensure that you are not using Builder (core/parent) 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.
  
Line 50: Line 58:
 
Here are the steps:
 
Here are the steps:
  
# Download and install the [http://wordpress.org/extend/plugins/easy-theme-and-plugin-upgrades Easy Theme and Plugin Upgrades plugin]. If this plugin is already present, ensure that it is the latest version.
+
# Download, install and activate the [http://wordpress.org/extend/plugins/easy-theme-and-plugin-upgrades Easy Theme and Plugin Upgrades plugin]. If this plugin is already present, ensure that it is the latest version.
# Go to Appearance -> Add New Themes. Click on ''Upload''.
+
# Go to Appearance -> Themes. Click on ''Install Themes'', then ''Upload''.
# Browse to and locate the zip file of the latest Builder that you downloaded from the [http://ithemes.com/member/member.php member panel]. Change the '''Upgrade existing theme?''' setting to '''Yes''' and click ''Install Now'' button.
+
# Browse to and locate the zip file of the latest Builder that you downloaded from [http://ithemes.com/member/member.php member panel]. Change the '''Upgrade existing theme?''' setting to '''Yes''' and click ''Install Now'' button.
 
# 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.
 
# 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.
  
Line 75: Line 83:
  
 
# Pick a layout that's closest to how you want your site to be and create its duplicate.
 
# Pick a layout that's closest to how you want your site to be and create its duplicate.
#* ''Right Sidebar'' is typically what you would want to start off with. Place the mouse cursor on ''Right Sidebar'' and the link to Duplicate it will be visible. Click on it, provide a new name (say, ''Main Layout'') and click ''Create Layout''.
+
#* ''Right Sidebar'' is typically what you would want to start off with. Place the mouse cursor on ''Right Sidebar'' and the link to Duplicate it will be visible. Click on it, provide a new name (say, ''Main'') and click ''Create Layout''.
 
# 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.
 
# 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.
  
Now your 'Main Layout' layout is ready to be customized. Click on its name to edit the modules that make up this layout. Do not forget to save the layout when you are done editing it.   
+
Now your 'Main' layout is ready to be customized. Click on its name to edit the modules that make up this layout.  
 +
 
 +
[[File:Modules-in-a-layout.png|391px|thumb|none]]
 +
 
 +
Do not forget to save the layout when you are done editing it.   
  
 
These are the different types of modules:  
 
These are the different types of modules:  
Line 101: Line 113:
 
* Custom Menu
 
* Custom Menu
  
'''Builder Settings Pages'''
+
====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.
 
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.
Line 107: Line 119:
 
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.
 
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'''
+
====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.
 
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.
Line 113: Line 125:
 
The order of categories in the menu can be changed by using [http://wordpress.org/extend/plugins/order-categories/ Category Order plugin].
 
The order of categories in the menu can be changed by using [http://wordpress.org/extend/plugins/order-categories/ Category Order plugin].
  
'''WordPress Pages'''
+
====WordPress Pages====
  
 
This module uses the output of wp_list_pages function. Child pages are displayed as sub menus.
 
This module uses the output of wp_list_pages function. Child pages are displayed as sub menus.
Line 119: Line 131:
 
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.
 
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'''
+
====Custom Menu====
  
 
This module uses custom menu that is created at Appearance -> Menus.
 
This module uses custom menu that is created at Appearance -> Menus.
Line 131: Line 143:
 
===Image Module===
 
===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:
+
Image module is typically used to display header images.
 +
 
 +
In the module's settings, we can upload an image, let the height be automatic or set its height manually, 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)
 
* No Sidebars (default)
Line 140: Line 154:
 
* Split (1 Left & 1 Right)
 
* Split (1 Left & 1 Right)
  
[[File:image-module.png|none]]
+
[[File:Builder-image-module.png]]
  
 
[[File:image-module2.png|500px|thumb|none|Screenshot of an image uploaded via image module - Click to expand]]
 
[[File:image-module2.png|500px|thumb|none|Screenshot of an image uploaded via image module - Click to expand]]
Line 159: Line 173:
 
[[File:Content-module.png]]
 
[[File:Content-module.png]]
  
Content module can have 0, 1 left or 2 left or 1 right or 2 right or split (1 left & 1 right) sidebar(s).
+
Content module can have
 +
 
 +
* No Sidebars
 +
* 1 Left
 +
* 2 Left
 +
* 1 Right
 +
* 2 Right
 +
* Split (1 Left & 1 Right)
 +
 
 +
sidebar(s).
  
 
When entering custom width(s) for the sidebar(s) ensure that "px" is not present next to the value.
 
When entering custom width(s) for the sidebar(s) ensure that "px" is not present next to the value.
Line 169: Line 192:
 
[[File:Footer-module.png]]
 
[[File:Footer-module.png]]
  
Like other modules, footer module can have 0, 1 left or 2 left or 1 right or 2 right or split (1 left & 1 right) sidebar(s).
+
Like other modules, footer module can have
 +
 
 +
* No Sidebars (default)
 +
* 1 Left
 +
* 2 Left
 +
* 1 Right
 +
* 2 Right
 +
* Split (1 Left & 1 Right)
 +
 
 +
sidebar(s).
  
 
To learn how to edit the content of footer, follow [http://ithemes.com/codex/page/Builder_Frequently_Asked_Questions#How_do_I_edit_the_footer.3F this].
 
To learn how to edit the content of footer, follow [http://ithemes.com/codex/page/Builder_Frequently_Asked_Questions#How_do_I_edit_the_footer.3F this].
Line 177: Line 209:
 
The power of Builder (layouts) can selectively be applied to specific sections of your WordPress site called 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.
+
'''To apply layouts to specific views, go to Layout Editor (My Theme -> Layouts & Views) and click on ''Views'' tab. Then click ''Add View'' button.'''
  
 
[[File:AddViewDialog1.png]]
 
[[File:AddViewDialog1.png]]
Line 184: Line 216:
  
 
# '''404''': This view represents (web)pages (controlled by 404.php) that come up when a non-existent (in your site) URL is accessed.
 
# '''404''': This view represents (web)pages (controlled by 404.php) that come up when a non-existent (in your site) URL is accessed.
# '''Archives''': This view represents pages (controlled by archive.php) that come up when a archive link is clicked.
+
# '''Archives''': This view represents pages (controlled by archive.php) that come up when a archive link is clicked. Examples of archive pages (these are listing pages, i.e., having multiple posts rather than a single entry) are: Category pages, Author pages, Tag pages, Date archive pages.
 
# '''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.
 
# '''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.
 
# '''Author''': This view represents pages that come up when link to a author is clicked.
 
# '''Author''': This view represents pages that come up when link to a author is clicked.

Revision as of 22:15, August 25, 2012

Contents

Getting started with Builder

This guide presents an introduction to basic Builder concepts and terms, as well as a beginner's overview on using Builder for the first time. We’ll walk step-by-step through installing and activating the Builder theme, as well as creating your first page Layout and View with Builder.

Click here -> Getting Started with Builder

Latest video version of this can be found at http://ithemes.tv/

Builder Basics Videos

It is highly recommended that anyone new to iThemes Builder watch recording of the online workshop (webinar) done through WebDesign.com 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 Builder.zip, 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 a child theme of your choice, say, Builder Child Theme - Default from the members area. In the steps below, "Builder Child Theme - Default" is merely used as an example. You are free to use any child theme (that appears in the Member Panel) of your choice.
    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 BuilderChild-Default.zip (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.

Manage-themes.png

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.

NOTE

  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.

Go to My Theme -> Start Here and watch videos covering Builder overview, Layouts & Modules and Child themes.

How to upgrade Builder

It is highly recommended to take a full backup of your Builder powered site using BackupBuddy before upgrading.

WARNING:

  1. Make sure that you have first upgraded any Builder-related plugins in use such as Style Manager, Builder SEO and Builder Blocks to their latest versions before attempting to upgrade Builder.
  2. Ensure that you are not using Builder (core/parent) 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.

Steps

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, install and activate the Easy Theme and Plugin Upgrades plugin. If this plugin is already present, ensure that it is the latest version.
  2. Go to Appearance -> Themes. Click on Install Themes, then Upload.
  3. Browse to and locate the zip file of the latest Builder that you downloaded from 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.
Upgrade-builder.png

Note:

  1. Builder can also be upgraded by replacing the existing Builder directory with the one extracted from the latest zip file using a FTP client or cPanel file manager. The advantage of using Easy Theme and Plugin Upgrades plugin is that it takes a backup of whatever is being replaced.
  2. 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 -> Layouts and Views

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

Screenshot of default layouts in Builder:

Manage-layouts-and-views-default.png

A layout is an arrangement of modules. Think of modules as building blocks for the layout. Builder comes with 9 layouts by default. You can create any number of layouts from scratch or duplicate existing ones 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.
    • Right Sidebar is typically what you would want to start off with. Place the mouse cursor on Right Sidebar and the link to Duplicate it will be visible. Click on it, provide a new name (say, Main) 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.

Now your 'Main' layout is ready to be customized. Click on its name to edit the modules that make up this layout.

Modules-in-a-layout.png

Do not forget to save the layout when you are done editing it.

These are the different types of modules:

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, let the height be automatic or set its height manually, 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)

Builder-image-module.png

Screenshot of an image uploaded via image module - Click to expand

Note:

  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

The actual Page/Post etc. content will be shown inside the content module. Therefore, ensure that default layout in your site has the content module. A layout can and will have only 1 content module.

Content-module.png

Content module can have

  • No Sidebars
  • 1 Left
  • 2 Left
  • 1 Right
  • 2 Right
  • Split (1 Left & 1 Right)

sidebar(s).

When entering custom width(s) for the sidebar(s) ensure that "px" is not present next to the value.

Footer Module

A layout can and will only have 1 footer module.

Footer-module.png

Like other modules, footer module can have

  • No Sidebars (default)
  • 1 Left
  • 2 Left
  • 1 Right
  • 2 Right
  • Split (1 Left & 1 Right)

sidebar(s).

To learn how to edit the content of footer, follow this.

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 Editor (My Theme -> Layouts & Views) and click on Views tab. Then click Add View button.

AddViewDialog1.png

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. Examples of archive pages (these are listing pages, i.e., having multiple posts rather than a single entry) are: Category pages, Author pages, Tag pages, Date archive pages.
  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 a single entry of "Widget Content" custom post type. 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.

Selecting-a-layout.png

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 http://ithemes.com/forum/index.php?/topic/9024-differences-between-views-layouts-and-extensions/

CSS - Identifying the modules

Builder CSS Guide

Personal tools
Namespaces
Variants
Actions
iThemes Codex
Codex Navigation
Toolbox