data-slot=text

Content type configurations

Content type configurations are how you define your content types to Page Builder. Creating new content types, extending content-types, and customizing content types all starts with an XML configuration file.

Your configuration should conform to our XSD: urn:magento:module:Magento_PageBuilder:etc/content_type.xsd. This topic provides descriptions of all the elements and properties that make up a content type configuration file. We'll start with the first element, type, and work our way down to the last element.

type element

There are a number of simple attributes that can be configured within the <type /> node of your content type.

Example:

<type name="text"
        label="Text"
        component="Magento_PageBuilder/js/content-type"
        preview_component="Magento_PageBuilder/js/content-type/text/preview"
        form="pagebuilder_text_form"
        menu_section="elements"
        icon="icon-pagebuilder-text"
        sortOrder="1"
        translate="label">

Direct children of type

The direct child elements of type are described here:

parents element

The parents element specifies which content types can accept this type as a child.

Parent policies will override any child policies that are set.

You can configure the default policy to easily allow or deny all parents.

The parents node accepts a list of content types for the policy via child parent elements.

Example:

<parents default_policy="deny">
    <parent name="row" policy="allow"/>
    <parent name="column" policy="allow"/>
</parents>

children element

The children element specifies which content types can accept this type as a parent, this configuration is formed the same as the above parents configuration, the difference being this controls which content types can be a child of the current content type.

Parent policies will override any child policies that are set.

You can configure the default policy to easily allow or deny all children.

The children node accepts a list of content types for the policy via child child elements.

Example:

<children default_policy="allow">
    <child name="row" policy="deny"/>
    <child name="column" policy="deny"/>
</children>

appearance element

The appearances node contains one or more appearance elements, which control how the content type renders in the Admin preview and storefront (using the master format).

The appearance configuration specifies how the master and preview components and templates interact with data from the master format. It also defines where and how data should be placed on the elements declared in your master.html and preview.html templates.

Each content type can have a number of different appearances. These appearances can alter where data is placed on the element. Different element placements, can provide different layouts for the same content type, without adding additional bloat to the UI.

For example, the Banner content type uses this feature to create four different appearances (layouts) for the same set of elements. This flexibility is one of Page Builder's key features. You can change an existing appearance (or add a new appearance) to provide new features for the same content type.

Example:

<appearance default="true"
            name="default"
            preview_template="Magento_PageBuilder/content-type/text/default/preview"
            master_template="Magento_PageBuilder/content-type/text/default/master"
            reader="Magento_PageBuilder/js/master-format/read/configurable" />

Every content type must declare a default appearance to allow other modules to easily extend the content type with additional appearances.

element node

The elements node contains one or more element nodes. An element node defines the attributes and properties that Page Builder binds to the HTML elements (<div>, <textarea>) in your preview.html and master.html templates.

For example, if you specified main as your element name (<element name="main" />), you could reference all styles and attributes in your master.html and preview.html templates as follows:

<div html="data.main.html" attr="data.main.attributes" ko-style="data.main.style" css="data.main.css"></div>

Where main is the element's name and html, attributes, style, and css are the elements that define the data for the element. These data elements are described here:

Example:

The Button Item content type shows multiple elements with various attributes.

