Visual page framework GrapesJS development tutorial (3) - integration with Drupal CMS

This article is an introduction to the visualization of page building tools GrapesJS development tutorial series of components, this series is mainly about the development of GrapesJS and how to dock GrapesJS visualization to other systems, such as how to integrate with CMS and other related content.

We have previously introduced several articles on the basic development of GrapesJS, including architecture, component development, etc., this article mainly introduces how to integrate with Drupal, so as to achieve rapid editing and production of Drupal's pages, LandingPage, etc., through the GrapesJS and Drupal, to achieve the purpose of building a station quickly.

In the previous article, we explained that there are two important elements in a GrapesJS component: the Component and the Block.

Component defines what the label of a component is, what properties and methods it has, how it is displayed in Canvas, and what the result should be when saved as HTML.

A Block is understood to be a “code snippet” consisting of one or more Components.

Then the integration with Drupal, we focus on providing Block and Component through Drupal, so there are also two modes of integration

1. Create Block only.

Since GrapesJS has implemented the common HTML elements of Component, so some static components can be built directly through Block. For example, a static Hero, a three-column Showcase, a billboard and so on. This approach has obvious advantages , development is simple , because the component is the regular HTML + CSS composition , the user can also easily edit the content of which the disadvantage is that only static content can be achieved for dynamic components are not applicable.

2. Twig Basic Component.

It can implement Twig's parser and Component, so that GrapesJS can recognize some syntax of Twig and realize the editing of dynamic components. Through a certain mapping relationship, the user can use GJS to edit the parameters of the twig component, in this way, the developer in the development of the component only need to decide what parameters exposed to the user, the user does not need to care about how to make the component have a good display, focusing on the content construction. However, the disadvantage of this approach is also obvious: there is usually a big gap between the preview of the component and the actual page, e.g. the preview may just be a placeholder block.

We have implemented a framework for building GJS components in Drupal. A new widget directory has been added to Drupal's docroot, which has the same mechanism and structure as a module, so let's take a look at a concrete example:

We looked for a timer component of the complete code, which contains the comments of each step, through the entire code example, you can fully understand the basic process of GrapesJS component development, specific reference is as follows:

widget
    |- hero
       |- hero.info.yml
       |- hero.lib.yml
       |- hero.twig
       |- hero.js
       |- hero.css
    

This is the directory structure of the Drupal module, you can dynamically register components by means of plugin, focusing on the following files:

1. hero.info.yml Indicates that this is a widget, and when the .info.yml file is detected, hero is used as the machine name for this component.

# hero.info.yml
    name: Hero
    description: "Hero block"
    type: widget
    category: hero
    

2. hero.lib.yml It defines the js and css used by the component.

# hero.lib.yml
    css:
      hero.css: {}
    js:
      hero.js: {}
    

3. hero.twigis the template for this component.

The name is fixed {machine_name}.twig. When parsing the component, the API takes the content in hero.twig and returns it to GrapesJS, and according to the above mentioned, the content can be normal HTML, Twig language, or even a mixin. GrapesJS automatically converts the content when parsing it to the corresponding Component

Here we make a special Component to enhance the use of these components. We create a component type called twig_widget, all Drupal widgets will be parsed into this type by default. twig_widget is a closed component, users can not add or remove components, all the content exists as a whole, the user can only edit the properties exposed by the component. 
This usage can be understood as a ‘component reference’, when a component has a style update or a functionality update (the update must be forward compatible, if there is a Breaking change, a new component must be created), the user does not need to re-edit, the page will automatically get the update.

Taking the hero component as an example, the HTML exported by GrapesJS would look like this

In the future, once HERO has HTML changes, or CSS adjustments, users will not need to re-edit component content as long as the parameters it receives remain the same.
What if the user needs to change some of its content? twig_widget provides a method eject, once the user clicks on this method, twig_widget will extract the content and break it into small independent components by GJS parsing. This operation is not reversible, once executed, it means that all subsequent HERO updates will not take effect on this page's HERO.
After executing eject, GJS exports the HTML result as follows:

GrapesJS has parsed the hero as a div container with an img component, an h1 caption, an h3 caption, and a twig syntax block. The user can delete the h3 title, add another image to it, etc.

The two modes want to combine, flexible use, basically can cover most of the scene requirements. In general, a website UI should maintain consistency, so the use of ‘reference’ way to ensure this effect, but sometimes a special page may need to make some changes to a component, you can use mode two, on the basis of retaining the original component framework, to make some customisation.

It's not easy to create.Reprinted with attribution!

For more on GrapesJS development and Drupal CMS, see our other related articles.