diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 9efef9b3c..7435821a5 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -73,6 +73,7 @@ module.exports = { ['/api/page', `${subDivider}Page`], ['/api/style_manager', 'Style Manager'], ['/api/sector', `${subDivider}Sector`], + ['/api/property', `${subDivider}Property`], ['/api/storage_manager', 'Storage Manager'], ['/api/device_manager', 'Device Manager'], ['/api/device', `${subDivider}Device`], diff --git a/docs/api.js b/docs/api.js index 988498f4b..797bdabe6 100644 --- a/docs/api.js +++ b/docs/api.js @@ -22,6 +22,7 @@ async function generateDocs () { ['panels/index.js', 'panels.md'], ['style_manager/index.js', 'style_manager.md'], ['style_manager/model/Sector.js', 'sector.md'], + ['style_manager/model/Property.js', 'property.md'], ['storage_manager/index.js', 'storage_manager.md'], ['device_manager/index.js', 'device_manager.md'], ['device_manager/model/Device.js', 'device.md'], diff --git a/docs/api/component.md b/docs/api/component.md index 89efdf8d5..1c8e1df6b 100644 --- a/docs/api/component.md +++ b/docs/api/component.md @@ -28,10 +28,10 @@ component.get('tagName'); * `attributes` **[Object][2]?** Key-value object of the component's attributes, eg. `{ title: 'Hello' }` Default: `{}` * `name` **[String][1]?** Name of the component. Will be used, for example, in Layers and badges * `removable` **[Boolean][3]?** When `true` the component is removable from the canvas, default: `true` -* `draggable` **([Boolean][3] | [String][1])?** Indicates if it's possible to drag the component inside others. +* `draggable` **([Boolean][3] | [String][1] | [Function][4])?** Indicates if it's possible to drag the component inside others. You can also specify a query string to indentify elements, eg. `'.some-class[title=Hello], [data-gjs-type=column]'` means you can drag the component only inside elements - containing `some-class` class and `Hello` title, and `column` components. Default: `true` + containing `some-class` class and `Hello` title, and `column` components. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drag is possible. Default: `true` * `droppable` **([Boolean][3] | [String][1] | [Function][4])?** Indicates if it's possible to drop other components inside. You can use a query string as with `draggable`. In the case of a function, target and destination components are passed as arguments, return a Boolean to indicate if the drop is possible. Default: `true` * `badgable` **[Boolean][3]?** Set to false if you don't want to see the badge (with the name) over the component. Default: `true` @@ -485,9 +485,41 @@ component.parent(); Returns **([Component][9] | null)** +### getTraits + +Get traits. + +#### Examples + +```javascript +const traits = component.getTraits(); +console.log(traits); +// [Trait, Trait, Trait, ...] +``` + +Returns **[Array][5]\** + +### setTraits + +Replace current collection of traits with a new one. + +#### Parameters + +* `traits` **[Array][5]<[Object][2]>** Array of trait definitions + +#### Examples + +```javascript +const traits = component.setTraits([{ type: 'checkbox', name: 'disabled'}, ...]); +console.log(traits); +// [Trait, ...] +``` + +Returns **[Array][5]\** + ### getTrait -Get the trait by id/name +Get the trait by id/name. #### Parameters @@ -500,11 +532,11 @@ const traitTitle = component.getTrait('title'); traitTitle && traitTitle.set('label', 'New label'); ``` -Returns **Trait** Trait model +Returns **(Trait | null)** Trait getModelToStyle ### updateTrait -Update a trait +Update a trait. #### Parameters @@ -555,11 +587,11 @@ component.removeTrait('title'); component.removeTrait(['title', 'id']); ``` -Returns **[Array][5]** Array of removed traits +Returns **[Array][5]\** Array of removed traits ### addTrait -Add trait/s by id/s. +Add new trait/s. #### Parameters @@ -577,7 +609,7 @@ component.addTrait({ component.addTrait(['title', {...}, ...]); ``` -Returns **[Array][5]** Array of added traits +Returns **[Array][5]\** Array of added traits ### getName diff --git a/docs/api/css_rule.md b/docs/api/css_rule.md index fcc791e43..fddfae028 100644 --- a/docs/api/css_rule.md +++ b/docs/api/css_rule.md @@ -14,7 +14,7 @@ * `singleAtRule` **[Boolean][4]?** This property is used only on at-rules, like 'page' or 'font-face', where the block containes only style declarations * `state` **[String][3]?** State of the rule, eg: `hover`, `focused` * `important` **([Boolean][4] | [Array][1]<[String][3]>)?** If true, sets `!important` on all properties. You can also pass an array to specify properties on which use important -* `stylable` **[Boolean][4]?** Indicates if the rule is stylable from the editor +* `stylable` **[Boolean][4]?** Indicates if the rule is stylable from the editor[Device]: device.html[State]: state.html[Component]: component.html ### getAtRule @@ -72,6 +72,45 @@ cssRule.getDeclaration() // ".class1{color:red;}" Returns **[String][3]** +### getDevice + +Get the Device the rule is related to. + +#### Examples + +```javascript +const device = rule.getDevice(); +console.log(device?.getName()); +``` + +Returns **([Device] | null)** + +### getState + +Get the State the rule is related to. + +#### Examples + +```javascript +const state = rule.getState(); +console.log(state?.getLabel()); +``` + +Returns **([State] | null)** + +### getComponent + +Returns the related Component (valid only for component-specific rules). + +#### Examples + +```javascript +const cmp = rule.getComponent(); +console.log(cmp?.toHTML()); +``` + +Returns **([Component] | null)** + ### toCSS Return the CSS string of the rule diff --git a/docs/api/property.md b/docs/api/property.md new file mode 100644 index 000000000..8ba102c93 --- /dev/null +++ b/docs/api/property.md @@ -0,0 +1,122 @@ + + +## Property + + + +### Properties + +* `id` **[String][1]** Property id, eg. `my-property-id`. +* `property` **[String][1]** Related CSS property name, eg. `text-align`. +* `label` **[String][1]** Label to use in UI, eg. `Text Align`. +* `default` **[String][1]** Defaul value of the property. + +### getId + +Get property id. + +Returns **[String][1]** + +### getType + +Get the property type. +The type of the property is defined on property creation and based on its value the proper Property class is assigned. +The default type is `base`. + +Returns **[String][1]** + +### getName + +Get name (the CSS property name). + +Returns **[String][1]** + +### getLabel + +Get property label. + +#### Parameters + +* `opts` **[Object][2]** Options (optional, default `{}`) + + * `opts.locale` **[Boolean][3]** Use the locale string from i18n module (optional, default `true`) + +Returns **[String][1]** + +### getValue + +Get property value. + +#### Parameters + +* `opts` **[Object][2]** Options (optional, default `{}`) + + * `opts.noDefault` **[Boolean][3]** Avoid returning the default value (optional, default `false`) + +Returns **[String][1]** + +### hasValue + +Check if the property has value. + +#### Parameters + +* `opts` **[Object][2]** Options (optional, default `{}`) + + * `opts.noParent` **[Boolean][3]** Ignore the value if it comes from the parent target. (optional, default `false`) + +Returns **[Boolean][3]** + +### getStyle + +Get the CSS style object of the property. + +#### Parameters + +* `opts` (optional, default `{}`) + +#### Examples + +```javascript +// In case the property is `color` with a value of `red`. +console.log(property.getStyle()); +// { color: 'red' }; +``` + +Returns **[Object][2]** + +### getDefaultValue + +Get the default value. + +Returns **[string][1]** + +### upValue + +Update the value. +The change is also propagated to the selected targets (eg. CSS rule). + +#### Parameters + +* `value` **[String][1]** New value +* `opts` **[Object][2]** Options (optional, default `{}`) + + * `opts.partial` **[Boolean][3]** If `true` the update on targets won't be considered complete (not stored in UndoManager) (optional, default `false`) + * `opts.noTarget` **[Boolean][3]** If `true` the change won't be propagated to selected targets. (optional, default `false`) + +### clear + +Clear the value. +The change is also propagated to the selected targets (eg. the css property is cleared). + +#### Parameters + +* `opts` **[Object][2]** Options (optional, default `{}`) + + * `opts.noTarget` **[Boolean][3]** If `true` the change won't be propagated to selected targets. (optional, default `false`) + +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object + +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/docs/api/sector.md b/docs/api/sector.md index 77069fc88..4d652fd7d 100644 --- a/docs/api/sector.md +++ b/docs/api/sector.md @@ -49,6 +49,13 @@ Update Sector open state Get sector properties. +#### Parameters + +* `opts` **[Object][4]** Options (optional, default `{}`) + + * `opts.withValue` **[Boolean][2]** Get only properties with value (optional, default `false`) + * `opts.withParentValue` **[Boolean][2]** Get only properties with parent value (optional, default `false`) + Returns **[Array][3]<[Property]>** [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String diff --git a/src/style_manager/index.js b/src/style_manager/index.js index 41f4bc9ec..9bac0a58d 100644 --- a/src/style_manager/index.js +++ b/src/style_manager/index.js @@ -33,6 +33,7 @@ * [Sector]: sector.html * [CssRule]: css_rule.html * [Component]: component.html + * [Property]: property.html * * @module StyleManager */ diff --git a/src/style_manager/model/Property.js b/src/style_manager/model/Property.js index be6545f59..6ce06e0b2 100644 --- a/src/style_manager/model/Property.js +++ b/src/style_manager/model/Property.js @@ -2,11 +2,19 @@ import { Model } from 'common'; import { isUndefined, isString, result, keys } from 'underscore'; import { capitalize } from 'utils/mixins'; +/** + * @typedef Property + * @property {String} id Property id, eg. `my-property-id`. + * @property {String} property Related CSS property name, eg. `text-align`. + * @property {String} label Label to use in UI, eg. `Text Align`. + * @property {String} default Defaul value of the property. + * + */ export default class Property extends Model { initialize(props = {}, opts = {}) { this.em = opts.em; const id = this.get('id') || ''; - const name = this.get('name') || ''; + const name = this.get('name') || this.get('label') || ''; !this.get('property') && this.set('property', (name || id).replace(/ /g, '-')); const prop = this.get('property'); !this.get('id') && this.set('id', prop); @@ -64,7 +72,9 @@ export default class Property extends Model { } /** - * Get property type. + * Get the property type. + * The type of the property is defined on property creation and based on its value the proper Property class is assigned. + * The default type is `base`. * @returns {String} */ getType() { @@ -72,7 +82,7 @@ export default class Property extends Model { } /** - * Get property name (usually is the CSS property name). + * Get name (the CSS property name). * @returns {String} */ getName() { @@ -88,12 +98,14 @@ export default class Property extends Model { getLabel(opts = {}) { const { locale = true } = opts; const id = this.getId(); - const name = this.get('name'); + const name = this.get('name') || this.get('label'); return (locale && this.em?.t(`styleManager.properties.${id}`)) || name; } /** * Get property value. + * @param {Object} [opts={}] Options + * @param {Boolean} [opts.noDefault=false] Avoid returning the default value * @returns {String} */ getValue(opts = {}) { @@ -103,9 +115,9 @@ export default class Property extends Model { } /** - * Check if the property has value + * Check if the property has value. * @param {Object} [opts={}] Options - * @param {Boolean} [opts.noParent=false] Ignore the value if from parent target. + * @param {Boolean} [opts.noParent=false] Ignore the value if it comes from the parent target. * @returns {Boolean} */ hasValue(opts = {}) { @@ -116,25 +128,51 @@ export default class Property extends Model { } /** - * Clear value + * Get the CSS style object of the property. + * @return {Object} + * @example + * // In case the property is `color` with a value of `red`. + * console.log(property.getStyle()); + * // { color: 'red' }; */ - clear(opts = {}) { - this._up(this.__getClearProps(), { ...opts, __clear: true }); + getStyle(opts = {}) { + return { [this.getName()]: this.__getFullValue(opts) }; } /** - * Get CSS style object of the propeprty - * @return {Object} + * Get the default value. + * @return {string} */ - getStyle(opts = {}) { - return { [this.getName()]: this.__getFullValue(opts) }; + getDefaultValue() { + const def = this.get('default'); + return `${!isUndefined(def) ? def : this.get('defaults')}`; } - upValue(value, opts) { + /** + * Update the value. + * The change is also propagated to the selected targets (eg. CSS rule). + * @param {String} value New value + * @param {Object} [opts={}] Options + * @param {Boolean} [opts.partial=false] If `true` the update on targets won't be considered complete (not stored in UndoManager) + * @param {Boolean} [opts.noTarget=false] If `true` the change won't be propagated to selected targets. + */ + upValue(value, opts = {}) { + if (opts.noTarget) opts.__up = true; const parsed = value === null || value === '' ? this.__getClearProps() : this.__parseValue(value, opts); return this._up(parsed, opts); } + /** + * Clear the value. + * The change is also propagated to the selected targets (eg. the css property is cleared). + * @param {Object} [opts={}] Options + * @param {Boolean} [opts.noTarget=false] If `true` the change won't be propagated to selected targets. + */ + clear(opts = {}) { + if (opts.noTarget) opts.__up = true; + this._up(this.__getClearProps(), { ...opts, __clear: true }); + } + __parseValue(value, opts) { return this.parseValue(value, opts); } @@ -174,6 +212,7 @@ export default class Property extends Model { * @param {any} value * @param {Boolen} [complete=true] Indicates if it's a final state * @param {Object} [opts={}] Options + * @private */ setValueFromInput(value, complete, opts = {}) { this.setValue(value, complete, { ...opts, fromInput: 1 }); @@ -264,16 +303,6 @@ export default class Property extends Model { return res.map(i => i.trim()); } - /** - * Get the default value - * @return {string} - * @private - */ - getDefaultValue() { - const def = this.get('default'); - return `${!isUndefined(def) ? def : this.get('defaults')}`; - } - __getFullValue({ withDefault } = {}) { return !this.hasValue() && withDefault ? this.getDefaultValue() : this.getFullValue(); }