Docs

1. Server requirements link

1.1. Minimum link

PHP 5.2.3+
MySQL 4.1.2+
WordPress 3.1+

top

1.2. Optional link

GD library - used for automatic image scaling and croping
Curl library or allow_url_fopen option set to "On" - used for downloading external feeds, e.g. latest tweets

top

2. Installing plugin link

Extract your Ether plugin into wordpress/wp-content/plugins folder on your server.
In admin panel go to Plugins, locate Ether Builder Plugin and activate.
Upon activation Content Builder tab will appear while in Post/Page editing mode next to Visual and HTML tabs.

top

3. qTranslate compatibility notes link

Ether Builder is compatible with multilingual sites that use qTranslate plugin. Support is a bit crude at the moment but it should suffice to some extent. Visual interface will be provides a little bit farther into the development. Here's how to use it:

Whenever you fill inputs/textareas with multilingual content you need to wrap content into proper tags like in example below:

<!--:en-->english text<!--:--><!--:zh-->chinese text<!--:-->

Note: Default shortcode notation of qTranslate - [:en]english text[:zh]chinese text - is not recommended as it will break content output.

top

4. Localization link

Localization files are locatated in ether-builder/locale directory. In order to translate the plugin please copy these files and save them as ether-lang_LANG eg. ether-pl_PL for polish translation. Full translating guide is available at http://codex.wordpress.org/Translating_WordPress

top

5. Customization link

5.1. Add custom widget link

To create your own widget you have to extend basic widget class, which is ether_builder_widget. Open your functions.php and define a new class:

//wrap everything inside a conditional to prevent any errors when Ether Builder plugin is deactivated
if ( class_exists('ether_builder_widget') )
{
	class my_widget extends ether_builder_widget
	{

	}
}

Next step is __construct() method. You have to call parent constructor from your widget __construct() method and provide widget with unique id and widget title.

class my_widget extends ether_builder_widget
{
	public function __construct()
	{
		// call ether_builder_widget constructor
		parent::__construct('my-unique-id', 'My widget title');

		// you can also add short description by chaning $label property
		$this->label = 'This is my own widget.';
	}
}

ether_builder_widget class contains form() and widget() methods. form() method defines your widget options form and widget() method provides output for you website. They both have a common $widget first argument which contains widget fields data.

form method:

class my_widget extends ether_builder_widget
{
	...

	public function form($widget)
	{
		// $widget holds all data bound to this instance of widget, in this case its only title field

		// make sure you generate your input names using get_field_name() method
		// thanks to get_field_name() method builder will catch data bound to this field and save it automatically
		return '<label>Title <input name="'.$this->get_field_name('title').'" value="'.$widget['title'].'" />';
	}
}

widget method:

class my_widget extends ether_builder_widget
{
	...

	public function widget($widget)
	{
		// $widget holds all data bound to this instance of widget, in this case its only title field
		//NOTE: Whenever you add an option to your widget please make sure to fill in its default value.
		$widget = ether::extend( array_merge(array
		(
			//define default values of your custom widget here
			'title' => ''
		)), $widget);

		// our widget will wrap title in <h2> tag
		return '<h2>'.$widget['title'].'</h2>';
	}
}

Each custom widget must be then registered using the following method:

ether_builder::register_widget('your_widget_class_name');

In the case of this example you would use:

ether_builder::register_widget('my_widget');

Thats all! If you have questions, please email us. Whole code down below:

//wrap everything inside a conditional to prevent any errors when Ether Builder plugin is deactivated
if ( class_exists('ether_builder_widget') )
{
	class my_widget extends ether_builder_widget
	{
		public function __construct()
		{
			// call ether_builder_widget constructor
			parent::__construct('my-unique-id', 'My widget title');

			// you can also add short description by chaning $label property
			$this->label = 'This is my own widget.';
		}

		public function form($widget)
		{
			// $widget holds all data bound to this instance of widget, in this case its only title field
			//NOTE: Whenever you add an option to your widget please make sure to fill in its default value.
			$widget = ether::extend( array_merge(array
			(
				//define default values of your custom widget here
			)), $widget);

			// make sure you generate your input names using get_field_name() method
			// thanks to get_field_name() method builder will catch data bound to this field and save it automatically
			return '<label>Title <input name="'.$this->get_field_name('title').'" value="'.$widget['title'].'" />';
		}

		public function widget($widget)
		{
			// $widget holds all data bound to this instance of widget, in this case its only title field
			//NOTE: Whenever you add an option to your widget please make sure to fill in its default value.
			$widget = ether::extend( array_merge(array
			(
				//define default values of your custom widget here
				'title' => ''
			)), $widget);

			// our widget will wrap title in <h2> tag
			return '<h2>'.$widget['title'].'</h2>';
		}
	}

	ether_builder::register_widget('my_widget');
}

