Extending Page Builder’s native content types is often the best way to satisfy your end users when they request changes.
Page Builder gives end users several content styling options from the default form editors. But what if your end users want to create a Banner with a different layout? Or maybe they want to change or add content properties that don’t have a form field. These are the use cases that beg you to extend an existing content type, rather than create a new one.
All content types provide end users with at least one layout that has properties end users can set. In Page Builder, we call these layouts appearances. When we extend content types, we’re talking about changing or adding appearances to the content type. Making sense of appearances is essential to extending content types.
An appearance defines the layout and styles for a content type. Every content type has at least one appearance. Content types like the Banner have four appearances to choose from. All content types define their appearances in their configuration files. For example, Banners, Products, and Columns define all their configurations, including appearances, in
banner.xml, products.xml, and column.xml, respectively.
To help you understand the kind of changes you can make to appearances, we’ll look at a few nodes from the Banner’s
collage-left appearance from the
banner.xml file. The following XML fragment is a condensed version of this appearance, so we can focus on what’s important.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 <appearances> <appearance name="collage-left" preview_template="Magento_PageBuilder/content-type/banner/collage-left/preview" master_template="Magento_PageBuilder/content-type/banner/collage-left/master" reader="Magento_PageBuilder/js/master-format/read/configurable"> <elements> <element name="wrapper"> <style name="text_align" source="text_align"/> <attribute name="background_type" source="data-background-type"/> <css name="css_classes"/> </element> <element name="content"> <html name="message" preview_converter="Magento_PageBuilder/js/converter/html/directive"/> </element> </elements> </appearance> </appearances>
Even in a condensed form, appearance configurations can be confusing. A quick summary of these nodes may help:
appearance— identifies an appearance configuration (by name) that all the HTML templates and nodes help define.
preview_template— path to the HTML template (
preview.html) used to display the appearance in the Admin.
master_template— path to the HTML template (
master.html) used to display the appearance on the storefront.
element— node type bound to an HTML element in the
elementnode provides its bound template element with the
cssvalues from the form fields.
style— for adding CSS properties (like
text-align) to the element. The
stylenode is bound to a form field of the same name.
attribute— for adding custom properties (like
background_type) to the element. The
attributenode is bound to a form field of the same name.
css— for adding CSS classes to the element. The
cssnode is bound to a form field of the same name.
html— for allowing HTML content in the element. The
htmlnode is bound to a form field of the same name. The field’s
formElementtype is either
When you understand how Page Builder uses these appearance nodes, it becomes much easier to recognize the nodes that define layouts vs. the ones that define styles. These node groups are defined next.
Appearance layout nodes
The layout for an appearance comes from the arrangement of HTML tags (
<button>) in the templates. So if you need to change the layout, you start by changing the appearance templates:
collage-left/preview.html) for changing the appearance’s layout in the Admin.
collage-left/master.html) for changing the appearance’s layout on the storefront.
Appearance style nodes
The styles and properties for an appearance come from all the sub-nodes of a given
element. So if you need to change or add styles and properties to existing layouts, you start by changing and adding
html nodes to an existing
element— for identifying the HTML element (in the templates) that you want to change using the
style— for changing or adding a CSS property (like
text-align) to an element.
attribute— for changing or adding a custom property (like
background_type) to an element.
css— for changing or adding CSS classes to an element.
html- for allowing HTML content in the element.
Now that you know about appearances, take the next steps by walking through one or both of these tutorials. We highly recommend you start with the first one, Extend an appearance: