grapesjs/docs/modules/Pages.md

title
Pages

Pages

The Pages module in GrapesJS allows you to leverage the built-in support for creating a project with multiple pages and one page is always created under the hood, even if you don't need multi-page support. This allows to keep the API consistent and easier to extend in case you need to add multiple pages later.

::: warning This guide is referring to GrapesJS v0.21.1 or higher :::

toc

Initialization

The default editor initialization doesn't require any knowledge of pages and this was mainly done to avoid introducing breaking changes when the Pages module was introduced.

This is how a typical editor initialization looks like

const editor = grapesjs.init({
  container: '#gjs',
  height: '100%',
  storageManager: false,
  // CSS or a JSON of styles
  style: '.my-el { color: red }',
  // HTML string or a JSON of components
  components: '<div class="my-el">Hello world!</div>',
  // ...other config options
});

What actually is happening is that this configuration is automatically migrated to the Page Manager.

const editor = grapesjs.init({
  container: '#gjs',
  height: '100%',
  storageManager: false,
  pageManager: {
   pages: [
     {
       // without an explicit ID, a random one will be created
       id: 'my-first-page',
       // CSS or a JSON of styles
       styles: '.my-el { color: red }',
       // HTML string or a JSON of components
       component: '<div class="my-el">Hello world!</div>',
     }
  ]
 },
});

::: warning Worth noting the previous keys are style and components, where in pages you should use styles and component. :::

As you might guess, this is how initializing the editor with multiple pages would look like

const editor = grapesjs.init({
  // ...
  pageManager: {
   pages: [
     {
       id: 'my-first-page',
       styles: '.my-page1-el { color: red }',
       component: '<div class="my-page1-el">Page 1</div>',
     },
     {
       id: 'my-second-page',
       styles: '.my-page2-el { color: blue }',
       component: '<div class="my-page2-el">Page 2</div>',
     },
  ]
 },
});

GrapesJS doesn't provide any default UI for the Page Manager but you can easily built one by leveraging its APIs. Check the Customization section for more details on how to create your own Page Manager UI.

Programmatic usage

If you need to manage pages programmatically you can use its APIs.

Below an example of commonly used methods.

// Get the Pages module first
const pages = editor.Pages;

// Get an array of all pages
const allPages = pages.getAll();

// Get currently selected page
const selectedPage = pages.getSelected();

// Add a new Page
const newPage = pages.add({
  id: 'new-page-id',
  styles: '.my-class { color: red }',
  component: '<div class="my-class">My element</div>',
});

// Get the Page by ID
const page = pages.get('new-page-id');

// Select another page by ID
pages.select('new-page-id');
// or by passing the Page instance
pages.select(page);

// Get the HTML/CSS code from the page component
const component = page.getMainComponent();
const htmlPage = editor.getHtml({ component });
const cssPage = editor.getCss({ component });

// Remove the Page by ID (or by Page instance)
pages.remove('new-page-id');

Customization

By using the [Layers API][Layers API] you're able to replace the default UI with your own implementation.

All you have to do is to indicate to the editor your intent to use a custom UI and then subscribe to a few events that allow you to properly update your UI.

const editor = grapesjs.init({
    // ...
    layerManager: {
      custom: true,
      // ...
    },
});

// Use this event to append your UI in the default container provided by GrapesJS.
// You can skip this event if you don't rely on the core panels and decide to
// place the UI in some other place.
editor.on('layer:custom', (props) => {
    // props.container (HTMLElement) - The default element where you can append your UI
});

// Triggered when the root layer is changed.
editor.on('layer:root', (root) => {
    // Update the root of your UI
});

// Triggered when a component is updated, this allows you to update specific layers.
editor.on('layer:component', (component) => {
    // Update the specific layer of your UI
});

In the example below we'll replicate most of the default functionality with our own implementation.

Events

For a complete list of available events, you can check it here.