top

5.2. Useful methods for creating admin elements of custom widgets link

If you want the content of your custom widget to be formatted uniformly with other Ether Builder Widgets you will need to follow a few simple patterns.

5.2.1. Tabbed Content link

Tabbed content can be achieved by wrapping your resulting widget code in the following HTML structure

<fieldset class="ether-form">
	<h2 class="ether-tab-title">'.ether::langr('General').'</h2>
	<div class="ether-tab-content">
		Put your general widget settings here
	</div>
	<h2 class="ether-tab-title">'.ether::langr('Misc').'</h2>
	<div class="ether-tab-content">
		Put your misc widget settings here
	</div>
</fieldset>

top

5.2.2. Common widget options - General tab link

Most of the Builder Widgets have some common options available in the General section. They include Widget alignment, width, left/right clearfix and such. In order to have them appear and work in your widget, insert the following snippet, preferably in the beginning of the section.

This should go in the form method of your custom widget class.

<h2 class="ether-tab-title">'.ether::langr('General').'</h2>
<div class="ether-tab-content">
	'.$this->form_widget_general($widget).'
	'.$this->form_widget_clearfloat($widget).'
	rest of the general options specific to your widget will go here		
</div>

Update the widget method of your custom widget class with the following changes to the $widget object.

//extend your $widget properties like so
$widget = ether::extend( array_merge(array
(
	//define default values of your custom widget here
),
$this->get_defaults(
	'widget_pos_align', //this relates to form_widget_general method
	'widget_clearfloat' //this relates to form_widget_clearfloat method
)), $widget);

NOTE: Whenever you add an option to your widget please make sure to fill in its default value in the widget method of your widget class.

top

5.2.3. Common widget options - Misc tab link

Other general widget options common to many default Builder widgets are grouped in the Misc section. They include widget visibility, additional classes, custom widget label and such. In order to have them appear and work in your widget, insert the following snippet, preferably in the beginning of the section.

Note: Column layout proposed below is not necessary and optional.

<h2 class="ether-tab-title">'.ether::langr('Misc').'</h2>
<div class="ether-tab-content">
	'.$this->form_widget_visibility($widget).'
	<div class="cols cols-1">
		<div class="col">
			<label><span class="label-title">'.ether::langr('Additional classes').'</span> '.$this->field('text', 'classes', $widget).'</label>
		</div>
	</div>
	<div class="cols cols-1">
		<div class="col">
			<label><span class="label-title">'.ether::langr('Widget label').'</span> '.$this->field('text', 'admin-label', $widget).'<small>'.ether::langr('Custom widget label which will be shown instead of widget name in the admin view').'</small></label>
		</div>
	</div>
</div>

These default widget options do not require any $widget object manipulation as it happens in case of the General section

top

5.2.4. Form Fields Basics link

NOTE: Whenever you add an option to your widget please make sure to fill in its default value in the widget method of your widget class.

This section outlines how to build form elements such as input, textarea and select. For a compound process of combining these fields with field labels and descriptions jump to the Form Fields Extended section.

There are premade patterns in place for generating form fields based on some data. All of the below code goes into form method of your custom widget class

top

Text input

$this->field('text', 'title', $widget)

//when executed, the line above will generate generate text input named 'title' similar to this:
<input name="ether_builder_widget[__LOCATION__][__ROW__][__COLUMN__][__ID__][title]" type="text" value="" />

top

Checkbox input

$this->field('checkbox', 'check_me', $widget)

//when executed, the line above will generate checkbox input named 'check_me' similar to this:
 <input name="ether_builder_widget[__LOCATION__][__ROW__][__COLUMN__][__ID__][check_me]" type="checkbox" />

top

Select input

