Page Builder for developers - Custom content types

Transcript

All right, we’re on to the final section, section five, customizing and creating new content types. And this is just a quick overview. I’m not gonna get too in depth, just gonna give you a brief overview of how to create a new content type. So you’ve seen this slide, or at least this graphic in the past, a workflow here of how to create a new content type. I’m gonna go a little more in depth on that. So step one is to add a configuration. So that entails creating an XML file to define your content type and reference all the other files that control the appearance and the behavior of your content type. And then in step two, we have adding templates, which involves creating HTML templates that define the appearance of your content types on the admin stage with preview.html and on the storefront with master.html. And then in step three, we have add component. And for that step, you will create a JavaScript file that defines the behavior of your content type on the admin stage. And that is with preview.js and on the storefront, it is master.js. Step four is to add a form and that is creating a UI component form and a layout so admin users can edit your content type within the page builder editor. Step five is to add styles. That involves creating several less files to style your content types when rendered in the admin UI and also on the storefront. And the final step, step six is to create an icon and that’s creating an SVG icon to just sort of visually identify your content type within the page builder panel. So you’ll notice in each of these steps, there’s really nothing new within Magento that you probably haven’t done before, such as adding styles. If you’re a front-end developer, you’ve added styles before so you’re familiar with that. If you’re a back-end developer, maybe you’ve built in a third-party module and you’ve modified a grid form or like some form elsewhere in the admin, you’ve added a form before. If you’ve worked in a JavaScript, you’ve probably created a component. If you’ve done anything with Knockout, you’ve added a template. So there’s really not too much to be intimidated about when creating a new content type. It’s really just knowing where all the pieces fit together, where all the pieces go, like putting together a puzzle. But everything that you see within page builder, you’ve probably seen before. So here we see a configuration file for the example quote content type. And if you are creating a new content type, I definitely recommend looking through the example repository. You can find that on Magento’s documentation page, and you’ll find more about that in the student guide if you’re not familiar with that already. The configuration file for any content type defines the settings and references to the content types files. And you can return to this file often and update references and change settings all throughout the development process. Files referenced from the configuration include HTML templates, JavaScript components, and icon displayed for your content type in the page builder panel, and also the UI component form for your content type editor within the admin.

By convention, page builder requires the configuration file to be in the page builder slash content underscore type directory within the admin HTML area of your module, or you can also add it to the content hyphen type directory as well. The name of your configuration file should reflect the name of your content type prefixed by your module vendor name and separated by an underscore. For example, your module name is example slash page builder quote, and our content type is quote control. For example, this module’s name is example slash page builder quote, and the content type is quote control. So Magento named the configuration file example underscore quote dot XML. And as I’ve said before, any configuration file should go in the page builder slash content underscore type directory, and that can also be the content hyphen type directory. Step two of creating your content type is to add your templates. So the content type templates are the HTML files that define how your content appears both on the admin stage and in your storefront. And then the combination of these templates is what creates an appearance. As discussed in the previous configuration step, you have to have at least one appearance to display the content for your content type. And if that is the case, then you would just use the default directory to house your master and preview templates. But like the banner, you can define several appearances for users to choose. So there are a few conventions that you have to follow within page builder, such as page builder requires you to name your templates preview dot HTML for the admin preview and master dot HTML for the storefront template. And then also when you put your templates in the appearance directory, the name of the directory has to match the appearance that you defined in your configuration. And if you don’t name your directories correctly, then your appearance just won’t render. So step three is adding your component. Components are just JavaScript files to define the behavior of your content type. And then you have the preview component that just defines the behavior in the admin and the master component defines the behavior in the storefront.

These are complimentary to the templates that you added in the last step. And architecturally, these components act as the view models to the templates views. It’s important to know that adding custom component files to your content types is completely optional. Whether you need one or not just depends on the complexity of your content type. If you do not add components to your content type, the page builder will just use the default and that is located in the native page builder module at js slash content type slash preview dot js and in the same directory for the master dot js template.

When you start developing more complex content types, there are a few situations where you will need to create a custom preview component so your content type works correctly in the admin. That can include things like initiating or using third party libraries such as like sliders and tabs, maybe you need to add image upload support or provide dynamic data in your preview template from the backend. You might also need to allow the backend to conduct very maybe complex renderings such as like what the block or dynamic block content type does and you may also need to declare special states based on the data that’s stored. For example, showing a disabled state when certain fields are set to specific values.

And when you create your components, they are configured in the same configuration file that we saw previously.

