This is a step-by-step guide for anyone who wants to create their own builder with GrapesJS. This is not a comprehensive guide, just a concise overview of most common modules. Follow along to create a page builder from scratch. Skip to the end of this page to see the [final result](#final-result)
This is a step-by-step guide for anyone who wants to create their own builder with GrapesJS. This is not a comprehensive guide, just a concise overview of most common modules. Follow along to create a page builder from scratch. Skip to the end of this page to see the [final result](#final-result).
## Import the library
Before you start using GrapesJS, you'll have to import it. Let's import the latest version
Before you start using GrapesJS, you'll have to import it. Let's import the latest version:
As you can see we add our blocks via the initial configuration. Obviously there might be a case in which you would like to add them dynamically, in this case you have to use the [Block Manager API](api/block_manager.html)
As you can see we add our blocks via the initial configuration. Obviously there might be a case in which you would like to add them dynamically, in this case you have to use the [Block Manager API](api/block_manager.html):
If you want to learn more about blocks we suggest to read its dedicated article: [Block Manager Module](modules/Blocks.html)
If you want to learn more about blocks we suggest to read its dedicated article: [Block Manager Module](modules/Blocks.html).
:::
## Define Components
Technically, once you drop your HTML block inside the canvas each element of the content is transformed into a GrapesJS Component. A GrapesJS Component is an object containing information about how the element is rendered in the canvas (managed in the View) and how it might look its final code (created by the properties in the Model). Generally, all Model properties are reflected in the View. Therefore, if you add a new attribute to the model, it will be available in the export code (which we will learn more about later), and the element you see in the canvas will be updated with new attributes.
This isn't totally out of the ordinary, but the unique thing about Components that you can create a totally decoupled View. This means you can show the user whatever you desire regardless of what is in the Model. For example, by dragging a placeholder text you can fetch and show instead a dynamic content. If you want to learn more about Custom Components, you should check out [Component Manager Module](modules/Components.html).
GrapesJS comes with a few [built-in Components](modules/Components.html#built-in-component-types) that enable different features once rendered in the canvas. For example, by double clicking on an image component you will see the default [Asset Manager](modules/Assets.html), which you can customize or integrate you own. By double clicking on the text component you're able to edit it via the built-in Rich Text Editor, which is also customization and [replaceable](guides/Replace-Rich-Text-Editor.html).
GrapesJS comes with a few [built-in Components](modules/Components.html#built-in-component-types) that enable different features once rendered in the canvas. For example, by double clicking on an image component you will see the default [Asset Manager](modules/Assets.html), which you can customize or integrate you own. By double clicking on the text component you're able to edit it via the built-in Rich Text Editor, which is also customizable and [replaceable](guides/Replace-Rich-Text-Editor.html).
As we have seen before you can create Blocks directly as Components
As we have seen before you can create Blocks directly as Components:
Check out the [Panels API](api/panels.html) to see all the available methods
Check out the [Panels API](api/panels.html) to see all the available methods.
:::
## Layers
Another utility tool you might find useful when working with web elements is the layer manger. It's a tree overview of the structure nodes and enables you to manage it easier. To enable it you just have to specify where you want to render it
Another utility tool you might find useful when working with web elements is the layer manger. It's a tree overview of the structure nodes and enables you to manage it easier. To enable it you just have to specify where you want to render it.
```html{4,5,6,7,8,9,10,11}
<divclass="panel__top">
@ -296,7 +296,7 @@ const editor = grapesjs.init({
## Style Manager
Once you have defined the structure of the template the next step is the ability to style it. To meet this need GrapesJS includes the Style Manager module which is composed by CSS style properties and sectors. To make it more clear, let's see how to define a basic set.
Let's start by adding one more panel inside the `panel__right` and another one in `panel__top` which will contain a Layer/Style Manager switcher
Let's start by adding one more panel inside the `panel__right` and another one in `panel__top` which will contain a Layer/Style Manager switcher:
Inside Style Manager definition we use `buildProps` which helps us create common properties from [available built-in objects](modules/Style-manager.html#built-in-properties) then in `properties` we can override same objects (eg. passing another `name` to change the label) identified by `property` name. As you can see from `custom-prop` example it's a matter of defining the CSS `property` and the input `type`. We suggest to check a more complete example of Style Manager properties usage from the [webpage preset demo](https://github.com/artf/grapesjs/blob/gh-pages/demo.html#L1000)
Inside Style Manager definition we use `buildProps` which helps us create common properties from [available built-in objects](modules/Style-manager.html#built-in-properties) then in `properties` we can override same objects (eg. passing another `name` to change the label) identified by `property` name. As you can see from `custom-prop` example it's a matter of defining the CSS `property` and the input `type`. We suggest to check a more complete example of Style Manager properties usage from the [webpage preset demo](https://github.com/artf/grapesjs/blob/gh-pages/demo.html#L1000).
::: tip
Check the [Style Manager API](api/panels.html) to see how to update sectors and properties dynamically
Check the [Style Manager API](api/panels.html) to see how to update sectors and properties dynamically.
:::
<!--
@ -440,7 +440,7 @@ Each component can also indicate what to style and what not.
## Traits
Most of the time you would style your components and place them somewhere in the structure, but sometimes your components might need custom attributes or even custom behaviors and for this need you can make use of traits. Traits are commonly used to update HTML element attributes (eg. `placeholder` for inputs or `alt` for images), but you can also define your own custom traits. Access the selected Component model and do whatever you want. For this guide, we going to show you how to render available traits, for more details on how to extend them we suggest you read the [Trait Manager Module page](modules/Traits.html).
Let's create a new container for traits. Tell the editor where to render it and update the sidebar switcher
Let's create a new container for traits. Tell the editor where to render it and update the sidebar switcher:
Now if you switch to the Trait panel and select one of the inner components you should see its default traits.
## Responsive templates
GrapesJS implements a module which allows you to work with responsive templates easily. Let's see how to define different devices and a button for device switching
GrapesJS implements a module which allows you to work with responsive templates easily. Let's see how to define different devices and a button for device switching:
```html{3}
<divclass="panel__top">
@ -597,13 +597,13 @@ editor.setDevice('Mobile');
```
::: tip
Check out the [Device Manager API](api/device_manager.html) to see all the available methods
Check out the [Device Manager API](api/device_manager.html) to see all the available methods.
:::
## Store & load data
Once you have finished with defining your builder interface the next step would be to setup the storing and loading process.
GrapesJS implements 2 simple type of storages inside its Storage Manager: The local (by using `localStorage`, active by default) and the remote one. Those are enough to cover most of the cases, but it's also possible to add new implementations ([grapesjs-indexeddb](https://github.com/artf/grapesjs-indexeddb) is a good example).
Let's see how the default options work
Let's see how the default options work:
```js
grapesjs.init({
@ -624,7 +624,7 @@ grapesjs.init({
It is worth noting that the default `id` parameter adds a prefix for all keys to store. If you check the `localStorage` inside the devtool panel you'll see something like `{ 'gjs-components': '....' ...}` this way it lessens the risk of collisions.
Let's look at the configuration required to setup the remote storage
Let's look at the configuration required to setup the remote storage:
```js
grapesjs.init({
@ -640,7 +640,7 @@ grapesjs.init({
});
```
As you might noticed, we've left some default options unchanged: Increased changes necessary for autosave triggering and passed remote endpoints.
If you prefer you could also disable the autosaving and you can do so using a custom command
If you prefer you could also disable the autosaving and you can do so using a custom command:
```js
// ...
@ -664,10 +664,10 @@ If you prefer you could also disable the autosaving and you can do so using a cu
// ...
```
To get a better overview of the Storage Manager and how you should store/load the template, or how to define new storages you should read the [Storage Manager Module](modules/Storage.html) page
To get a better overview of the Storage Manager and how you should store/load the template, or how to define new storages you should read the [Storage Manager Module](modules/Storage.html) page.
## Theming
One last step that might actually improve a lot your editor personality is how it's look visually. To achieve an easy theming we have adapted an atomic design for this purpose. To customize the main palette of colors all you have to do is to change few CSS rules. Alternatively if you include GrapesJS styles via SCSS you can make use of its [internal variables](https://github.com/artf/grapesjs/blob/dev/src/styles/scss/_gjs_variables.scss) and declare your variables before the import
One last step that might actually improve a lot your editor personality is how it looks visually. To achieve an easy theming we have adapted an atomic design for this purpose. To customize the main palette of colors all you have to do is to change few CSS rules. Alternatively if you include GrapesJS styles via SCSS you can make use of its [internal variables](https://github.com/artf/grapesjs/blob/dev/src/styles/scss/_gjs_variables.scss) and declare your variables before the import:
```scss
// Put your variables before the GrapesJS style import
@ -684,7 +684,7 @@ $quaternaryColor: #d278c9;
```
In case of a simple CSS you'll have to put your rules after the GrapesJS styles.
To complete our builder let's customize its color palette and to make it more visually "readable" we can replace all button labels with SVG icons
To complete our builder let's customize its color palette and to make it more visually "readable" we can replace all button labels with SVG icons:
```css
/* We can remove the border we've set at the beginnig */
@ -716,7 +716,7 @@ To complete our builder let's customize its color palette and to make it more vi
Erik Demaine
4 years ago
GitHub