diff --git a/docs/api/property_stack.md b/docs/api/property_stack.md index e96544873..3e13419ae 100644 --- a/docs/api/property_stack.md +++ b/docs/api/property_stack.md @@ -10,7 +10,7 @@ * `layerSeparator` **([String][1] | [RegExp][2])?** The separator used to split layer values. * `layerJoin` **[String][1]?** Value used to join layer values. -* `layerLabel` **[Function][3]?** Custom logic for creating the layer value. +* `layerLabel` **[Function][3]?** Custom logic for creating the layer label. ### getLayers diff --git a/docs/api/style_manager.md b/docs/api/style_manager.md index 0e6e1c9e4..95ecd8483 100644 --- a/docs/api/style_manager.md +++ b/docs/api/style_manager.md @@ -50,19 +50,16 @@ Returns **[Object][16]** ## addSector -Add new sector to the collection. If the sector with the same id already exists, -that one will be returned. +Add new sector. If the sector with the same id already exists, that one will be returned. ### Parameters -* `id` **[string][17]** Sector id -* `sector` **[Object][16]** Object representing sector - - * `sector.name` **[string][17]** Sector's label (optional, default `''`) - * `sector.open` **[Boolean][18]** Indicates if the sector should be opened (optional, default `true`) - * `sector.properties` **[Array][19]<[Object][16]>** Array of properties (optional, default `[]`) +* `id` **[String][17]** Sector id +* `sector` **[Object][16]** Sector definition. Check the [available properties][18] * `options` **[Object][16]** Options (optional, default `{}`) + * `options.at` **[Number][19]?** Position index (by default, will be appended at the end). + ### Examples ```javascript @@ -71,18 +68,18 @@ const sector = styleManager.addSector('mySector',{ open: true, properties: [{ name: 'My property'}] }, { at: 0 }); -// With `at: 0` we place the new sector at the beginning of the collection +// With `at: 0` we place the new sector at the beginning of the list ``` Returns **[Sector]** Added Sector ## getSector -Get sector by id +Get sector by id. ### Parameters -* `id` **[string][17]** Sector id +* `id` **[String][17]** Sector id * `opts` (optional, default `{}`) ### Examples @@ -95,11 +92,11 @@ Returns **([Sector] | null)** ## removeSector -Remove a sector by id +Remove sector by id. ### Parameters -* `id` **[string][17]** Sector id +* `id` **[String][17]** Sector id ### Examples @@ -111,7 +108,7 @@ Returns **[Sector]** Removed sector ## getSectors -Get all sectors +Get all sectors. ### Parameters @@ -127,51 +124,33 @@ Returns **Collection<[Sector]>** Collection of sectors ## addProperty -Add property to the sector identified by id +Add new property to the sector. ### Parameters -* `sectorId` **[string][17]** Sector id -* `property` **[Object][16]** Property object - - * `property.name` **[string][17]** Name of the property (optional, default `''`) - * `property.property` **[string][17]** CSS property, eg. `min-height` (optional, default `''`) - * `property.type` **[string][17]** Type of the property: integer | radio | select | color | file | composite | stack (optional, default `''`) - * `property.units` **[Array][19]<[string][17]>** Unit of measure available, eg. \['px','%','em']. Only for integer type (optional, default `[]`) - * `property.unit` **[string][17]** Default selected unit from `units`. Only for integer type (optional, default `''`) - * `property.min` **[number][20]** Min possible value. Only for integer type (optional, default `null`) - * `property.max` **[number][20]** Max possible value. Only for integer type (optional, default `null`) - * `property.defaults` **[string][17]** Default value (optional, default `''`) - * `property.info` **[string][17]** Some description (optional, default `''`) - * `property.icon` **[string][17]** Class name. If exists no text will be displayed (optional, default `''`) - * `property.preview` **[Boolean][18]** Show layers preview. Only for stack type (optional, default `false`) - * `property.functionName` **[string][17]** Indicates if value need to be wrapped in some function, for istance `transform: rotate(90deg)` (optional, default `''`) - * `property.properties` **[Array][19]<[Object][16]>** Nested properties for composite and stack type (optional, default `[]`) - * `property.layers` **[Array][19]<[Object][16]>** Layers for stack properties (optional, default `[]`) - * `property.list` **[Array][19]<[Object][16]>** List of possible options for radio and select types (optional, default `[]`) +* `sectorId` **[String][17]** Sector id. +* `property` **[Object][16]** Property definition. Check the [base available properties][20] + others based on the `type` of your property. * `opts` (optional, default `{}`) * `options` **[Object][16]** Options (optional, default `{}`) + * `options.at` **[Number][19]?** Position index (by default, will be appended at the end). + ### Examples ```javascript -var property = styleManager.addProperty('mySector',{ - name: 'Minimum height', +const property = styleManager.addProperty('mySector', { + label: 'Minimum height', property: 'min-height', type: 'select', - defaults: '100px', - list: [{ - value: '100px', - name: '100', - },{ - value: '200px', - name: '200', - }], + default: '100px', + options: [ + { id: '100px', label: '100' }, + { id: '200px', label: '200' }, + ], }, { at: 0 }); -// With `at: 0` we place the new property at the beginning of the collection ``` -Returns **(Property | null)** Added Property or `null` in case sector doesn't exist +Returns **([Property] | null)** Added property or `null` in case the sector doesn't exist. ## getProperty @@ -291,7 +270,7 @@ Returns **[Object][16]** Type definition Get all types -Returns **[Array][19]** +Returns **[Array][21]** ## createType @@ -318,6 +297,44 @@ someContainer.appendChild(propView.el); Returns **PropertyView** +## getBuiltIn + +Return built-in property definition + +### Parameters + +* `prop` **[String][17]** Property name. + +Returns **([Object][16] | null)** Property definition. + +## getBuiltInAll + +Get all the available built-in property definitions. + +Returns **[Object][16]** + +## addBuiltIn + +Add built-in property definition. +If the property exists already, it will extend it. + +### Parameters + +* `prop` **[String][17]** Property name. +* `definition` **[Object][16]** Property definition. + +### Examples + +```javascript +const sector = styleManager.addBuiltIn('new-property', { + type: 'select', + default: 'value1', + options: [{ id: 'value1', label: 'Some label' }, ...], +}) +``` + +Returns **[Object][16]** Added property definition. + [1]: https://github.com/artf/grapesjs/blob/master/src/style_manager/config/config.js [2]: #getconfig @@ -352,8 +369,10 @@ Returns **PropertyView** [17]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[18]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[18]: sector.html#properties + +[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number -[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[20]: property.html#properties -[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number +[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/docs/modules/Style-manager.md b/docs/modules/Style-manager.md index bef313c18..85251799a 100644 --- a/docs/modules/Style-manager.md +++ b/docs/modules/Style-manager.md @@ -286,6 +286,10 @@ editor.StyleManager.getBuiltInAll(); ``` ::: + + + + ## I18n If you're planning to have a multi-language editor you can easily connect sector and property labels to the [I18n] module via their IDs. @@ -343,6 +347,10 @@ grapesjs.init({ }); ``` + + + + ## Components constraints When you define custom components you can also indicate, via `stylable` and `unstylable` props, which CSS properties should be available for styling. In that case, the Style Manager will only show the available properties. If the sector doesn't contain any available property, it won't be shown. @@ -396,34 +404,48 @@ grapesjs.init({ }); ``` + + + + ## Programmatic usage +For a more advanced usage you can rely on the [Style Manager API] to perform different kind of actions related to the module. + +* Managing sectors/properties post-initialization. + ```js + // Get the module from the editor instance + const sm = editor.StyleManager; + + // Add new sector + const newSector = sm.addSector('sector-id', { + name: 'New sector', + open: true, + properties: ['width'], + }); + + // Add new property to the sector + sm.addProperty('sector-id', { + type: 'number', + property: 'min-width', + }); + + // Remove sector + sm.removeSector('sector-id'); + ``` + * Change target * Get current selected target ## Customization -## Events -Here you can find all the available built-in properties that you can use inside Style Manager via `buildProps`: -`float`, `position`, `text-align`, `display`, `font-family`, `font-weight`, `border`, `border-style`, `border-color`, `border-width`, `box-shadow`, `background-repeat`, `background-position`, `background-attachment`, `background-size`, `transition`, `transition-duration`, `transition-property`, `transition-timing-function`, `top`, `right`, `bottom`, `left`, `margin`, `margin-top`, `margin-right`, `margin-bottom`, `margin-left`, `padding`, `padding-top`, `padding-right`, `padding-bottom`, `padding-left`, `width`, `height`, `min-width`, `min-height`, `max-width`, `max-height`, `font-size`, `letter-spacing`, `line-height`, `text-shadow`, `border-radius`, `border-top-left-radius`, `border-top-right-radius`, `border-bottom-left-radius`, `border-bottom-right-radius`, `perspective`, `transform`, `transform-rotate-x`, `transform-rotate-y`, `transform-rotate-z`, `transform-scale-x`, `transform-scale-y`, `transform-scale-z`, `color`, `background-color`, `background`, `background-image`, `cursor`, `flex-direction`, `flex-wrap`, `justify-content`, `align-items`, `align-content`, `order`, `flex-basis`, `flex-grow`, `flex-shrink`, `align-self`, `overflow`, `overflow-x`, `overflow-y` -Example usage: -```js -... - styleManager : { - sectors: [{ - name: 'Dimension', - buildProps: ['width', 'min-height'] - },{ - name: 'Extra', - buildProps: ['background-color', 'box-shadow'] - }] - } -... -``` +## Events + +For a complete list of available events, you can check it [here](/api/style_manager.html#available-events). [Components]: diff --git a/src/style_manager/index.js b/src/style_manager/index.js index 11ab15d7f..d7d317995 100644 --- a/src/style_manager/index.js +++ b/src/style_manager/index.js @@ -145,22 +145,19 @@ export default () => { }, /** - * Add new sector to the collection. If the sector with the same id already exists, - * that one will be returned. - * @param {string} id Sector id - * @param {Object} sector Object representing sector - * @param {string} [sector.name=''] Sector's label - * @param {Boolean} [sector.open=true] Indicates if the sector should be opened - * @param {Array} [sector.properties=[]] Array of properties - * @param {Object} [options={}] Options - * @return {[Sector]} Added Sector + * Add new sector. If the sector with the same id already exists, that one will be returned. + * @param {String} id Sector id + * @param {Object} sector Sector definition. Check the [available properties](sector.html#properties) + * @param {Object} [options={}] Options + * @param {Number} [options.at] Position index (by default, will be appended at the end). + * @returns {[Sector]} Added Sector * @example * 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 collection + * // With `at: 0` we place the new sector at the beginning of the list * */ addSector(id, sector, options = {}) { let result = this.getSector(id); @@ -174,9 +171,9 @@ export default () => { }, /** - * Get sector by id - * @param {string} id Sector id - * @return {[Sector]|null} + * Get sector by id. + * @param {String} id Sector id + * @returns {[Sector]|null} * @example * const sector = styleManager.getSector('mySector'); * */ @@ -187,9 +184,9 @@ export default () => { }, /** - * Remove a sector by id - * @param {string} id Sector id - * @return {[Sector]} Removed sector + * Remove sector by id. + * @param {String} id Sector id + * @returns {[Sector]} Removed sector * @example * const removed = styleManager.removeSector('mySector'); */ @@ -198,7 +195,7 @@ export default () => { }, /** - * Get all sectors + * Get all sectors. * @returns {Collection<[Sector]>} Collection of sectors * @example * const sectors = styleManager.getSectors(); @@ -208,41 +205,23 @@ export default () => { }, /** - * Add property to the sector identified by id - * @param {string} sectorId Sector id - * @param {Object} property Property object - * @param {string} [property.name=''] Name of the property - * @param {string} [property.property=''] CSS property, eg. `min-height` - * @param {string} [property.type=''] Type of the property: integer | radio | select | color | file | composite | stack - * @param {Array} [property.units=[]] Unit of measure available, eg. ['px','%','em']. Only for integer type - * @param {string} [property.unit=''] Default selected unit from `units`. Only for integer type - * @param {number} [property.min=null] Min possible value. Only for integer type - * @param {number} [property.max=null] Max possible value. Only for integer type - * @param {string} [property.defaults=''] Default value - * @param {string} [property.info=''] Some description - * @param {string} [property.icon=''] Class name. If exists no text will be displayed - * @param {Boolean} [property.preview=false] Show layers preview. Only for stack type - * @param {string} [property.functionName=''] Indicates if value need to be wrapped in some function, for istance `transform: rotate(90deg)` - * @param {Array} [property.properties=[]] Nested properties for composite and stack type - * @param {Array} [property.layers=[]] Layers for stack properties - * @param {Array} [property.list=[]] List of possible options for radio and select types + * Add new property to the sector. + * @param {String} sectorId Sector id. + * @param {Object} property Property definition. Check the [base available properties](property.html#properties) + others based on the `type` of your property. * @param {Object} [options={}] Options - * @return {Property|null} Added Property or `null` in case sector doesn't exist + * @param {Number} [options.at] Position index (by default, will be appended at the end). + * @returns {[Property]|null} Added property or `null` in case the sector doesn't exist. * @example - * var property = styleManager.addProperty('mySector',{ - * name: 'Minimum height', + * const property = styleManager.addProperty('mySector', { + * label: 'Minimum height', * property: 'min-height', * type: 'select', - * defaults: '100px', - * list: [{ - * value: '100px', - * name: '100', - * },{ - * value: '200px', - * name: '200', - * }], + * default: '100px', + * options: [ + * { id: '100px', label: '100' }, + * { id: '200px', label: '200' }, + * ], * }, { at: 0 }); - * // With `at: 0` we place the new property at the beginning of the collection */ addProperty(sectorId, property, opts = {}) { const sector = this.getSector(sectorId, { warn: 1 });