Now on to step four, adding a form. So you can see here in the screenshot, we are still in the example quote extension. The two files that you need to add are the layout file and the UI component file, they’re named the same.

The forms for page builder, they’re just like any other UI component. They render a form when you select the cog in the toolbox panel that opens up when you hover over a content type.

If you’re familiar with adding forms or any specific UI components within a form elsewhere in Magento, this really shouldn’t be all that new to you. The only difference in page builder when creating a form is specifying the name within the type node for the specific content type that you are working with. Now moving on to step five of creating your custom content type.

Here we’re talking about adding styles. When you create your template, any elements that you want to style in your style sheet, you can add the class attribute with your own unique class style. You want a user to be able to modify a style in the content types settings in the admin. That style will be added to the CSS attribute of the element in your template. Using the configuration of data.content-type.css.

Here just following the screenshot to kind of show what it would look like if a user was to modify a field in the settings panel of a particular content type. Here we have the template, the preview.html template for the quote, example quote content type. So the element block quote has the attribute class, which is the quote content class. And that is just for your own styling in your style sheet. There’s also the CSS attribute and that has data.quote.css. Data.quote refers to the quote element in configuration and .css refers to the CSS node that is set to the quote underscore CSS. Field. So the value of that name is the field that you can find in the form field for the example quote form. So here we can see that field, the name is quote underscore CSS and the form element is an input element. If we were to look at the quote content types settings panel in the admin, we would see a quote color field. And here we have a screenshot of that field, quote color, and the value is set to blue quote. So because the end user set the value of quote color to blue quote, so now when that template is rendered in the browser, Knockout will convert data.quote.css to the value that was added by the user in that input field. And here we see it is blue quote, which is the correct value. And here we see in the template, it is set to blue quote, which has a style applied to it and underscore import.less, which has a style applied to it and underscore import.less in the example quote module.

So the final step in creating a new content type is supposed to be adding an icon. It’s pretty straightforward, pretty self-explanatory. If you just go to the dev docs, there are instructions for how to do that. For the purposes of this instruction, we’re not going to be going over that. We are going to go over extending existing content types, and that is a little bit simpler than creating a new one.

The first part we’re going to cover is extending appearances. You can see here in this screenshot, again, we have the appearances for banners, and then you have a bit of the form for a banner. One of the quickest ways to customize page builder is to change how existing content types look and behave. So end users can already use page builder’s content types to customize their content just using the form editor. But your end users might want to change the structure or set properties that do not exist on the content type. In those cases, you can extend an existing content type by customizing its appearance or adding a new appearance. You can also extend the forms. In page builder, when you customize content types that have multiple appearances, you must also apply your changes to all appearances, not just one. So customizing a single appearance of a content type that defines multiple appearances is not currently supported. You can use appearances to change content types in the following ways. You can add a new style property. You can add or change templates. You can add to or change existing forms, or you can add new attributes. You can also move data between elements using them.

So the first step in creating appearance customizations for an existing page builder content type is to just create the standard Magento module. In this step, we create an empty module so we can add our appearance and form extensions in step two and three. We want to add a directory structure for a module and add the files module.xml and registration.php.

And you also want to enable your module by running the bin magento command module, module colon enable and bin magento setup colon upgrade.

To customize appearances, you need to create a new configuration file named with the same name and relative path as the configuration file responsible for originally declaring the appearance. Like layout.xml files, Magento merges page builder configuration files from across all the modules. You can use Magento’s module dependency declaration in the module.xml file for the module to ensure that your custom module is loaded after Magento’s core module. Once the module load order is handled correctly, the configuration values in your Magento’s core page builder module can then be overridden, or new nodes can be introduced using your own modules configuration. Page builder forms are UI component forms, and this means they follow the same conventions as any other UI component form in Magento. If you’re not already familiar with the UI component forms, you can learn more about them from the UI components guide on the Magento Dev Docs website.

Before you add a field to the form of an existing content type, you need to know where to add it. Or in other words, you need to decide which field set to put it in. Extending page builder forms like other UI components relies on the fact that XML configuration from across all the modules is merged into one.

Therefore, you can only modify the existing HTML.

So that’s all for this presentation. This was really just meant for an overview for page builder.

Don’t really expect you to come away from this, just knowing exactly how to create a new content type or extend the content type, more so just to have some context to dive more into it in your own time and look at the code yourself and start tinkering with things. But if you aren’t an expert at this point, if you’d like, Magento will be offering a three-day course that goes much more in depth. So I really appreciate you guys purchasing and viewing this course. Please stay inside and also cover your mouth when you cough.