<elements>
    <element name="main">
        <style name="display" source="display" converter="Magento_PageBuilder/js/content-type/button-item/converter/style/display" preview_converter="Magento_PageBuilder/js/converter/style/preview/display"/>
        <attribute name="name" source="data-content-type"/>
        <attribute name="appearance" source="data-appearance"/>
        <css name="css_classes"/>
    </element>
    <element name="link">
        <style name="text_align" source="text_align"/>
        <style name="border" source="border_style" converter="Magento_PageBuilder/js/converter/style/border-style"/>
        <style name="border_color" source="border_color"/>
        <style name="border_width" source="border_width" converter="Magento_PageBuilder/js/converter/style/border-width"/>
        <style name="border_radius" source="border_radius" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
        <style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins"/>
        <style name="padding" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/paddings" converter="Magento_PageBuilder/js/converter/style/paddings"/>
        <attribute name="button_link" reader="Magento_PageBuilder/js/property/link" persistence_mode="read"/>
        <attribute name="virtual_link_href" storage_key="button_link" source="href" converter="Magento_PageBuilder/js/converter/attribute/link-href" persistence_mode="write"/>
        <attribute name="virtual_link_target" storage_key="button_link" source="target" converter="Magento_PageBuilder/js/converter/attribute/link-target" persistence_mode="write"/>
        <attribute name="virtual_link_type" storage_key="button_link" source="data-link-type" converter="Magento_PageBuilder/js/converter/attribute/link-type" persistence_mode="write"/>
        <css name="button_type"/>
    </element>
    <element name="empty_link">
        <style name="text_align" source="text_align"/>
        <style name="border" source="border_style" converter="Magento_PageBuilder/js/converter/style/border-style"/>
        <style name="border_color" source="border_color"/>
        <style name="border_width" source="border_width" converter="Magento_PageBuilder/js/converter/style/border-width"/>
        <style name="border_radius" source="border_radius" converter="Magento_PageBuilder/js/converter/style/remove-px"/>
        <style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins"/>
        <style name="padding" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/paddings" converter="Magento_PageBuilder/js/converter/style/paddings"/>
        <css name="button_type"/>
    </element>
    <element name="link_text">
        <html name="button_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
    </element>
</elements>

data-variant=info

data-slots=text

style, property, and attribute elements

These elements share a common interface and can be configured using the following attributes.

You can optionally set a reader in configuration, otherwise Magento_PageBuilder/js/property/style-property-reader will be used for properties, and Magento_PageBuilder/js/property/attribute-reader will be used for attributes. Both default readers accept source as a parameter, and return that value.

For example, the margins style uses a custom margins reader, as well as a custom converter, described next:

<style name="margins" storage_key="margins_and_padding" reader="Magento_PageBuilder/js/property/margins" converter="Magento_PageBuilder/js/converter/style/margins" />

converter

The converter enables you to convert data between different formats or make mutations on the data as it's read or written for your specific element.

For example, Page Builder's remove-px.js converter removes px strings from CSS values after reading from the DOM of the master format (using fromDOM()). This converts the value from a string to number so that it can be handled numerically as needed. The same converter adds the px string back to the CSS value before writing it to the DOM of the master format (using toDOM()).

All converters have these two functions:

• fromDom() - called after data is read from the master format.
• toDom() - called before observables are updated in the cycle rendering preview or master format.

Page Builder provides several converters you can use in your own content types: Magento/PageBuilder/view/adminhtml/web/js/converter.

When accessing data provided into the above functions, you should use the get and set utility functions from Magento_PageBuilder/js/utils/object. These functions ensure that you can use dot notation to correctly retrieval and set that data mapping entries that traverse deeper into the data set.

Example:

The following converter determines the output for an overlay background color:

define(["Magento_PageBuilder/js/utils/color-converter", "Magento_PageBuilder/js/utils/number-converter", "Magento_PageBuilder/js/utils/object"], function (colorConverter, numberConverter, objectUtil) {
    var OverlayBackgroundColor = function () {};

    /**
     * Convert value to internal format
     *
     * @param {string} value
     * @returns {string | object}
     */
    OverlayBackgroundColor.prototype.fromDom = function fromDom(value) {
        return value;
    };

    /**
     * Convert value to knockout format
     *
     * @param {string} name
     * @param {object} data
     * @returns {string | object}
     */
    OverlayBackgroundColor.prototype.toDom = function toDom(name, data) {
          var overlayColor = "transparent";

          if (data.show_overlay === "always" && data.overlay_color !== "" && data.overlay_color !== undefined) {
                overlayColor = colorConverter.fromHex(data.overlay_color, numberConverter.percentToDecimal(data.overlay_transparency));
          }

          return overlayColor;
    };
    return OverlayBackgroundColor;
});

static_style and static_attribute elements

These elements should be used to add static styles and attributes that don't require any logic or input by the end user. A good example is the CSS overflow property. Let's say a content type provides users with a max-height property they can set. The max-height in this context is a dynamic property because users can set it from a form. As a dynamic property, you need to add it to an element using the <style> element. But the overflow property in this context is static. End users don't set it and no logic is required. But this property is essential to how your content type is rendered. It ensures that content can scroll when the max-height is reached. Without it, your content type would not render or function as intended.

