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
top
2. Installing plugin link
- Extract the plugin into wordpress/wp-content/plugins folder on your server.
- In admin panel go to Plugins, locate Ether Forms 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. 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
4. Creating New Form link
Create a new form by going to Forms > New Form
top
4.1. Adding Form Elements link
When creating new form click Add Widget > Select Form Element > Configuration window will appear and the element will be automatically added to the document.
top
4.2. Filtering Form Elements link
You can filter widgets in the top right corner of the modal box that appears after clicking add widget button
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_form_widget. Open your functions.php and define a new class:
//wrap everything inside a conditional to prevent any errors when Ether Forms Builder plugin is deactivated
if ( class_exists('ether_form_widget') )
{
class my_form_widget extends ether_form_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.
NOTE: IF your form widget is meant to be some sort of a form field THEN its ID must start with "form-". Othewise the field won't be included in the Form Entry preview.
class my_form_widget extends ether_form_widget
{
public function __construct()
{
// call ether_form_widget constructor
parent::__construct('my-unique-id', 'My widget title'); //NOTE: IF your form widget is meant to be some sort of a form field THEN its ID must start with "form-". Othewise the field won't be included in the Form Entry preview.
// you can also add short description by chaning $label property
$this->label = 'This is my own widget.';
}
}
ether_form_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_form_widget extends ether_form_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_form_widget extends ether_form_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_form::register_widget('your_widget_class_name');
In the case of this example you would use:
ether_form::register_widget('my_form_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 Forms Builder plugin is deactivated
if ( class_exists('ether_form_widget') )
{
class my_form_widget extends ether_form_widget
{
public function __construct()
{
// call ether_form_widget constructor
parent::__construct('my-unique-id', 'My widget title'); //NOTE: IF your form widget is meant to be some sort of a form field THEN its ID must start with "form-". Othewise the field won't be included in the Form Entry preview.
// 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
'title' => ''
)), $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
// our widget will wrap title in <h2> tag
return '<h2>'.$widget['title'].'</h2>';
}
}
ether_form::register_widget('my_form_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 Forms 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 Forms 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 - Conditionals tab link
Each form widget can be made dependent on conditional fields and so can your custom widgets. All you need to do to make that happen is through the input of the following code snippet into your widget.
This goes inside the form method of your custom widget.
$context->form_conditional($widget)
top
5.2.4. Common widget options - Errors tab link
You can define custom error messages for your custom form widget.
This goes inside the form method of your custom widget.
$context->form_errors($widget)
top
5.2.5. Common widget options - Misc tab link
Other general widget options common to many default Forms 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.6. 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.7. 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 Forms Builder widgets.
For field construction examples check out the Form Fields Basics section.
top
top
6. Viewing Created Forms link
Created Forms can be accessed via Forms > Forms. You can preview some useful information about all forms you created there, such as form shortcode for use on a page, link to form entries submitted by users as well as download link that will export form entries to CSV format.
top
7. Viewing Form Entries link
Form Entries can be viewed directly under Forms > Entries.
top
8. Exporting / Downloading Form Entries in CSV format link
Form entries can be downloaded in Forms > Entries.
top
9. Local Form Options link
9.1. General link
9.1.1. Form Style link
- Default: Defaults to full width block fields
- Inline: Forces all form elements to take as little space as possible. Useful for Simple forms such as newsletter signup forms where you want fields and submit button to line up in a single line
- Short Fields: Form Fields will take up as little space as possible but won't collapse into a single line
- Full Width: Causes form fields to expand to fill 100% available width
top
9.1.2. Form Description link
Form description appears above the form on a page.
top
9.1.3. Email Notification link
Email address for email notification (comma separated): Will send notification email to specified email addresses.
top
9.1.4. Email Address For Sent Entries link
Email address for sent entries (comma separated): Specify an email address form entries will be sent from.
top
9.2. Confirmation link
Define what happens after the form has been successfully submitted. You can choose to specify a custom thank you message or redirect url.
top
9.3. Button Style link
Customize submit button style. Attributes that can be changed include button text, predefined style (small, medium or big button), alignment, background and text color as well as additional css classes for adding custom css styles.
top
9.3.1. Additional Classes link
Define comma separated custom classes here eg 'my-custom-class, and-another-one'. Extra button styles can be applied via them by adding some css rules eg. .my-custom-class { border: 1px solid red; } will add a red border around a button.
top
9.4. Shortcode link
Displays form shortcode. Use this shortcode to insert form to a page.
top
10. Inserting Form on a page link
Forms can be inserted on a page via the following shortcode where 66 is a value that should be replaced with a specific form id. Form ID can be previewed either when creating a form in Options > Shortcode metabox or on Forms > Forms listing page.
top
10.1. Inserting Form on a Page via Ether Content Builder link
If you have Ether Content Builder installed you can select Ether Forms widget and select a form you'd like to use on your page from a dropdown menu.
top
10.2. Creating Popup / Lightbox Form link
Any form created with Ether Forms can be displayed in a popup that appears after clicking a link. In order to do so specify a popup title inside a shortcode like this:
[form id="66" popup title="click to open form inside a popup / lightbox window"]
top
11. Global Form Options link
Global form options can be accessed in Ether > Forms section
top
11.1. Choosing Form Theme Style link
Ether Forms come in two predefined Light and Dark styles that can be defined in Ether > Forms > Styles > Color Scheme.
top
11.2. ReCaptcha Private / Public Key link
Location: Ether > Forms > ReCaptcha. Enter your keys there if you want to use ReCaptcha widget in your forms. In order to obtain the keys follow the instructions on recaptcha website.
top
11.3. Adding Custom CSS Styles link
Custom CSS styles for Ether Forms can be added in Ether > Forms > Custom Styles > Custom CSS.
top
12. FAQ link
12.1. Q: Error: "The package could not be installed. No valid plugins were found" link
A: Please repack the files you downloaded from CodeCanyon so that there’s only 'ether-forms' 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-forms 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
12.2. Q: Error: "DEP TEST FAILED" link
A: 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
12.3. Q: 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
12.4. Q: 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
12.5. Q: 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
12.6. How to remove ether entry from admin bar link
Go to Ether > Ether and select 'Hide "Ether" entry from the Admin Toolbar'.
top
12.7. 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'.
