data-slot=text

Add form

In this step, we will create a UI component form. This form will give users another way to enter text for the Quote and style the text's appearance.

About forms

Page Builder provides two base forms that give you a ton of functionality you can inherit from right out-of-the-box:

• pagebuilder_base_form

• pagebuilder_base_form_with_background_attributes (inherits from pagebuilder_base_form)

Inheriting from either base form gives you an editor for your content type that slides out from the right side of the Admin screen.

pagebuilder_base_form

The pagebuilder_base_form gives you the following form fields in a fieldset named Advance, along with the Close, Reset, and Save buttons as shown here:

pagebuilder_base_form_with_background_attributes

In addition to all the fields from pagebuilder_base_form, the pagebuilder_base_form_with_background_attributes gives you the following "Background" form fields as shown here:

The base form you inherit from depends on the complexity of the content type you create and the level of customization you want to give to end-users.

Form and layout conventions

The conventions for naming your form and its layout are as follows:

• The name for your form should follow this pattern: pagebuilder_ + content_type_name_ + form.xml. For example pagebuilder_example_quote_form.xml.

• The name for your layout must match the name of your form, in this case: pagebuilder_example_quote_form.xml.

Add your form and layout files to your module in the following locations:

• view/adminhtml/layout/

• view/adminhtml/ui_component/

Form configuration

In your configuration file, add your form name (without the .xml file extension) to the form attribute within the <type> element, as shown here:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_PageBuilder:etc/content_type.xsd">
    <type name="example_quote"
        label="Quote"
        form="pagebuilder_example_quote_form"
        ...>

The Quote form

In our Quote form, we will inherit from pagebuilder_base_form_with_background_attributes. This will give end-users all the native Page Builder form fields shown in the two previous screenshots. In addition to those fields, we want to add four specific content entry and styling fields, as shown here:

The purpose of each field is described as follows:

The Quote form is shown in full here for you to copy into your pagebuilder_example_form.xml file, followed by descriptions of the key parts.

