What you'll learn
- how to create a new Page Builder element
- how to add custom plugins to Webiny apps
Although the Page Builder app comes with a lot of ready-made page elements, at one point in time, you might need to create your own to satisfy your specific requirements. To achieve that, we can utilize a couple of simple plugins, which is what we'll cover in this short tutorial. So, without further ado let's get started.
We’ll create a new element that will allow content creators to embed content using an
Here's what the end result will look like:
We're creating a sample plugin here, but the same principle applies no matter what type of plugin the developer wants to create.
- A Webiny Project
This tutorial assumes you have already created a new Webiny project to work on. We recommend reading our install Webiny tutorial which will show you how to do it.
- Organization of Files
Although you can place and organize the plugin files as you see fit for your project, we recommend following some kind of structure which is easy to understand and maintain later on.
In this particular case, we'll need to share some logic (a plugin) across multiple apps i.e.
For this we're going to create a package named
packages folder, and simply import and reuse the code (plugin) across apps.
This is a very common scenario for Page Builder plugins because the Admin app use the plugin to render element inside editor and the Website app need the same plugin to render element in the actual page.
To create a new page element, we need to register two sets of plugins:
- For the
- a plugin that will defines how it's rendered in the editor
- a plugin that will defines all of the available settings and options for it
- For the
- a plugin that will defines how the page element is rendered on the actual page
To better organize files we'll write all the plugins needed for the Admin app in
iFrameElement/src/admin and plugins needed for
the Website app in
In the end the folder structure of our project will look similar to this:
All of the available page elements can be accessed via the elements menu, which can be opened by clicking on the "plus" icon, located on the left side of the editor:
As mentioned, this list of page elements can be expanded and custom page elements can be created via plugins. Now that we have covered the brief overview of what we need to do and how to organize files. Let's get started with creating plugins.
Let's add the new page element in the editor. First, we will add the necessary plugins in the
We will start with the
pb-editor-page-element plugin type.
The key properties of the plugin are the
They define the initial page element's settings and how it will be rendered in the editor, respectively.
data property holds the initial state of the page element which can contain any data you might need.
toolbar property helps us put our plugin into the tool bar.
Finally, it’s up to the
render function to define how the page element will be rendered once the user drops it on the page.
props that were passed to the render function. This object contains all of the relevant page element's data and settings.
After registering the plugin in the Admin app it will appear in editor toolbar similar to the pre-defined elements as shown below:
Now that we've covered the overall structure of plugin. Let's see what's inside
The following code snippet shows the entire
As you can see it's a simple React component which render an
iframe HTML element.
Every element needs to have
component as root because it apply
styles, classes and attributes to the element assigned via right sidebar style tab.
Notice we've added
webiny-pb-base-page-element-style CSS class.
Every element needs to have it as it contains all base styles applied by Page Builder app.
Notice we've added
webiny-pb-page-element-iframe CSS class, which enables us to add custom CSS styling if needed.
The next plugin we'll need to define is the
which we will use to render required UI for settings so the user can provide an iframe URL.
The settings UI will be shown automatically in right sidebar when the user drags and drops the page element on the page.
This plugin type will be added in the
packages/iFrameElement/src/admin/index.tsx file too.
As mentioned, this code will show the settings UI in sidebar and ask for the URL of the iframe, as shown in the image below:
As mentioned, every page element consists of two sets of plugins. We've already covered the editor side of the logic now, let's also see the actual plugin/code that will render it to the page.
In order to render the element on the actual page, we will use the
We will add this plugin in the
The following code snippet shows the
Along with the actual page, this plugin will also responsible for rendering the element in the page preview, as shown in the image below:
Now that we've created plugins for
iFrame element. We need to register them in
apps/admin to work.
Let's make the required changes as shown below:
After registering the plugins successfully you will see them in the Admin app as shown below:
Using the same approach you can create as many custom elements as you need for your project.
In order to render the page element on the website app, we will use the
pb-render-page-element plugin again.
The render plugin is necessary to load our page element in the page.
Like mentioned before the following code snippet shows the
In order for these plugins to actually work. We need to add them to plugins inside
apps/website. Please see the example below.
After registering the plugins successfully the page element now will be available in your
website app, shown in the image below:
We've successfully created a custom page element for our Page Builder app. Use similar approach to easily create a whole array of custom elements for Page Builder app.