Element API Reference

Element Definitions

Elements are registered with this function:

• $type must be a unique element name. Please use a prefix to avoid naming collisions. e.g. my-plugin-my-element
• $options provides all the details for our definition. It should be an array with the keys notated in Base Options below.

Base Options

Builder Options

These are all optional, but you'll want to provide some combination or the Inspector will be empty. Any of these keys can be added top level, but we recommend returning an array including them from the builder callback function. It is most likely that your builder callback will return the result of the cs_compose_controls function which provides an array in the shape described below. See Composing Controls

Sample Control Nav

Element Definition Options

Inline Editing

Here's an example of how to configure inline editing taken from the Tabs element.

The selector indicates the double click target. When the user starts editing, it will update the value with the associated key (tab_label_content). You can set the selector to root to make the base element the double click target.

Additional Definition Functions

Can be used to unregister an element originally registered under $name.

Retrieve the instance of an element's definition originally registered under $name

Defining Values

Every element needs values. These store data that will be customized later in the Element's controls.

Single values.

Each value has a $default which is the initial value used when an element is created.

The $designation determines how the system will render this value.

• markup` - When this value changes it makes a HTTP request to the server with the updated attributes and fetches new markup for the builder preview. This is the most expensive in terms of performance, but most versatile as it invokes your custom PHP code.
• attr - When this value changes it updates the value in the DOM immediately.
• style - We'll cover this later on, but our builders allow you to provide a style template to output generated CSS. When a value with this designation changes, it causes the generated CSS to recalculate.
• all - When this value changes it cause the element to fetch new markup from the server and renders the generated CSS again.

When $protected is set to true it flags the variable as "content". This means it will not be overridden by default when pasting element styles or applying a preset.

Example

Defining Reusable Values

This function is useful if you're creating a suite of elements that will share values. Call this before you register your elements to define values that can be reused later. The $key is a name to use when you want to recall your values with cs_values or cs_compose_values. Set $values to an associative array that assigns keys to the result of cs_value calls.

Example

Composing Values

The cs_compose_values function accepts unlimited arguments. Each can be a string or an array. If you pass a string, the function will retrieve the values stored via cs_define_values under the given key. If passed an array, it will merge those values into the list. This function will let you create elements that tap into predefined functionality.

Example

Prefixing Defined Values

By passing a string as the first argument, this function allows you to fetch values stored with cs_define_values. An array as the first argument assumes you are passing an associative array of values.

The $key_prefix argument is used to prefix every value in the list. The example below shows how you can retrieve the values of the native text element and prefix it for your element. The native card element is a good example of composing multiple values (controls as well).

Example

Individual Controls

In this section we'll cover all the different control types, the available options, and the helper functions you can use to work with them.

Control Parameters

A control is an array that contains the following keys

Control Reference

• Controls without keys only output a single value
• Keys with |value indicate which one is used when passing a singular key
• Keys with ? are optional.
• Angle brackets indicate you must use one of the enclosed strings. e.g. for <row|column> you must provide row or column.
• Each line in Options is an individual option that can be mapped for this control. If an option references another control, it means that you can pass an array of the options for the named control.

Notes:

1. Checkbox List - These keys are variable and depend on the items you map.
2. Font Weight - This needs a reference to font_family but it doesn't directly modify the value.
3. Group - The group control doesn't accept keys or options. A top level controls property will let you pass a list of controls to display inside the group.
4. Image - width and height are optional but you must declare both or neither
5. Image - is_retina can only be used if width and height are mapped.
6. Sortable - See sortable section below. Keys are not used
7. List - @since CS 7.4.0

Example Groups

You can add a group as child control of a group to create a third level. These controls don't support labels and you're even more restricted at the types of controls that can be mapped.

Group Example (2nd Level)

Group Example (3rd Level)

Example Checkbox List

Here's an example of the checkbox list control. The full option tells the checkbox to span the full width of the control area instead of being half size.

Composing Controls

Call cs_compose_controls with unlimited arguments. Each argument must be a string associated with a registered partial, or an array that adheres to the Builder Options parameters above. The function will combine multiple sets of controls into a single output used in the builder. This allows for leveraging partials and organizing the standard controls that should only appear when Advanced Mode is turned off.

Registering a Control Partial

To create your own control partials, call cs_register_control_partial with $name set to the key you will eventually reference in calls to cs_compose_controls or cs_partial_controls. Set $function to a function that will return valid Builder Options.

Example

Using Control Partials

Call cs_partial_controls and pass the result as an argument of cs_compos_controls to add the partial registered as $name to your control list. The $settings array is passed to the partial to allow for customization of the resulting controls.

Example

Leveraging Common Control Types

The cs_control function returns an array describing various common control types. It automatically maps one or more keys for you, and honors $key_prefix in front of those keys. Use the table below to see what is allowed for the $type argument. You can set Control parameters like group, condition(s), and options by passing them through $control. Settings can also be passed into $control to adjust the output.

All of these include {{prefix}} in their label, so you can pass label_prefix as a parameter of $control to further describe how the control should be used.

Amending a Control used multiple times

Use cs_amend_control to make an adjustment to a control that you've defined once, but need to use somewhere an additional time (useful for standard controls) with a slight adjustment. The $control argument is the original, and $update is the changes to merge in. This is different from array_merge because it handles the additional layer of updating the control's options parameter.

Example

Remembering Commonly Used Options

This can only be used inside a builder callback, but it allows you to store commonly used bits of data. For example, if you have a list of localized options that you may need to add on multiple elements you could store it like this.

Example

Recalling Commonly Used Options

Building off the previous example, we can recall the stored options as well. Remember it can only be used inside of a builder callback.

Example

Control Conditions

When mapping a control, you can set condition or conditions to determine when a control should be visible. This is primarily used to reveal additional controls after they are enabled. Each condition has the following properties:

• key - String identifier of the value we are observing
• op - The type of operator we are using for this comparison. See operator table below
• value - The value to check our condition against.
• or - Set to trueto enable OR logic for this condition. See Using OR Logic below.

1. Blank strings, CSS values that are zero with any unit, and the keyword none are considered empty.

Shorthand

The equality operator is the most commonly used and therefore is offered as a shorthand. The following two conditions are identical.

Using OR Logic

By default multiple conditions are applied with AND logic. This means they must all be true for the control to be visible. You can override this on individual controls by setting the or parameter to true. When enabled, the condition will be automatically be considered true if condition immediately following it is true. The following example is considered true when feature_enabled is true AND either some_value is a value in the list (one, two) or another_value is ten.

Example

Style Templates

When you set style to a function when registering your Element definition you will need to return a string style template. This uses a CSS like syntax to create dynamic styles based on the state of your element's values.

Basics

You can use variables in your selectors and property values. Variables can not be used as part of a property name. The available variables correspond to values that you have registered with designations style or all. An additional variable to reference the current element's class name is available as &. The following example shows styling a few properties. Each of the property value variables is expected to mapped as one of your element values.

Example

Conditions

Often you'll want to exclude styles unless a criteria is met. This is possible with @if. When using @if the contained styles will appear if the expression evaluates to true.

Learn more about Themeco Stylesheets here.

PHP in a style template

If you're browsing our partial templates, you'll notice that they are PHP functions that use object buffering. Remember that this PHP does not actually have any element data. We're constructing a template that contains rules applied to elements later. Using PHP is helpful to setup things like key prefixes and make calls to cs_get_partial_style.

Partials

This function is used to get the string of a predefined style template partial registered under $name. The $settings parameter is used to instruct the partial on various adjustments that can be made.

Creating a Style Partial

This is accomplished via the cs_get_partial_style_$name hook.

Example

Rendering

The function you assign to the render parameter accepts $data which includes the element values and should return a string.

Example

Rendering View Partials

Within your render function, call cs_get_partial_view with the $name of a partial you wish to render and a string will be returned with that partial's markup. The $data array is used to pass through your element's data (the $data argument of the render function). The example below is the native Button element.

Example

Preparing Partial Data

Extracting and Prefixing Data

Sometimes you'll need to modify the data passed into the partial. For example, if you want to use a partial multiple times, or need to rename some of the keys, you can do that with cs_extract.

Pass in the $data from your render function (or manipulate it first with calls so cs_without and/or array_merge) and specific what values you want to extract in the $find array. Here's an example of using cs_extract to retrieve values prefixed with headline_one/headline_two and rename those keys to text for the purposes of rendering the partial. Notice how the cs_extract calls work in parallel with calls to cs_values .

Example

Omitting Data

This function simply returns $data after omitting key/value pairs found in the $keys array.

Example

Deferred View Partials

Sometimes you want to output partial markup at the end of the site markup instead of inline. This is useful for modal and off-canvas elements. You can call cs_defer_partial with the $name of your registered partial and it will internally utilize a function called x_set_view which caches HTML and outputs it at a specific hook. In this case, it will be output at the x_before_site_end hook. This is a few levels above the closing </body> tag, and where X and Pro output all deferred markup. When using Cornerstone with other themes this will be equivalent to the wp_footer hook.

The $data argument is identical the cs_get_partial_view function. You can adjust the $priority used when attaching to the x_before_site_end hook. The following example is from the Content Area Modal element with some comments added.

Example

Creating a View Partial

This is accomplished via the cs_get_partial_view_$name hook.

Example

Helpers

Attributes

Takes an associative array ($atts) and combines them into single escaped string that can be output in an HTML tag.

Example

Class Output

Combines multiple strings into a single CSS class name. Pass as many arguments as you like. They can be strings or arrays of strings. It will automatically remove any values that are empty.

Example

ARIA Attributes

Some of the native view partials look for additional data to populate the aria attributes. We can attach this data with the cs_make_aria_atts function.

Example

The best way to understand how this function is used would be to look at the code for the Content Area Dropdown, Content Area Modal, and Content Area Off Canvas elements.

FAQ

How can I make an element like [native element]?

Feel free to copy and paste from our native elements liberally! The native partials are not a documented part of the public API, but you're welcome to re-use anything you find in our elements.

What is the _region value?

This is used internally to track which "region" the element resides in. Here are the regions and what they mean

• top, left, right, bottom - Element is a bar or descendant of one in the respective region of a Pro Header.
• footer - Element is a bar or descendant of one in a Pro Footer
• content - Element is in the main area of content created in the Content Builder of Global Blocks

Referencing this value can be useful if you want to slightly alter the element behavior based on the output location.

How can I make my render function behave differently in the preview area?

This is useful in render functions if you want to slightly adjust the behavior for the preview versus the front end.

How can I turn my element into a drag/drop container?

Because this requires additional client side (React Components) code, we do not currently offer a way to define an element as a drag and drop container.

Summary

We've taken an in-depth look at all the Element API has to offer, and covered specific options and covered the majority of functionality used in the native elements. When building your own elements, feel free to copy and paste sections of code from the native elements. For more of a step-by-step walkthrough of the Element API, see the API Primer.