CMDG 16: Live preview reference

By default, whenever a user changes a module setting, the Beaver Builder layout will refresh to reflect that change. The default refresh functionality works in many cases but can be overridden as detailed in the examples below for an instant preview that doesn't require a refresh.

Additionally, when developing a module, you must write it in a way that you account for the default settings as modules are rendered as soon as they are dropped into a layout. As such, your code should never expect that it's dealing with user submitted settings as it could be dealing with the default settings.

The live preview system got a few new additions in Beaver Builder 2.2 to make it easier to work with. These additions are described in the sections that are marked as Beaver Builder 2.2.

Important preview (Beaver Builder 2.2)

You can declare preview rules as important using the important param.

Attribute preview (Beaver Builder 2.2)

Attribute previews allow you to preview an HTML attribute change on an element. For example, you can have a text field update the `data-foo` attribute on an element as shown below.

Callback preview (Beaver Builder 2.2)

Callback previews allow you to specify the name of a JavaScript function in your field config for implementing custom preview logic.

Tthen define your callback function in JavaScript:

Text preview

A text preview will insert the text of a field into the element specified by the selector value. The selector value for all preview types is scoped to your module and only needs to include the selector of the element you wish to modify.

CSS preview

A CSS preview will use the value of a field combined with the property value to change the style of the element specified by the selector value. A unit value (as shown below) must also be specified for style properties such as font-size or line-height.

You can also define an array of rules for your CSS previews that allows a field to affect more than one selector and property.

CSS color preview

A CSS color preview is similar to the standard CSS preview except that it only applies to color picker fields. The value of the color picker field will be combined with the property value to change the style of the element specified by the selector value.

None

A preview type of none will prevent any preview from occurring when a module setting field is changed. This preview type can be useful if you wish to code your own custom preview functionality in the module's settings.js file.

JavaScript events

There are two JavaScript events available to you when working with live previews that may come in handy:

fl-builder.layout-rendered
This event fires on the main builder content wrapper .fl-builder-content every time the layout is rendered or rerendered, typically when saving settings. It can be used to run additional logic once the render has been completed.

Example:

fl-builder.preview-rendered
This event fires on the main builder content wrapper .fl-builder-content every time the layout preview is rendered or rerendered when editing settings. It can be used to run additional logic once the render has been completed.

Example:

Previous:
15. Helpers
Next: 
17. Partial refresh reference