Page manager

[artf]

Hi guys, this PR introduces the new Pages module in GrapesJS but besides that, it also includes a lot of improvements and refactoring inside the editor which was necessary to make this module work properly. In order to use this module, you will probably need to update the way you initialize and store your project but the good news is that you should be able to continue to use the old way without a big difference.

The new module is focused only on API and no UI was introduced but you can easily make your own as you can see from this demo https://codepen.io/artf/pen/XWpJQoY

Initialization

In order to use the module, you have to change the way the editor is initialized.

Before

Current possible ways of initialization

// Loading content from the inline data
grapesjs.init({
  // ...
  container : '#gjs',
  components: '<div class="txt-red">Hello world!</div>', // or JSON of components
  style: '.txt-red{color: red}', // or JSON of styles
  // or getting the content from the container element
  fromElement: true,
});


// Loading content from the storage
grapesjs.init({
  // ...
  storageManager: { // eg. using the remote storage
    type: 'remote',
    urlStore: 'http://endpoint/store-project/id-123',
    urlLoad: 'http://endpoint/load-project/id-123',
  },
});

After

// Loading content from the inline data
grapesjs.init({
  // ...
  container : '#gjs',
  pageManager: {
    pages: [
      {
        id: 'page-1', // id is mandatory
        // The page can contain multiple frames but as multi-framing API are not yet ready you
        // can declare pages as the page 2 below
        frames: [{
          component: '<div class="txt-red">Hello world!</div>', // or JSON of components
          styles: '.txt-red{color: red}', // or JSON of styles
         }],
       }, {
         id: 'page-2',
         component: '...',
         styles: '...',
       }
     ]
  },
  // `fromElement` option is ignored in case of `pageManager` in initialization
});


// Loading content from the storage
grapesjs.init({
  // ...
  storageManager: {...},
  pageManager: true,
});

Changes in the Storage structure

Currently, the Storage module is creating this kind of structure for your editor project (the JSON you're storing/loading)

{
  // ...
  components: '...',
  styles: '...',
  html: '...',
  css: '...',
}

With the Pages module, things are slightly different

{
  // ...
  styles: '...',
  pages: '...',
}

As you can see, with Pages module enabled, you'll get now only styles and pages as the representation of your project. Styles are kept global across all the pages (this lets you reuse styles across all the pages) and the pages key contains the array of pages, where each page is:

{
 id: 'page-id',
 frames: [{
   component: { type: 'wrapper', ...}, // GrapesJS never stored data about the `wrapper`, now it does
   html: '...',
   css: '...', 
 }]
}

Possible breaking changes

Before the introduction of the Page module, GrapesJS was creating the main Wrapper component (the one containing your components) right at the initialization step (before loading plugins) this could allow plugins calling methods like editor.getComponents() or editor.getHtml() even before the load of project data

// some plugin
export default (editor) => {
  // ...
  editor.getComponents().... // trying to do stuff before data are completely loaded
  // ...
}

Now with the Pages module, this step was refactored and the creation of wrappers is actually happening once the data are loaded. Indeed, this actually allows you to extend the Wrapper component, something that wasn't possible at all. So, with this new approach, if in your plugin you have to access components, you have to do it once the editor is loaded.

// some plugin
export default (editor) => {
  // ...
  editor.on('load', () => {
     editor.getComponents()....
  })
}