//this will be passed as an option property of the fourth argument to the field method 
$aligns = array
(
	'' => ether::langr('Default'),
	'left' => ether::langr('Left'),
	'right' => ether::langr('Right'),
	'center' => ether::langr('Center')
);
//take note of fourth argument. It can be used for passing additional data to the field generator function. In this case we specify the options that will appear in the Select Box
$this->field('select', 'align', $widget, array('options' => $aligns))

//when executed, the line above will generate select box named 'align' similar to this:
<select name="ether_builder_widget[__LOCATION__][__ROW__][__COLUMN__][__ID__][align]" value="">
	<option value="" selected="selected">Default</option>
	<option value="left">Left</option>
	<option value="right">Right</option>
	<option value="center">Center</option>
</select>

top

Textarea

$this->field('textarea', 'description', $widget)

//when executed, the line above will generate generate textarea field input named 'description' similar to this:
<textarea name="ether_builder_widget[__LOCATION__][__ROW__][__COLUMN__][__ID__][description]" rows="3" cols="10" "></textarea>

top

5.2.5. Form Fields Extended link

This section outlines how to construct form fields combined with labels and descriptions so that they blend seamlessly with default Ether Builder widgets.

For field construction examples check out the Form Fields Basics section.


$output = '
<label>
	<span class="label-title">'.ether::langr('Widget Title').'</span>'
	.$this->field('text', 'title', $widget)
	.'<small>'.ether::langr('Field description goes here').'</small>
</label>';

top

5.3. Enable 3rd party / external /sidebar widgets link

You can use 3rd party widgets within Ether Content Builder upon going to Ether > Builder and checking the "Enable widgets from sidebars/external plugins in the Ether Builder" checkbox under general section.

Note: This option is turned off by default as we were getting many instability reports from people who had numerous plugins installed. This happens when a specific plugin is not complying with Wordpress Codex guidelines for plugin development, usually there's nothing we can do but to forward the issue to the author of the plugin in question. Inevitably it's Ether Builder that's considered faulty by the clients though.

top

5.4. Modify widgets output link

For this you will use ether_builder_widget filter. It accepts four parameters:

$output - html output from specific widget
$id - unique id of widget
$data - array of parameters passed to widget data
$slug - widget slug (e.g. plain-text, gallery etc.)

add_filter('ether_builder_widget', 'all_builder_widgets', 1, 4);

function all_builder_widgets($output, $id, $data, $slug)
{
	// replace Hello with Howdy in each widget
	$output = str_replace('Hello', 'Howdy', $output);


	// remember to return modified output
	return $output;
}

top

5.5. Modify specific widget output link

Eeach widget has its own filter. Let's say we want to strip out all tags within 'plain text' widget:

add_filter('ether_builder_{WIDGET_SLUG}_widget', ...);

In this case our slug equals 'plain-text' so here we go:

add_filter('ether_builder_plain-text_widget', 'plain_text_widget', 1, 4);

function plain_text_widget($output, $id, $data, $slug)
{
	$output = strip_tags($output);

	return $output;
}

And the parameters are:

$output - html output from specific widget
$id - unique id of widget
$data - array of parameters passed to widget data
$slug - widget slug (e.g. plain-text, gallery etc.)

top

5.6. Manage list of available widgets directly from the source link

Say we want to remove rich text widget from the list of available widgets:


add_filter('ether_builder_widgets', 'my_builder_widgets_list');

function my_builder_widgets_list($registered_widgets)
{
	foreach ($registered_widgets as $index => $widget_class)
	{
		if ($widget_class == 'ether_rich_text_widget')
		{
			unset($registered_widgets[$index]);
		}
	}

	return $registered_widgets;
}

top

5.7. Ether Builder and Custom Loop link

For Ether Builder to work within custom loops two conditions need to be met. Firstly WordPress loop guidelines must be followed - http://codex.wordpress.org/The_Loop. Secondly special Ether Builder template tags must be used. You should also boast a mighty knowledge of the following:

Template Tags
the_content() and get_the_content()

Ether Builder comes with template tags equivalents. These are:

ether_builder::the_content()
ether_builder::get_the_content()

Each time you want to use Ether Builder generated content and display it in a non-standard way with a loop the above tags must be used. Prey on the example below and then go ahead and conquer:

query_posts('YOUR CUSTOM LOOP ARGS HERE');

