style_manager.md

StyleManager

With Style Manager you build categories (called sectors) of CSS properties which could be used to customize the style of components. You can customize the initial state of the module from the editor initialization, by passing the following Configuration Object

const editor = grapesjs.init({
 styleManager: {
   // options
 }
})

Once the editor is instantiated you can use its API and listen to its events. Before using these methods, you should get the module from the instance.

// Listen to events
editor.on('style:sector:add', (sector) => { ... });

// Use the API
const styleManager = editor.StyleManager;
styleManager.addSector(...);

Available Events

• style:sector:add - Sector added. The Sector is passed as an argument to the callback.
• style:sector:remove - Sector removed. The Sector is passed as an argument to the callback.
• style:sector:update - Sector updated. The Sector and the object containing changes are passed as arguments to the callback.
• style:property:add - Property added. The Property is passed as an argument to the callback.
• style:property:remove - Property removed. The Property is passed as an argument to the callback.
• style:property:update - Property updated. The Property and the object containing changes are passed as arguments to the callback.
• style:target - Target selection changed. The target (or null in case the target is deselected) is passed as an argument to the callback.

Methods

• getConfig
• addSector
• getSector
• getSectors
• removeSector
• addProperty
• getProperty
• getProperties
• removeProperty
• select
• getSelected
• getSelectedAll
• getSelectedParents
• addStyleTargets
• getBuiltIn
• getBuiltInAll
• addBuiltIn
• addType
• getType
• getTypes

Sectors

getConfig

Get configuration object

Returns Object

addSector

Add new sector. If the sector with the same id already exists, that one will be returned.

Parameters

• id String Sector id

• sector Object Sector definition. Check the available properties

• options Object Options (optional, default {})

  • options.at Number? Position index (by default, will be appended at the end).

Examples

const sector = styleManager.addSector('mySector',{
  name: 'My sector',
  open: true,
  properties: [{ name: 'My property'}]
}, { at: 0 });
// With `at: 0` we place the new sector at the beginning of the list

Returns Sector Added Sector

getSector

Get sector by id.

Parameters

• id String Sector id
• opts {warn: boolean?} (optional, default {})

Examples

const sector = styleManager.getSector('mySector');

Returns (Sector | null)

getSectors

Get all sectors.

Parameters

• opts Object Options (optional, default {})

  • opts.visible Boolean? Returns only visible sectors

Examples

const sectors = styleManager.getSectors();

Returns Array<Sector>

removeSector

Remove sector by id.

Parameters

• id String Sector id

Examples

const removed = styleManager.removeSector('mySector');

Returns Sector Removed sector

addProperty

Add new property to the sector.

Parameters

• sectorId String Sector id.

• property Object Property definition. Check the base available properties + others based on the type of your property.

• opts Object Options (optional, default {})

  • opts.at Number? Position index (by default, will be appended at the end).

Examples

const property = styleManager.addProperty('mySector', {
  label: 'Minimum height',
  property: 'min-height',
  type: 'select',
  default: '100px',
  options: [
   { id: '100px', label: '100' },
   { id: '200px', label: '200' },
  ],
}, { at: 0 });

Returns (Property | null) Added property or null in case the sector doesn't exist.

getProperty

Get the property.

Parameters

• sectorId String Sector id.
• id String Property id.

Examples

const property = styleManager.getProperty('mySector', 'min-height');

Returns (Property | undefined)

getProperties

Get all properties of the sector.

Parameters

• sectorId String Sector id.

Examples

const properties = styleManager.getProperties('mySector');

Returns (Collection<Property> | undefined) Collection of properties

removeProperty

Remove the property.

Parameters

• sectorId String Sector id.
• id String Property id.

Examples

const property = styleManager.removeProperty('mySector', 'min-height');

Returns (Property | null) Removed property

select

Select new target. The target could be a Component, CSSRule, or a CSS selector string.

Parameters

• target (Component | CSSRule | String)
• opts {stylable: boolean?, component: Component?} (optional, default {})

Examples

// Select the first button in the current page
const wrapperCmp = editor.Pages.getSelected().getMainComponent();
const btnCmp = wrapperCmp.find('button')[0];
btnCmp && styleManager.select(btnCmp);

// Set as a target the CSS selector
styleManager.select('.btn > span');

Returns Array<(Component | CSSRule)> Array containing selected Components or CSSRules

getSelected

Get the last selected target. By default, the Style Manager shows styles of the last selected target.

Returns (Component | CSSRule | null)

getSelectedAll

Get the array of selected targets.

Returns Array<(Component | CSSRule)>

getSelectedParents

Get parent rules of the last selected target.

Returns Array<CSSRule>

addStyleTargets

Update selected targets with a custom style.

Parameters

• style Object Style object
• opts Object Options (optional, default {})

Examples

styleManager.addStyleTargets({ color: 'red' });

getBuiltIn

Return built-in property definition

Parameters

• prop String Property name.

Examples

const widthPropDefinition = styleManager.getBuiltIn('width');

Returns (Object | null) Property definition.

getBuiltInAll

Get all the available built-in property definitions.

Returns Object

addBuiltIn

Add built-in property definition. If the property exists already, it will extend it.

Parameters

• prop String Property name.
• definition Object Property definition.

Examples

const sector = styleManager.addBuiltIn('new-property', {
 type: 'select',
 default: 'value1',
 options: [{ id: 'value1', label: 'Some label' }, ...],
})

Returns Object Added property definition.

addType

Add new property type

Parameters

• id string Type ID
• definition Object Definition of the type.

Examples

styleManager.addType('my-custom-prop', {
   // Create UI
   create({ props, change }) {
     const el = document.createElement('div');
     el.innerHTML = '<input type="range" class="my-input" min="10" max="50"/>';
     const inputEl = el.querySelector('.my-input');
     inputEl.addEventListener('change', event => change({ event }));
     inputEl.addEventListener('input', event => change({ event, partial: true }));
     return el;
   },
   // Propagate UI changes up to the targets
   emit({ props, updateStyle }, { event, partial }) {
     const { value } = event.target;
     updateStyle(`${value}px`, { partial });
   },
   // Update UI (eg. when the target is changed)
   update({ value, el }) {
     el.querySelector('.my-input').value = parseInt(value, 10);
   },
   // Clean the memory from side effects if necessary (eg. global event listeners, etc.)
   destroy() {}
})

getType

Get type

Parameters

• id string Type ID

Returns Object Type definition

getTypes

Get all types

Returns Array