From 71326c752b1365aa7874e7ebc3d82a8afe6a00cd Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Sun, 3 Oct 2021 14:44:35 +0200 Subject: [PATCH] Update CssRule doc --- docs/api/block.md | 32 ++++++++++++++++++ docs/api/block_manager.md | 9 +++-- docs/api/css_composer.md | 14 ++++---- docs/api/css_rule.md | 56 ++++++++++++++++++++----------- docs/modules/Components.md | 2 +- src/css_composer/model/CssRule.js | 36 +++++++------------- 6 files changed, 96 insertions(+), 53 deletions(-) diff --git a/docs/api/block.md b/docs/api/block.md index 41ce2dab0..5deb19cc1 100644 --- a/docs/api/block.md +++ b/docs/api/block.md @@ -17,6 +17,36 @@ * `onClick` **[Function][5]?** Custom behavior on click, eg. `(block, editor) => editor.getWrapper().append(block.get('content'))` * `attributes` **[Object][2]?** Block attributes to apply in the view element +### getId + +Get block id + +Returns **[String][1]** + +### getLabel + +Get block label + +Returns **[String][1]** + +### getMedia + +Get block media + +Returns **[String][1]** + +### getContent + +Get block content + +Returns **([Object][2] | [String][1] | [Array][6]<([Object][2] | [String][1])>)** Component definition | HTML string + +### getCategoryLabel + +Get block category label + +Returns **[String][1]** + [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object @@ -26,3 +56,5 @@ [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function + +[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array diff --git a/docs/api/block_manager.md b/docs/api/block_manager.md index 770de1ec5..2d76d3275 100644 --- a/docs/api/block_manager.md +++ b/docs/api/block_manager.md @@ -28,9 +28,10 @@ blockManager.add(...); * `block:add` - Block added. The [Block] is passed as an argument to the callback. * `block:remove` - Block removed. The [Block] is passed as an argument to the callback. * `block:update` - Block updated. The [Block] and the object containing changes are passed as arguments to the callback. -* `block:drag:start` - Started dragging block, model of the block is passed as an argument -* `block:drag` - Dragging block, the block's model and the drag event are passed as arguments -* `block:drag:stop` - Dragging of the block is stopped. As agruments for the callback you get, the dropped component model (if dropped successfully) and the model of the block +* `block:drag:start` - Started dragging block, the [Block] is passed as an argument. +* `block:drag` - Dragging block, the [Block] is passed as an argument. +* `block:drag:stop` - Dragging of the block is stopped. The dropped [Component] (if dropped successfully) and the [Block] are passed as arguments. +* `block` - Catch-all event for all the events mentioned above. An object containing all the available data about the triggered event is passed as an argument to the callback. ## Methods @@ -46,6 +47,8 @@ blockManager.add(...); [Block]: block.html +[Component]: component.html + ## getConfig Get configuration object diff --git a/docs/api/css_composer.md b/docs/api/css_composer.md index c209adedb..a119e74fe 100644 --- a/docs/api/css_composer.md +++ b/docs/api/css_composer.md @@ -84,18 +84,18 @@ Get the rule ### Parameters -* `selectors` **[Array][12]\** Array of selectors -* `state` **[String][13]** Css rule state -* `width` **[String][13]** For which device this style is oriented +* `selectors` **([String][13] | [Array][12]\)** Array of selectors or selector string, eg `.myClass1.myClass2` +* `state` **[String][13]** Css rule state, eg. 'hover' +* `width` **[String][13]** Media rule value, eg. '(max-width: 992px)' * `ruleProps` **[Object][10]** Other rule props ### Examples ```javascript -var sm = editor.SelectorManager; -var sel1 = sm.add('myClass1'); -var sel2 = sm.add('myClass2'); -var rule = cssComposer.get([sel1, sel2], 'hover'); +const sm = editor.SelectorManager; +const sel1 = sm.add('myClass1'); +const sel2 = sm.add('myClass2'); +const rule = cssComposer.get([sel1, sel2], 'hover', '(max-width: 992px)'); // Update the style rule.set('style', { width: '300px', diff --git a/docs/api/css_rule.md b/docs/api/css_rule.md index d7ca0daf4..b3b0687a1 100644 --- a/docs/api/css_rule.md +++ b/docs/api/css_rule.md @@ -1,10 +1,26 @@ -## getAtRule +## CssRule -Return the at-rule statement when exists, eg. '@media (...)', '@keyframes' +**Extends Model.extend(Styleable)** -### Examples +### Properties + +* `selectors` **[Array][1]\** Array of selectors +* `style` **[Object][2]** Object containing style definitions +* `selectorsAdd` **[String][3]?** Additional string css selectors +* `atRuleType` **[String][3]?** Type of at-rule, eg. `media`, 'font-face' +* `mediaText` **[String][3]?** At-rule value, eg. `(max-width: 1000px)` +* `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 + +### getAtRule + +Return the at-rule statement when exists, eg. `@media (...)`, `@keyframes` + +#### Examples ```javascript const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { @@ -14,19 +30,19 @@ const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { cssRule.getAtRule(); // "@media (min-width: 500px)" ``` -Returns **[String][1]** +Returns **[String][3]** -## selectorsToString +### selectorsToString Return selectors of the rule as a string -### Parameters +#### Parameters * `opts` **[Object][2]?** Options (optional, default `{}`) - * `opts.skipState` **[Boolean][3]?** Skip state from the result + * `opts.skipState` **[Boolean][4]?** Skip state from the result -### Examples +#### Examples ```javascript const cssRule = editor.Css.setRule('.class1:hover', { color: 'red' }); @@ -34,17 +50,17 @@ cssRule.selectorsToString(); // ".class1:hover" cssRule.selectorsToString({ skipState: true }); // ".class1" ``` -Returns **[String][1]** +Returns **[String][3]** -## getDeclaration +### getDeclaration Get declaration block (without the at-rule statement) -### Parameters +#### Parameters * `opts` **[Object][2]** Options (same as in `selectorsToString`) (optional, default `{}`) -### Examples +#### Examples ```javascript const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { @@ -54,17 +70,17 @@ const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { cssRule.getDeclaration() // ".class1{color:red;}" ``` -Returns **[String][1]** +Returns **[String][3]** -## toCSS +### toCSS Return the CSS string of the rule -### Parameters +#### Parameters * `opts` **[Object][2]** Options (same as in `getDeclaration`) (optional, default `{}`) -### Examples +#### Examples ```javascript const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { @@ -74,10 +90,12 @@ const cssRule = editor.Css.setRule('.class1', { color: 'red' }, { cssRule.toCSS() // "@media (min-width: 500px){.class1{color:red;}}" ``` -Returns **[String][1]** CSS string +Returns **[String][3]** CSS string -[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array [2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String + +[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/docs/modules/Components.md b/docs/modules/Components.md index 1c3dedb2d..2ed028fcf 100644 --- a/docs/modules/Components.md +++ b/docs/modules/Components.md @@ -42,7 +42,7 @@ editor.getWrapper().append(`
...`); ``` ::: tip -If you need to append a component in at a specific position, you can use `at` option. So, to add a component on top of all others (in the same collection) you would use +If you need to append a component at a specific position, you can use `at` option. So, to add a component on top of all others (in the same collection) you would use ```js component.append('
...', { at: 0 }) ``` diff --git a/src/css_composer/model/CssRule.js b/src/css_composer/model/CssRule.js index 2ae46e08c..9f69f525c 100644 --- a/src/css_composer/model/CssRule.js +++ b/src/css_composer/model/CssRule.js @@ -6,41 +6,31 @@ import { isEmptyObj, hasWin } from 'utils/mixins'; const { CSS } = hasWin() ? window : {}; +/** + * @typedef CssRule + * @property {Array} selectors Array of selectors + * @property {Object} style Object containing style definitions + * @property {String} [selectorsAdd=''] Additional string css selectors + * @property {String} [atRuleType=''] Type of at-rule, eg. `media`, 'font-face' + * @property {String} [mediaText=''] At-rule value, eg. `(max-width: 1000px)` + * @property {Boolean} [singleAtRule=false] This property is used only on at-rules, like 'page' or 'font-face', where the block containes only style declarations + * @property {String} [state=''] State of the rule, eg: `hover`, `focused` + * @property {Boolean|Array} [important=false] If true, sets `!important` on all properties. You can also pass an array to specify properties on which use important + * @property {Boolean} [stylable=true] Indicates if the rule is stylable from the editor + */ export default class CssRule extends Model.extend(Styleable) { defaults() { return { - // Css selectors selectors: [], - - // Additional string css selectors selectorsAdd: '', - - // Css properties style style: {}, - - // On which device width this rule should be rendered, eg. `(max-width: 1000px)` mediaText: '', - - // State of the rule, eg: hover | pressed | focused state: '', - - // Indicates if the rule is stylable stylable: true, - - // Type of at-rule, eg. 'media', 'font-face', etc. atRuleType: '', - - // This particolar property is used only on at-rules, like 'page' or - // 'font-face', where the block containes only style declarations singleAtRule: false, - - // If true, sets '!important' on all properties - // You can use an array to specify properties to set important - // Used in view important: false, - group: '', - _undo: true }; } @@ -89,7 +79,7 @@ export default class CssRule extends Model.extend(Styleable) { } /** - * Return the at-rule statement when exists, eg. '@media (...)', '@keyframes' + * Return the at-rule statement when exists, eg. `@media (...)`, `@keyframes` * @returns {String} * @example * const cssRule = editor.Css.setRule('.class1', { color: 'red' }, {