Not Your Grandfather’s WYSIWYG Editor
For those of you coming to this article with zero experience in Page Builder in Magento 2, here is a brief introduction to what Page Builder is. Page Builder is a drag and drop interface for creating richly styled, dynamic content, without needing to write any CSS, JavaScript, or HTML. This makes Page Builder a perfect utility for merchants who want to create good looking dynamic content without needing to employ an in house developer or pay an agency to build, style, and maintain content for them. Page Builder branches out from more traditional WYSIWYG editors by adding custom content types in addition to your basic text styles. These are the content types included in Page Builder out of the box.
- Row
- Column
- Tabs
- Text
- Heading
- Buttons
- Divider
- HTML Code
- Image
- Video
- Banner
- Slider
- Map
- Block
- Dynamic Block
- Products
In most use cases, these components are enough. However, there will likely be a feature request made by a client or an ambitious marketer who wants Page Builder to do something that it doesn’t do out of the box. Fortunately, Page Builder was made to be extended with minimal effort. If you’re not a developer, the rest of this article isn’t going to be useful to you. I recommend reviewing Magento’s well-written user guide for Page Builder if you are a content creator or need to have an understanding of how to use Page Builder in general. It covers in detail all the native components, as well as how to use those components to build richly styled, dynamic content.
If you are a developer, or just someone interested in understanding the architecture of Page Builder, the rest of this article is for you. I am not going to explain how to create a custom component. For that, Magento has already provided detailed documentation for creating custom Page Builder components. Their documentation does an excellent job of walking you through creating a custom component, but it can be a little frustrating going into it without any understanding of Page Builder’s architecture. This article exists to fill that gap in knowledge so you can read the documentation with a little more comprehension.
Inserting Data
First, it’s important to understand how the data used to generate the content is sourced. Page Builder uses the same UI component forms and form fields that Magento uses throughout the backend. The form configuration files for existing Page Builder components can be found in the directory vendor/Magento/module-page-builder/view/adminhtml/ui_component. Since Page Builder utilizes the same UI component form architecture, you can find a lot of helpful blog posts and tutorials covering how to build your UI components and use existing ones. For a comprehensive overview of UI components, I recommend reading through Alan Storm’s series of articles on the topic.
If you are planning to add a field to a form for a Page Builder component and you aren’t sure how to do it, make sure you see if existing fields are being used elsewhere in the backend, or even in a native Page Builder component. I haven’t yet added a field type that didn’t already exist somewhere else in Magento.
Preview and Master
Once you have a place to insert the data, you have to put it somewhere. In the case of Page Builder, the data gets stored within the content. A key thing to understand about the Page Builder architecture is that the markup, functionality, and styles needed to render a component on the frontend, generally need to be reproduced to render the component in the backend. This duplication of styles is required because a component may need to look or behave differently in the frontend then it does in the backend. Magento calls the backend look and behavior “preview” and the frontend “master.” Magento splits up these areas by allowing for separate HTML templates to render the markup, separate JS component files for controlling the behavior, and separate CSS files for styling the markup. The file structure for a Page Builder component that had all three of these concerns separated would look like this:
Markup
Frontend: view/adminhtml/web/template/content-type/component-name/appearance-name/master.html
Backend: view/adminhtml/web/template/content-type/component-name/appearance-name/preview.html
Behavior
Frontend: view/adminhtml/web/js/content-type/component-name/master.js
Backend: view/adminhtml/web/js/content-type/component-name/preview.js
Styles
Frontend: view/frontend/web/css/source/_module.less
Backend: view/adminhtml/web/css/source/_module.less
I say “generally need to be reproduced” earlier in this section because there is the option to only write one of these files for each concern. Most native Page Builder components follow the pattern of separating the markup and styles into their respective areas while only adding custom JS to the preview.js file. The master.js file is available for very complex components and, according to Magento, rarely necessary. You also have the option of setting a single HTML file as both the preview and master template if your component is simple enough. As for the styles, the “base” area in a module’s view directory applies styles to both frontend and backend. If your module is simple enough, you might be able to get away with only writing the styles in this base area.
Data Storage and Retrieval
The bridge of the data between markup and form fields is the content type config file. Looking at the Magento_PageBuilder extension, you’ll find these config files in the directory view/adminhtml/pagebuilder/content_type/. The content types config file defines the source of the data. It is also where converters are assigned to manipulate the data as it’s passed between the markup and the form fields.
All data that is inserted into the markup via a form field will be used in the markup for one of these four purposes.
In the preview and master knockout templates, the data for these fields can be seen represented as data.element.dataType. For example, if a field outputs its data as HTML in an element named container, the templates would have the object data.container.html, and the preview.js and master.js components would render that object using any converters assigned to that particular field.
Converters and Mass Converters
Sometimes a field contains a value that needs to be parsed into something else before it can be put into the markup. For example, if you have an input field to define a pixel value for a CSS style, you might want to have that field validate as a number. However, that CSS style still needs that value to come in the form of a pixel value (e.g., 10px), so you need a converter to append ‘px’ to the value when it’s being parsed in the HTML and remove it when retrieved from the HTML. Magento created a converter that does precisely this in the file view/adminhtml/web/js/converter/style/remove-px.js.
Mass converters serve the same purpose as converters in that they convert some value into a modified value. The difference is that mass converters are generally used to create a single output from multiple inputs or vice versa. They are useful when you need to convert a form field value, or multiple field values, into something that cannot convert back into its original value. A mass converter also allows you to place the original value of a field into a data attribute while converting the new value to what it needs to be in the dom. For example, the background-images mass converter converts the mobile and desktop background images into media directives ({{media url='wisiwyg/background.jpg';}}). These media directives get saved to the markup to be parsed by PHP, but the original background image URLs also get saved to the markup in the form of a data attribute:
data-background-images="{'desktop_image':'https://example.test/media/wysiwyg/desktop.jpg',
'mobile_image':'https://example.test/media/wysiwyg/mobile.jpg'}"If all this is a bit confusing, think of mass converters in the way the name implies. A converter is a straightforward one-to-one conversion, while a mass converter is everything else. Converters are a compelling feature of Page Builder and possibly require the most time and experience to master. Take plenty of time to review the existing converters so you can see how they work.
Conclusion
By now, you should have a good understanding of how everything is put together within a Page Builder component. You have learned how the data inserted into the markup with form fields, modified with converters, rendered in the templates, and retrieved from the markup for editing. If you still feel like you aren’t grasping Page Builder enough to begin reviewing the documentation, take a look at Magento’s example components. The example components are a bit more simple and straight forward than the ones included with Page Builder, so they should be easier to grasp. Look through one or two of those examples and then come back and reread this article.
I hope this article has been enlightening. Feel free to comment below if you have any questions. Page Builder is a project that is still undergoing many changes, and some of this article might end up out of date. If you notice an error, please let me know so I can make the necessary changes.