diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index c3adffcc8..2113b1182 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -112,6 +112,7 @@ module.exports = { ['/modules/I18n', 'I18n'], ['/modules/Selectors', 'Selectors'], ['/modules/Layers', 'Layers'], + ['/modules/Pages', 'Pages'], ['/modules/Style-manager', 'Style Manager'], ['/modules/Storage', 'Storage Manager'], ['/modules/Modal', 'Modal'], diff --git a/docs/modules/Pages.md b/docs/modules/Pages.md new file mode 100644 index 000000000..6868bacde --- /dev/null +++ b/docs/modules/Pages.md @@ -0,0 +1,384 @@ +--- +title: Pages +--- + +# Pages + +The Layer Manager module is responsible to manage and display your [Components] as a tree. + +::: warning +This guide is referring to GrapesJS v0.21.1 or higher +::: + +[[toc]] + + +## Configuration + +To change the default configurations you have to pass the `layerManager` option with the main configuration object. + +```js +const editor = grapesjs.init({ + ... + layerManager: { + ... + } +}); +``` + +You can check here the full list of available configuration options: [Layer Manager Config](https://github.com/GrapesJS/grapesjs/blob/master/src/navigator/config/config.ts) + + +Layers are a direct representation of your components, therefore they will only be available once your components are loaded in the editor (eg. you might load your project data from a remote endpoint). + +In your configuration, you're able to change the global behavior of layers (eg. make all the layers not sortable) and also decide which component layer should be used as a root. + +```js +const editor = grapesjs.init({ + ... + layerManager: { + // If the `root` is not specified or the component element is not found, + // the main wrapper component will be used. + root: '#my-custom-root', + sortable: false, + hidable: false, + } +}); +``` + +The configurations are mainly targeting the default UI provided by GrapesJS core, in case you need more control over the tree of your layers, you can read more in the [Customization](#customization) section below. + + + +## Programmatic usage + +If you need to manage layers programmatically you can use its [APIs][Layers API]. + + + + + +## 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. + +```js +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](/api/layer_manager.html#available-events). + + +[Components]: +[Layers API]: