Symbols plugin for GrapesJS

This plugin adds feature to GrapesJS editor, for users to be able to reuse elements in a website and accross pages

This code is part of a bigger project: Silex v3 which aims to be a free/libre alternative to webflow

Links

• DEMO on Codepen
• Npm package
• Discussion about this plugins and Symbols, bug report etc
• Discussion about ongoing developments

Features

• Create a symbol from an element
• Create symbol instances
• Sync instances: when one instance is modified, update all other instances
• Temporary pause sync
• Unlink an instance so that is stops syncing
• Symbol have a name and an icon
• View symbol icon for all instances in the layer manager
• Optional list of symbols which support draging symbols to the stage
• Support for symbols in symbols
• Support sync accross grapesjs pages

HTML

<link href="https://unpkg.com/grapesjs/dist/css/grapes.min.css" rel="stylesheet">
<script src="https://unpkg.com/grapesjs"></script>
<script src="https://unpkg.com/@silexlabs/grapesjs-symbols"></script>

<div id="gjs"></div>

JS

const editor = grapesjs.init({
	container: '#gjs',
  height: '100%',
  fromElement: true,
  storageManager: false,
  plugins: ['@silexlabs/grapesjs-symbols'],
  pluginsOpts: {
    '@silexlabs/grapesjs-symbols': {
      appendTo: '.gjs-pn-views-container',
    },
  },
})

CSS

body, html {
  margin: 0;
  height: 100%;
}

Add a UI

Add a button to create a new symbol

<div id='basic-actions' class="panel__basic-actions" style="z-index: 9; background: red; position: absolute; min-height: 500px"></div>

And the JS for the button

var idx = 0
editor.on('load', () => {
  editor.Panels.addPanel({
    id: 'basic-actions',
    el: '.panel__basic-actions',
    buttons: [
      {
        id: 'alert-button',
        className: 'btn-alert-button',
        label: 'Create symbol pink',
        command(editor) {
          var label = prompt('Label', 'Symbol ' + ++idx)
          var icon = prompt('Icon', 'fa-list')
          editor.runCommand('symbols:add', { label, icon })
        }
      },
    ]
  })
})

Add some content programmatically if you need to

editor.addComponents(`
  <div class="main">
    <h1 class="title">Test title</h1>
    <p class="content">Test content text lorem ipsum</p>
  </div>
`)

Test the plugin

Select a component on the stage, click on "Create symbol", then duplicate the component or drag and drop the symbol on the stage

Finally change the content of the compoenent or add/remove classes or attributes for all the instances to be updated as well

Summary

TBD

• Plugin name: @silexlabs/grapesjs-symbols
• Components
  • component-id-1
  • component-id-2
  • ...
• Blocks
  • block-id-1
  • block-id-2
  • ...

Vocabulary

A symbol is a structure holding the symbol data, see the comment in the Symbol module

A symbol model is a grapesjs Component which is not attached to the DOM and is used to create instances of a symbol

An instance is a grapesjs Component which is in sync with a Symbol, it is a root component with child components which are also synced between symbols

About IDs

These are the IDs we need in models attributes

• Each Symbol has symbolId
• Each instance (the root component) has symbolId set to its symbol cid, this is used to find the symbol associated to this instance
• Each model also has the symbolId set to its symbol cid
• Each child of an instance has symbolChildId set to the same ID in all the symbols, this is used to sync the symbol instances children

Notes

• symbolChildId attributes are not synced between symbol instances (the root of a symbol instance) since it can be different when an instance is in two different other symbols
• In a collection of Symbol, you can get the symbol with .get(symbolId) since the symbols have their cid set to their initial symbolId - see the initialize method in Symbol.ts

Options

TBD

Option	Description	Default
appendTo	CSS selector to choose where to attach the list of symbols.	#symbols
emptyText	A text to be displayed when there is no symbols in the list.	No symbol yet.
primaryColor	Color for the UI (list of symbols and traits in the property manager)	#b9a5a6
secondaryColor	Color for the UI (list of symbols and traits in the property manager)	#463a3c
highlightColor	Color for the UI (list of symbols and traits in the property manager)	#d97aa6

Download

• CDN
  • https://unpkg.com/@silexlabs/grapesjs-symbols
• NPM
  • npm i @silexlabs/grapesjs-symbols
• GIT
  • git clone https://github.com/silexlabs/grapesjs-symbols.git

Development

Clone the repository

$ git clone https://github.com/silexlabs/grapesjs-symbols.git
$ cd grapesjs-symbols

Install dependencies

$ npm i

Start the dev server

$ npm start

Build the source

$ npm run build

License

AGPL-v3