Defining your static styles with static_style or static_attribute, rather than from a loaded style sheet, ensures that the master format has all the essential data it needs to render its content as intended, independent of any outside requirements.

Example from Image:

<element name="desktop_image">
    <static_style source="max-width" value="100%" />
    <static_style source="height" value="auto" />
</element>

html

The html element allows you to read the innerHTML of the element in a property and map it back to the master format. This enables you to add rich text editing to a content type and have the HTML written and read from the master format.

Example:

<html name="message" converter="Magento_PageBuilder/js/converter/html/tag-escaper" />

data-variant=warning

data-slots=text

css

The css element allows you to read the class value of the element in the property and map back to the master format.

filter allows you to specify which static CSS classes to ignore. These classes are not read and do not appear on the form.

Example:

<css name="button_type">
    <filter>
        <class source="pagebuilder-banner-button"/>
    </filter>
</css>

tag

The tag element allows you to read the tag name of the element and map back to the master format.

Example:

<tag name="heading_type"/>

Mass converter

The mass converter provides a similar function to the element converter. However, mass converters are able to access and modify all data. For example, we use these to convert the background desktop and mobile images into a JSON format which is read and rendered into CSS on the storefront. Mass converters are defined for a specific appearance.

The fromDom method is called after data is read for all elements and converted by element converters.

The toDom method is called before data is converted by element converters to update observables.

When accessing data provided into the above functions, you should use the get and set utility functions from Magento_PageBuilder/js/utils/object. These functions ensure that you can use dot notation to correctly retrieval and set that data mapping entries that traverse deeper into the data set.

Example: Mass converter that defaults mobile image value to desktop image value if not configured.

<converters>
    <converter name="empty_mobile_image" component="Magento_PageBuilder/js/mass-converter/empty-mobile-image">
        <config>
            <item name="desktop_image_variable" value="background_image"/>
            <item name="mobile_image_variable" value="mobile_image"/>
        </config>
    </converter>
</converters>

define(["Magento_PageBuilder/js/utils/object"], function (objectUtil) {
    var EmptyMobileImage = function () {};

    /**
     * Process data after it's read and converted by element converters
     *
     * @param {object} data
     * @param {object} config
     * @returns {object}
     */
    EmptyMobileImage.prototype.fromDom = function fromDom(data, config) {
        var desktopImage = objectUtil.get(data, config.desktop_image_variable);
        var mobileImage = objectUtil.get(data, config.mobile_image_variable);

        if (mobileImage && desktopImage && mobileImage[0] !== undefined && desktopImage[0] !== undefined && mobileImage[0].url === desktopImage[0].url) {
            delete data[config.mobile_image_variable];
        }

        return data;
    };

    /**
     * Process data before it's converted by element converters
     *
     * @param {object} data
     * @param {object} config
     * @returns {object}
     */
    EmptyMobileImage.prototype.toDom = function toDom(data, config) {
        var mobileImage = objectUtil.get(data, config.mobile_image_variable);

        if (mobileImage === undefined || mobileImage[0] === undefined) {
            objectUtil.set(data, config.mobile_image_variable, objectUtil.get(data, config.desktop_image_variable));
        }

        return data;
    };

    return EmptyMobileImage;
});

Preview component settings

When creating your preview component there are some additional settings you can configure to inform the internal framework how to handle aspects of your data.

Menu Sections

The different sections displayed in the left menu are configured with the menu_section.xml configuration. This configuration allows you to configure new menu sections along with modifying existing ones.

Your configuration should conform to our XSD: urn:magento:module:Magento_PageBuilder:etc/menu_section.xsd. This article will go into more details regarding the configuration you can include within a content type.

We discourage modifying existing menu sections if they do not belong to your module.

menu_section element

An example of a menu-section configuration can be found here: view/adminhtml/pagebuilder/menu_section.xml:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/menu_section.xsd">
    <menu_section name="layout" translate="label" sortOrder="1" label="Layout"/>
</config>

For more information on how to customize the menu sections and the left panel please see: Customize the panel.