Addons are encapsulated features that enhance or add new functionalities to the YOOtheme Pro builder. They are enabled by default, but if required can be individually disabled in the
Theme -> Settings -> ZOOlanders
panel.Builder Elements. Getting Started. The easiest way to get started is to try out the example element or take a look at the included YOOtheme Pro elements. JSON Configuration. Fix prefix custom CSS for elements - Fix grouped input field loosing focus upon first input - Child theme can override offline.php (Joomla) ### Removed - Remove redundant WooCommerce setting for WooCommerce 3.3 (WordPress) 1.11.5 (March 06, 2018) ### Fixed - Fix Pinewood-Lake navbar letter-spacing 1.11.4 (March 05, 2018) ### Added.
# Forms
![Elements Elements](/uploads/1/1/8/8/118813883/265026099.png)
Forms addon extends YOOtheme Pro builder with a form build and submission workflow, allowing for any
section
, column
, or row
to become a submittable Form Area. The form configuration is located for those elements in the Advanced Tab settings, under the Form field.An icon will be displayed in the Builder Element field giving you a hint about the form configuration. If there is any error the icon will turn red and indicate one of the possible configuration errors.
The most important form configuration is the Actions, those allow to further process the submitted data or simply show a message of a successful submission.
The form fields are represented by the Form Elements under the group ZOOlanders Form, and as long as they are inside the Form Area the inputted data will be picked up and processed.
Not all elements are meant for inputting data, the Form Fieldset element allows to group fields into a fieldset, while the Form Submit Button element allows the user to submit the form. Be sure to explore them all for composing the perfect form for your project.
At this point, the form should be successfully processing submissions! To further learn and deep into the subject please refer to the Forms In-Depth section.
# Access
Access addon extends YOOtheme Pro Builder elements with rendering conditions, located on each element Advanced Tab settings, under the Access -> Conditions panel.
Access conditions are composed of core and custom rules, when a rule is enabled it options will reveal, and the element rendering will be evaluated against the logic and configuration set by it.
An icon will be displayed in the Builder Element field giving you a hint about the access evaluation.
To further learn and deep into the subject please refer to the Access In-Depth section.
# Icons
Icons addon extends YOOtheme Pro Builder with core and custom icon collections like Font Awesome, Ionicons, and others. The icons are natively integrated and accessible in the icon picker Modal when requested from any icon field.
Each collection will be displayed on its own Tab with sub-tabs separating the groups. Being all GPL, MIT, or Creative Commons licensed, you can use them in personal as commercial projects.
Additionally, the modal is enhanced with a Search field that also extends the core UIkit icons making it possible to easily find an icon by it name.
To further learn and deep into the subject please refer to the Icons In-Depth section.
# Elements
A collection of elements available under the group ZOOlanders. Their integration with the Builder is as native, using the YOOtheme Pro elements settings and other conventions.
To further learn and deep into the subject please refer to the Elements In-Depth section.
Custom elements are the easiest way to extend the functionality of the YOOtheme Pro page builder. Copy an existing element and customize its markup and settings, or create a new element from scratch.
Custom elements can be added to the page builder by using a child-theme or a Joomla plugin. The easiest way to add an element is by using a child theme. This is typically used for client projects. A Joomla plugin should be used when developing a third-party extension for YOOtheme Pro. Take a look at the extensions page to see what is available from the developer community.
Getting Started
The easiest way to get started is to try out the example element or take a look at the included YOOtheme Pro elements. Once the element is added to the page builder, it will appear under
Custom
in the element library.Example Element
The example element on Github demonstrates how to configure an element, extend its functionality and make use of the different field types. Simply download and unzip the element. The quickest way to try it out is using a child-theme.
Included Elements
Included elements can be found in the respective module directory under
vendor/yootheme
in YOOtheme Pro.Directory | Elements |
---|---|
builder/elements | accordion, alert, button, code, column, countdown, description_list, divider, gallery, grid, headline, html, icon, image, layout, list, map, overlay, panel, popover, quotation, row, section, slider, slideshow, social, subnav, switcher, table, text, totop, video |
builder-newsletter/elements | newsletter |
builder-joomla/elements | breadcrumbs, module, module_position |
builder-wordpress/elements | breadcrumbs, module, module_position |
builder-joomla-source/elements | pagination |
builder-wordpress-source/elements | comments, pagination |
To create a new element by customizing an existing element, simply copy one of the included elements and give it a unique name in the
element.json
configuration.File Structure
An element has its own directory with configuration and template files.
File | Description |
---|---|
element.json | Define the element configuration, fields and settings. |
element.php | Extend the element functionality with custom transforms or update functions. This file is optional and has to be imported through the element.json . |
templates/template.php | Render the element layout. The rendering is often split into template partials prefixed with template- . |
templates/content.php | Render the element content without layout-specific markup. The content is saved in the Joomla page. It's used by the Joomla search and remains when discontinuing using YOOtheme Pro. |
images/icon.svg | The icon shown in the element library |
images/iconSmall.svg | The icon shown in the page builder |
JSON Configuration
The
element.json
defines the element's name, icons, fields and how the editing interface should look like inside the builder. Make sure to set a unique element name, for example my_element
, that is not taken by an existing element. The following example shows a simple element configuration without any fields.Property | Description |
---|---|
name | Name of the element. Must be unique. |
title | Label in the page builder |
icon | Path to the icon used in the element library |
iconSmall | Path to the icon used in the page builder |
element | Show element in the element library. |
width | Width of the customizer sidebar when editing the element |
templates | Paths to the two required template files |
Group Property
By default custom elements are grouped under
Custom
in the element library. To create a dedicated group for elements, set the group
property. This is recommended if elements are shared across different projects or when developing a third-party extension for YOOtheme Pro.Fields
Fields of an element can be defined in the
fields
object in the element.json
file. Just add a field name and its field definition. Additionally, set all fields in the default
fieldset
object to define their order and layout when editing the element in the page builder.Properties
Every field is defined by its
type
and further properties. The following properties are available for all field types.Property | Description |
---|---|
name | Name of the field. When not set, inferred from the object property key. |
type | Set the field input type. By default it's text which displays an input field. |
label | Display a field label above the field. |
description | Display a field description below the field. |
attrs | Add additional HTML attributes to the rendered field. |
show | Show field only if a specific condition is met. |
enable | Enable field only if a specific condition is met. |
In the following example an input field named Content is shown.
In the following example the style option can only be selected if the
content
field is filled out. The icon picker is only shown if the content
field is filled out and the style
is set to primary
.Tabs
Optionally, the
fieldset
object type
can be set to tabs
which defines different tabs in which the fields are shown. The following example has two tabs – Content and Settings. The Content tab includes the content field, and the Settings includes the two option fields.Default Values
Fields can be set to a default value when the element is added to the page builder. Simply set the field key to the default value in the
defaults
object in the element.json
file. In the following example the text field content
will be filled out with Some default value.
.Preview Placeholder
Fields can show a placeholder in the page builder preview while it has no content. Once the field is filled out, the placeholder disappears, and the field value is shown. Simply set the field key to the placeholder value in the
placeholder
object under props
in the element.json
file. In the following example the element will show a Lorem ipsum placeholder text as long as the content field is not filled out.Interpolation Syntax
YOOtheme Pro comes with powerful interpolation syntax to reference values and to call functions. These interpolations are embedded within strings and wrapped in
${}
, such as ${var.foo}
.For example, this is used for general element settings which are often the same across elements. Those fields are defined in the
vendor/yootheme/builder/config/builder.json
file. Their field definition can be referenced as ${builder.NAME}
. The following example sets the field name maxwidth
to the field definition defined in the builder.json
file.Here is the referenced field definition from the
builder.json
file.Another example is the advanced settings tab which is also the same across all elements. The order and layout of these fields are also referenced from the
builder.json
file.Here is the referenced value from the
builder.json
file.Dynamic Content
To add the dynamic content field which allows selecting a content source, reference the
source
fields from the builder.json
file. Referencing the advanced settings tab as in example above also defines the source field. To allow a field to map dynamic content, set the field
source
property to true
.Field Types
Here is a list of all available content field types in YOOtheme Pro.
Name | Description |
---|---|
checkbox | Define a checkbox. |
color | Define a color picker. |
editor | Define a visual and code editor. |
font | Define a font picker. |
icon | Define an icon picker for the UIkit icon library. |
image | Define an image picker for files in the media library. |
link | Define a link picker for Joomla system links and files in the media library. |
location | Define an interactive map to pick a location. |
number | Define a numerical input field. |
radio | Define a group of radio buttons. |
range | Define a range slider with an addition input field. |
select | Define a select box. |
text | Define an input field. |
textarea | Define a plain text area for multiple lines of text. |
video | Define a video picker for files in the media library. |
Field types which have additional properties are described below.
Checkbox Field
The checkbox field has an additional property
text
to set the text next to the checkbox.Editor Field
The editor field has an
editor
property which loads only the code editor when set to code
. An additional mode
property explicitly defines the code language css
, js
or text/html
.The following example shows an editor with the Visual and Code tabs.
The following example shows only the code editor with syntax highlighting for CSS.
Note To prevent the customizer preview from updating while typing in the editor, set the
debounce
attribute to around 500
milliseconds.Select Field
The select field has the
options
and default
properties for its options and the default value.Radio Field
The radio field has the
name
, options
and default
properties for its name, options and the default value.Range Field
The range field has no additional properties, but it is necessary to set the
min
, max
and step
HTML attributes.Field Layouts
Some field types are only used to layout fields in the page builder and have no content themselves. They are typically used in the
fieldset
object. The containing fields are defined in a fields
object. Name | Description |
---|---|
grid | Arrange fields within a grid which share a description text below. |
group | Arrange fields compactly with label and controls side by side and the description text as tooltip. |
Grid Field
The grid field has a
width
property to define the width for each grid cell.![Custom Custom](/uploads/1/1/8/8/118813883/627562089.jpeg)
Note Inline field definitions in the
fieldset
object need a unique name. By default, the label
property is used as fallback for the name. But if a field definition doesn't have a label like in the example above, a unique name
must be set. We mark names which are not used anywhere with a _
prefix.Group Field
The group field has a
divider
property to set a divider at the bottom of the group.Note Opposite to the grid field, groups usually have a
label
which is why a name
doesn't have to be set.Template Files
The following variables are available when rendering an element node in the templates.
Variable | Description |
---|---|
$node | The element node (stdClass) |
$props | The element properties $node->props set using the fields (array) |
$children | The element children $node->children , for example items (array) of a multiple items element |
$builder | The current builder instance used to render children (YOOthemeBuilder) |
Field Properties
All element fields defined in the
element.json
file can be accessed as properties using the $props
variable. Their type is defined by the field type, or null
if the user has not entered a value yet.Template Partials
Rendering the element layout is often split into template partials prefixed with
template-
using the helper function $this->render()
. The following example renders the template-content.php
file and passes the element properties $props
.Template Engine
The YOOtheme Pro template engine provides an HTML helper function
$this->el()
to create HTML elements using a compact interpolation syntax for the $props
variable. It also allows merging attributes easily.Syntax | Description |
---|---|
foo-{bar} | Add foo-{bar} if $props['bar'] has a value and substitute {bar} with the value. |
foo {@bar} | Add foo if $props['bar'] has a value. |
foo {@!bar} | Add foo if $props['bar'] has no value. |
foo {@bar: value} | Add foo if $props['bar'] is set to value . |
foo {@bar: value1|value2} | Add foo if $props['bar'] is set to value1 or value2 . |
foobar [foo {@bar}] | Add foobar and optionally add foo if $props['bar'] has a value. |
There are severals arguments which are passed to the HTML element rendering.
Argument | Type | Description |
---|---|---|
$params | array | Pass the required element properties $props . |
$attrs | array | Optionally, pass additional attributes to merge them. Attributes needed for the general and advanced element settings are stored in the attrs variable and should be passed to the element wrapping HTML element. |
$contents | mixed | Optionally, pass any content, for example $props['content'] , and the whole HTML element will get rendered. |
Transforms and Updates
The optional
element.php
file extends the element functionality with custom transforms or update functions. It has to be imported through the element.json
file.Here is an example on how to define transforms and updates for the element node. It also shows which objects and parameters are available.
Collapsing Layout
Make sure to prevent the element from rendering if its content fields are empty to behave according to the collapsing layout cascade.
Mind that for a single content field, the return value has to be casted to a boolean.
Updates
Define element updates for new versions of YOOtheme Pro.
Note Currently element updates are tied to the updates of YOOtheme Pro. They don't have their own version numbers and can only be updated when the YOOtheme Pro version number changes.
Yootheme Custom Elements Custom
Content Items
Elements which have content items, like the Grid element, are parent elements which contain child elements. To create a parent element, set the
container
property to true
in the element.json
file. To add a field which shows an interface to manage the content items, use the content-items
field type and set the item
property to the name
of the child element.Just like any other element a child element has its own directory, JSON configuration with a unique element name and template files. It's not shown in the element library which is why it also has no icons. Typically a child element also has an advanced setting tab which is the same across all child elements. Its fields order and layout are referenced from the the
builder.json
file.The child element should have at least a
title
field and an optional image
field. Both will be shown in the list of content items created by the content-items
field in the parent element.Template Files
All child elements can be accessed with the
$children
array and rendered using the helper function $builder->render()
. Typically the
$props
variable of the parent element is passed as $element
to the child element, so all fields of the parent element can be accessed in template files of the child element.Add Media Button
By default, the
content-items
field shows an Add Item button to create a new content item. Optionally, add an Add Media button which allows picking images in the media manager. For each selected image, a new item is created. The image
and title
fields are automatically filled out.Yootheme Custom Elements Design
Simply define the
media
object and set its type
property to image
. Use the item
object to define to which fields the image title
and src
are set.Preview Placeholder
Elements can show placeholder items in the page builder preview while they have no content items. Once a content item is added, the placeholder items disappear, and the content item is shown. Simply set the placeholder items in the
placeholder
object under children
in the element.json
file. Create an object for each placeholder item by setting the type
property to the name
of the child element.Make sure placeholders are defined in the child element.
If necessary, different placeholder values for fields of the placeholder item can be set in the
props
object.