<?xml version="1.0" encoding="UTF-8"?>
<form xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Ui:etc/ui_configuration.xsd" extends="pagebuilder_base_form_with_background_attributes">
    <argument name="data" xsi:type="array">
        <item name="js_config" xsi:type="array">
            <item name="provider" xsi:type="string">pagebuilder_example_quote_form.pagebuilder_example_quote_form_data_source</item>
        </item>
        <item name="label" xsi:type="string" translate="true">Quote</item>
    </argument>
    <settings>
        <namespace>pagebuilder_example_quote_form</namespace>
        <deps>
            <dep>pagebuilder_example_quote_form.pagebuilder_example_quote_form_data_source</dep>
        </deps>
    </settings>
    <dataSource name="pagebuilder_example_quote_form_data_source">
        <argument name="data" xsi:type="array">
            <item name="js_config" xsi:type="array">
                <item name="component" xsi:type="string">Magento_PageBuilder/js/form/provider</item>
            </item>
        </argument>
        <dataProvider name="pagebuilder_example_quote_form_data_source" class="Magento\PageBuilder\Model\ContentType\DataProvider">
            <settings>
                <requestFieldName/>
                <primaryFieldName/>
            </settings>
        </dataProvider>
    </dataSource>
    <fieldset name="appearance_fieldset" sortOrder="10" component="Magento_PageBuilder/js/form/element/dependent-fieldset">
        <settings>
            <label translate="true">Appearance</label>
            <additionalClasses>
                <class name="admin__fieldset-visual-select-large">true</class>
            </additionalClasses>
            <collapsible>false</collapsible>
            <opened>true</opened>
            <imports>
                <link name="hideFieldset">${$.name}.appearance:options</link>
                <link name="hideLabel">${$.name}.appearance:options</link>
            </imports>
        </settings>
        <field name="appearance" formElement="select" sortOrder="10" component="Magento_PageBuilder/js/form/element/dependent-visual-select">
            <argument name="data" xsi:type="array">
                <item name="config" xsi:type="array">
                    <item name="default" xsi:type="string">default</item>
                </item>
            </argument>
            <settings>
                <additionalClasses>
                    <class name="admin__field-wide">true</class>
                    <class name="admin__field-visual-select-container">true</class>
                </additionalClasses>
                <dataType>text</dataType>
                <validation>
                    <rule name="required-entry" xsi:type="boolean">true</rule>
                </validation>
                <elementTmpl>Magento_PageBuilder/form/element/visual-select</elementTmpl>
            </settings>
            <formElements>
                <select>
                    <settings>
                        <options class="AppearanceSourceQuote"/>
                    </settings>
                </select>
            </formElements>
        </field>
    </fieldset>
    <fieldset name="general" sortOrder="20">
        <settings>
            <label/>
        </settings>
        <field name="quote_text" sortOrder="10" formElement="textarea">
            <argument name="data" xsi:type="array">
                <item name="config" xsi:type="array">
                    <item name="source" xsi:type="string">page</item>
                </item>
            </argument>
            <settings>
                <dataScope>quote_text</dataScope>
                <dataType>text</dataType>
                <label translate="true">Quote</label>
            </settings>
        </field>
        <field name="quote_author" sortOrder="20" formElement="input">
            <argument name="data" xsi:type="array">
                <item name="config" xsi:type="array">
                    <item name="source" xsi:type="string">page</item>
                </item>
            </argument>
            <settings>
                <dataScope>quote_author</dataScope>
                <dataType>text</dataType>
                <label translate="false">Author</label>
            </settings>
        </field>
        <field name="quote_author_desc" sortOrder="30" formElement="input">
            <argument name="data" xsi:type="array">
                <item name="config" xsi:type="array">
                    <item name="source" xsi:type="string">page</item>
                </item>
            </argument>
            <settings>
                <dataScope>quote_author_desc</dataScope>
                <dataType>text</dataType>
                <label translate="false">Author Description</label>
            </settings>
        </field>
        <field name="quote_css" sortOrder="40" formElement="input">
            <argument name="data" xsi:type="array">
                <item name="config" xsi:type="array">
                    <item name="source" xsi:type="string">page</item>
                </item>
            </argument>
            <settings>
                <dataScope>quote_css</dataScope>
                <dataType>text</dataType>
                <label translate="true">CSS for Quote</label>
            </settings>
        </field>
    </fieldset>
</form>

appearance fieldset and field

Page Builder requires you to add the appearance_fieldset along with its appearance field for all your content type forms. Even though our Quote content type doesn't have any additional appearances, the field is still required/expected so that other modules can add appearances to your content type as needed.

To ensure your appearance field renders, create a di.xml file located here:

Then add the source implementation as referenced in the appearance field (<options class="AppearanceSourceQuote"/>) as shown here:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <virtualType name="AppearanceSourceQuote" type="Magento\PageBuilder\Model\Source\VisualSelect">
        <arguments>
            <argument name="optionsSize" xsi:type="string">large</argument>
            <argument name="optionsData" xsi:type="array">
                <item name="0" xsi:type="array">
                    <item name="value" xsi:type="string">default</item>
                    <item name="title" xsi:type="string" translate="true">Default</item>
                </item>
            </argument>
        </arguments>
    </virtualType>
</config>

Again, even though our Quote control doesn't currently define an appearance, we must implement all the parts so that other modules can expect each Page Builder content type to have an appearance defined, even if it is not used.

fieldset

Page Builder requires fields to be grouped within named <fieldset> elements. Fieldsets provide your fields with a basic grouping mechanism and an optional label. You can define as many fieldsets as you want.

field

The <field> element creates the actual HTML form element as specified by the formElement attribute, such as input, select, textarea, and colorPicker.

data source

Defines the data source for the field. The source node's value corresponds to a key (page) in the data array returned by the \Magento\Framework\View\Element\UiComponent\DataProvider\DataProviderInterface::getData method of your UI component.

<field name="quote_text" sortOrder="10" formElement="textarea">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            <item name="source" xsi:type="string">page</item>
        </item>
    </argument>

For example, the quote_text field above specifies that the source of its data should come from the data stored under the key page returned by the page's DataProvider.

settings