while (have_posts()):
	the_post();
	ether_builder::the_content();
endwhile;

top

5.8. Replace default lightbox with a custom one link

First you need to disable default lightbox. You do that in functions.php file

function disable_colorbox() {
	ether::config(‘builder_lightbox’, FALSE );
}

Now you need to add a following line to a js file:

$(”.ether-widget a[rel^=’lightbox’]”).custom_lightbox_init_function();

custom_lightbox_init_function() is your lightbox gallery of choice.

top

6. General Ether Content Builder options link

6.1. Show Ether Content Builder tab by default link

Select Ether > Builder > Show Builder Tab By default. This will show Ether Content Builder tab rather than Visual or HTML by default.

top

6.2. Hide Visual or HTML tab link

Select Ether > Builder > Hide "Visual" tab or Hide "HTML" tab to hide Visual / HTML tabs when editing pages.

top

6.3. Hide Builder content on archive/listing pages link

Select Ether > Builder > Hide Builder content on archive/listing pages.

top

6.4. Enable Revision Support for Builder content link

Select Ether > Builder > Enable revision support for Builder content. NOTE: This feature is beta

top

6.5. Change Builder content theme link

Select one of the available styles in Ether > Builder > Color scheme.

top

6.6. Disable Ether Content Builder for specific post types link

Select what post types you want Ether Content Builder to be hidden for in Ether > Builder > Post Types section.

top

Select widgets you want / don't want to show up in Builder modal window (the one that appears after clicking 'add widget' button) in Ether > Builder > Widgets section.

top

7. Common Widget Options link

7.1. Adding Global CSS link

There's an Ether > Builder > Custom CSS field that's perfect for the job. Just insert any custom styles there and they will get applied on any page where content generated with Ether Builder exists

top

7.2. Customize default CSS styles link

Note: This process requires at least basic understanding of how CSS is applied to a page. Basic knowledge of browser element inspector will be helpful as well.

To permanently overwrite some default Ether Widgets styles:

Locate all the rules of a widget in question (stylesheets are located in ether-builder/media/stylesheets - doesn't really matter if you choose light or dark as a pattern). Rules are groupped on per widget basis so that you can easily tell the rules for different widgets apart. For example divider widget rules may look like this:

a.ether-divider { position: relative; display: block; margin: 25px 0; height: 1px;}
a.ether-divider hr { margin: 0; }
a.ether-divider .ether-back-to-top { position: absolute;  top: -.5em; background-color: #ffffff; font-size: .8em; line-height: 1em; padding: 0 5px; margin-bottom: -.5em; display: inline-block;}

a.ether-divider.ether-title-alignright .ether-back-to-top { right: 0; padding-right: 0; }
a.ether-divider.ether-title-alignleft .ether-back-to-top { left: 0; padding-left: 0; }
a.ether-divider.ether-title-aligncenter { text-align: center; }
a.ether-divider.ether-title-aligncenter .ether-back-to-top {   position: relative; top: -14px; margin-bottom: -1em;}

hr.ether-divider.ether-style-1 {  background: none;  border: none;  border-top: 1px solid  #c1c1c1; }
hr.ether-divider.ether-style-2 {  background: none;  border: none;  border-top: 1px dotted #c1c1c1; }

.ether-clear { clear: both; }

Alter the rules as you wish and paste them into Ether > Builder > Custom CSS. You don't need them all, only these that change. Less is better. Note: Don't make changes to the stylesheet file directly as this will result in them being overwritten after plugin update!

top

7.3. Adding CSS on single page link

For that CSS Style widget is best used. It accepts any css syntax as it's content.

top

7.4. Additional Classes link

Additional classes can be defined in Misc section of widget settings.

Define extra classes that will be applied to a current widget. For example if you add 'my-custom-class' and define the following css rule in a stylesheet you will have custom styles applied to elements that have that extra class:

.my-custom-class {
	border: 1px solid red;
	font-size: 2em;
}

At times some rules defined within such selector may not work due to default styles superseding them. In order to counteract this behaviour you can prepend your custom class declaration with .ether-widget like this:

.ether-widget.my-custom-class {
	border: 1px solid red;
	font-size: 2em;
}

To further increase weight of custom defined rules you can append !important marker to properties declarations:

.ether-widget.my-custom-class {
	border: 1px solid red !important;
	font-size: 2em !important;
}

top

7.5. Adding custom widget label link

For every widget you add to a page, there's an option inside a 'misc' tab called 'widget label' that allows for custom label titles to be assigned to these (widgets). If you set this it will overwrite automatic description that may be sometimes less descriptive. For example if the description of an image by default is Image - /path/to/image by providing a label you can control it so that it appears as Image - image description.

top

8. Templates link

8.1. What are Ether Builder templates and where to manage them link

Any page built with Ether Builder can be a template. Such pages / templates can then be used repeatedly and speed up page building process for pages that use similar structure.

top

8.2. Adding Template link

Add a new page, add some widgets to it and choose template > save in builder metabox in the top right.

top

8.3. Loading / Using Template link

Add a new page and choose template > load from builder metabox in the top right. Content area will then get populated with template content ready to edit.

top

8.4. Adding template content via Template Widget link

Some content bits such as author bio or other general purpouse information that appear on many pages in the same form can be easily added and managed by creating a template first (see above) and then adding it via Template Widget from Ether Builder Modal (rather than applying template to a whole page).

top

9. FAQ link

9.1. Error: "The package could not be installed. No valid plugins were found" link

Please repack the files you downloaded from CodeCanyon so that there’s only 'ether-builder' root directory inside the archive. You can follow this step by step process:

Unpack the downloaded archive somewhere on your computer
Create a new archive that consists of ether-builder directory only

Alternatively to that you can remove other directiories directly from the downloaded package.

Yet another solution is to:

Copy ether-builder directory to your WordPress plugins directory (located at wp-content/plugins/)
And then activating the plugin in WordPress admin panel in Plugins section (Find Ether Content Builder position in a table and click activate)

top

9.2. Error: "DEP TEST FAILED" link

It means your server does not comply with minimum/optimal plugin requirements. Below there's a list of possible errors and missing libraries that will need to be installed in order to get rid of the issue:

imagecreatetruecolor, imagecolorallocatealpha, imagecolortransparent - lib gd - required for automatic images thumbnail generation
curl_init - curl_init - curl library is required for download of feeds from external services such as Twitter, Flickr, etc.
zipArchive - zipArchive - Handles .zip files. Required for manual updates conducted via Ether > Update and migration of backups if Ether Backup is used
allow_url_f_open - curl_init - An error pops up if a value of the property is set to false. Changing allow_url_f_open = true will get rid of that. This dependency is not mandatory as long as you have curl library installed on your server.

top

9.3. Allowed memory size of * bytes exhausted... link

You need to increase WordPress memory limit. Follow the guidelines over here - http://codex.wordpress.org/Editing_wp-config.php#Increasing_memory_allocated_to_PHP

top

9.4. External plugin appears broken when used within Ether Builder link

Ether Builder automatically attempts to make all available wordpress widgets compatible with it. Whether the process turns out fine for a specific widget depends heavily on coding practices used during its creation. If a specific plugin seems broken please contact its author and ask him to try to make it compatible with Ether Builder on his end.

top

9.5. How do I update to the latest version? link

You can do so at any time in Ether > Update section. Keep in mind a valid license key is required for updates to take place. Your license key is the same as your Item Purchase Code you get when you buy an item on Envato marketplace

top

9.6. Where do I get a License Key? link

It’s the same as your Item Purchase Code you get in an email after you buy an item on in your Downloads > License Certificate section of a specific item

top

9.7. How to remove ether entry from admin bar link

Go to Ether > Ether and select 'Hide "Ether" entry from the Admin Toolbar'.

top

9.8. How to remove ether board section from dashboard widgets link

Go to Ether > Ether and select 'Hide "Ether Board" widget from the Admin Dashboard Widgets'.

top

9.9. Yoast SEO issues (not picking up the content from builder) link

Yoast SEO (WordPress SEO) does not apply the_content filter on post content before extracting data such as metatags from it rendering ether builder content not visible. Filters allow to modify and add new content to different data types (in this case post content) and not applying the_content filter is a bad practice. We can't do anything about that beyond contacting Yoast SEO plugin author which we did. As for today it yielded no response from him unfortunately ;(

top

9.10. Will I lose my content after I deactivate the plugin? link

Nope. Ether data is stored in WordPress database and stays there even after plugin deactivation/removal.

EtherBuilder