The <settings> element defines the data scope, data type, and label to use for the field, as shown here:

<settings>
    <dataScope>quote_text</dataScope>
    <dataType>text</dataType>
    <label translate="true">Quote</label>
</settings>

Quote form layout

The layout for our Quote form is shown in full here for you to copy into your pagebuilder_example_form.xml layout file. For more information about layouts, see Layout instructions.

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" layout="admin-1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <update handle="styles"/>
    <body>
        <referenceContainer name="content">
            <uiComponent name="pagebuilder_example_quote_form"/>
        </referenceContainer>
    </body>
</page>

Configuration data mapping

As mentioned in Add configuration, the elements section of your configuration file, maps the data from your form to the content type's master format so that the values entered in the form can be stored and rendered correctly on the Admin stage and storefront.

The following elements are from our example_quote.xml configuration. These elements are shown here in full for you to copy into your configuration file. Descriptions of the key attributes follow.

<elements>
    <element name="main">
        <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="background_color" source="background_color"/>
        <style name="background_image" source="background_image" converter="Magento_PageBuilder/js/converter/style/background-image" preview_converter="Magento_PageBuilder/js/converter/style/preview/background-image"/>
        <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"/>
        <style name="display" source="display" converter="Magento_PageBuilder/js/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="quote">
        <style name="text_align" source="text_align"/>
        <html name="quote_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
        <css name="quote_css"/>
    </element>
    <element name="author">
        <style name="text_align" source="text_align"/>
        <html name="quote_author" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
    </element>
    <element name="author_title">
        <style name="text_align" source="text_align"/>
        <html name="quote_author_desc" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
    </element>
</elements>

element

The <element> element provides a scope for the data bindings within it.

style

The <style> element configures the bindings from the form style fields to the template elements.

attribute

The <attribute> element provides a mechanism to attach DOM attributes to template elements.

css

The <css> element sets the binding for the CSS Classes form field (css_classes) from the pagebuilder_base_form, or from any custom input field you add to your form. When we define the <css> element, Page Builder applies the class names from the form's CSS Classes field to the template elements that use the css binding element.

For example, in our Quote configuration, we define an <element> named quote with a <css> element bound to an input field in our form named quote_css, as shown here:

<!-- from example_quote.xml -->
<element name="quote">
    ...
    <css name="quote_css"/>
</element>

The corresponding quote_css form field is shown here:

<!-- from pagebuilder_example_quote_form.xml -->
<field name="quote_css" sortOrder="40" formElement="input">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            <item name="source" xsi:type="string">page</item>
        </item>
    </argument>
    <settings>
        <dataScope>quote_css</dataScope>
        <dataType>text</dataType>
        <label translate="true">CSS for Quote</label>
    </settings>
</field>

And the css binding is applied in the preview.html template, as shown here:

<!-- from preview.html -->
<blockquote css="data.quote.css" ...></blockquote>

In Add styles, we will revisit the css attribute in detail to show how users can style templates with additional CSS classes.

html

The <html> element binds the HTML content entered in a form field. When the <html> element names a field for binding, content entered into the field is applied to the template elements that use them.

For example, as with the previous css binding, the Quote configuration defines the <element> named quote with an <html> element that is bound to an input field in our form named quote_text, as shown here:

<!-- from example_quote.xml -->
<element name="quote">
    ...
    <html name="quote_text" converter="Magento_PageBuilder/js/converter/html/tag-escaper"/>
    <css name="quote_css"/>
</element>

The corresponding quote_text form field is shown here:

<!-- from pagebuilder_example_quote_form.xml -->
<field name="quote_text" sortOrder="10" formElement="textarea">
    <argument name="data" xsi:type="array">
        <item name="config" xsi:type="array">
            <item name="source" xsi:type="string">page</item>
        </item>
    </argument>
    <settings>
        <dataScope>quote_text</dataScope>
        <dataType>text</dataType>
        <label translate="true">Quote</label>
    </settings>
</field>

And the html binding is applied in the master.html template, as shown here:

<!-- from master.html -->
<blockquote css="data.quote.css" html="data.quote.html"></blockquote>

Next

Add styles