From 328bf8bf1c27a7d07d6ac3f99660ce474b7beb18 Mon Sep 17 00:00:00 2001 From: Artur Arseniev Date: Sat, 11 Jun 2016 11:33:57 +0200 Subject: [PATCH] Update JSDoc after refactoring --- README.md | 101 +++++++++++------------------------- src/code_manager/main.js | 2 +- src/commands/main.js | 8 +-- src/dom_components/main.js | 4 +- src/editor/main.js | 46 +++++++++++++--- src/grapesjs/main.js | 4 +- src/panels/main.js | 12 ++--- src/storage_manager/main.js | 2 +- src/style_manager/main.js | 4 +- 9 files changed, 89 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index 063454c83..9a2b6b3ee 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,16 @@ [![Build Status](https://travis-ci.org/artf/grapesjs.svg?branch=master)](https://travis-ci.org/artf/grapesjs)

GrapesJS

+
-GrapesJS is a free and open source Web Template Editor for building HTML templates to be used inside sites, webapps, newsletters or anything else related with HTML. +GrapesJS is a free and open source Web Template Builder which helps you building HTML templates to be used inside sites, newsletters or even mobile apps. Mainly GrapesJS was designed to be used inside a [CMS] to speed up creation of dynamic templates. To better understand this concept check the image below - +

GrapesJS - Style Manager

+
- -Generally any 'template system', that you can find in various applications like CMS, is composed by the **structure** (HTML), **style** (CSS) and **variables**, which are then replaced with other templates and contents on server-side and rendered soon on client. +Generally any 'template system', that you can find in various applications like CMS, is composed by the **structure** (HTML), **style** (CSS) and **variables**, which are then replaced with other templates and contents on server-side and rendered on client. This demo shows an example of what is possible to achieve: http://grapesjs.com/demo.html @@ -77,7 +78,7 @@ If [Grunt](http://gruntjs.com/) is already installed globally you could change t ## Usage -JQuery is the only hard dependency so you have to include it before use GrapesJS. +JQuery is the only hard dependency so you have to include it before using GrapesJS. ```html @@ -87,92 +88,57 @@ After that include scripts from GrapesJS with all your configurations and render ```html +
``` -Unfortunately with the configuration above you wouldn't see a lot. This because GrapesJS it self is simply empty, adding panels, buttons and other stuff will be your job (actually it's not empty but you need buttons to show them up). -The section below will explain some basic configurations but for a more practical example I suggest to look up the code inside this demo: http://grapesjs.com/demo.html - -Documentation is under construction here: [wiki] - - -## Configuration - -For now I only show up some general settings, for more details check source or demo. Examples will be available soon - -```js -var config = { - - // Prefix to use inside local storage name - storagePrefix: 'wte-', - - // Where to render editor (eg. #myId) - container: '', - - // Enable/Disable the possibility to copy (ctrl + c) and paste (ctrl + v) elements - copyPaste: true, - - // Enable/Disable undo manager - undoManager: true, - - //Indicates which storage to use. Available: local | remote | none - storageType: 'local', - - //Configurations for Asset Manager (check src/asset_manager/config/config.js) - assetManager: {}, +You could also grab the content directly from the element with `fromElement` property - //Configurations for Style Manager (check src/style_manager/config/config.js) - styleManager: {}, - - //Configurations for Layers (check src/navigator/config/config.js) - layers: {}, - - //Configurations for Storage Manager (check src/storage_manager/config/config.js) - storageManager: {}, +```html +
+
Hello world!
+ +
- //Configurations for Rich Text Editor (check src/rich_text_editor/config/config.js) - rte: {}, + +``` - //Configurations for Components (check src/dom_components/config/config.js) - components: {}, +Unfortunately with the configuration above you wouldn't see a lot. This because GrapesJS it self is simply empty, adding panels, buttons and other stuff will be your job (actually it's not empty but you need buttons to show them up). +The section below will explain some basic configurations but for a more practical example I suggest to look up the code inside this demo: http://grapesjs.com/demo.html - //Configurations for Panels (check src/panels/config/config.js) - panels: {}, - //Configurations for Commands (check src/commands/config/config.js) - commands: {}, +## Configuration -}; -``` +Check the getting started guide here: [wiki] ## API -At the moment `render()` is the only available method but others will be public very soon... +API References (draft) could be found here: [wiki/API-Reference] ## Testing -**ATTENTION: tests are pretty far away from being complete** - -Tests are run by [PhantomJS](http://phantomjs.org/) using [Mocha](https://mochajs.org/) (with [Chai](http://chaijs.com/) and [Sinon](http://sinonjs.org/) help) - ```sh -$ npm run test +$ npm test ``` -## Todos before beta release +## TODOs before beta release -* **Class Manager** (*in development*) - Ability to assign different classes to components and style them (because CSS with only ids is pretty much a pain) * **Breakpoint Manager** - Resize canvas according to breakpoints established by user (in simple terms, for responsive templates). Will be put into development immediately after Class Manager -* **Style Manager improvements** - Mainly `stack` type is not yet complete ## Acknowledgements @@ -189,16 +155,11 @@ GrapesJS is built on top of this amazing open source projects: ## Support -A star/fork is already a huge motivational support and I'd like to thank all of you for that, but if you want to contribute the project economically and you have this possibility you could use the link below :heart: +If you like the project support it, with a donation of your choice. [![PayPalMe](http://grapesjs.com/img/ppme.png)](https://paypal.me/grapesjs) -## Contributing - -Any kind of help is welcome. At the moment there is no generic guidelines so use usual pull requests and push to `dev` branch - - ## License BSD 3-clause diff --git a/src/code_manager/main.js b/src/code_manager/main.js index c4ad9178b..72b51fef1 100644 --- a/src/code_manager/main.js +++ b/src/code_manager/main.js @@ -12,7 +12,7 @@ * Before using methods you should get first the module from the editor instance, in this way: * * ```js - * var codeManager = editor.get('CodeManager'); + * var codeManager = editor.CodeManager; * ``` * * @module CodeManager diff --git a/src/commands/main.js b/src/commands/main.js index fdab3869d..31db04f70 100644 --- a/src/commands/main.js +++ b/src/commands/main.js @@ -7,7 +7,7 @@ * You can init the editor with all necessary commands via configuration * * ```js - * var editor = new GrapesJS({ + * var editor = grapesjs.init({ * ... * commands: {...} // Check below for the properties * ... @@ -17,7 +17,7 @@ * Before using methods you should get first the module from the editor instance, in this way: * * ```js - * var commandsService = editor.get('Commands'); + * var commands = editor.Commands; * ``` * * @module Commands @@ -100,7 +100,7 @@ define(function(require) { * @param {Object} command Object representing you command. Methods `run` and `stop` are required * @return {this} * @example - * commandsService.add('myCommand', { + * commands.add('myCommand', { * run: function(serviceManager, senderBtn){ * alert('Hello world!'); * }, @@ -115,7 +115,7 @@ define(function(require) { * @param {string} id Command's ID * @return {Object} Object representing the command * @example - * var myCommand = commandsService.get('myCommand'); + * var myCommand = commands.get('myCommand'); * myCommand.run(); * */ get: function(id){ diff --git a/src/dom_components/main.js b/src/dom_components/main.js index f7bc76f25..6ae99c275 100644 --- a/src/dom_components/main.js +++ b/src/dom_components/main.js @@ -9,7 +9,7 @@ * You can init the editor with initial components via configuration * * ```js - * var editor = new GrapesJS({ + * var editor = grapesjs.init({ * ... * components: {...} // Check below for the possible properties * ... @@ -20,7 +20,7 @@ * Before using methods you should get first the module from the editor instance, in this way: * * ```js - * var ComponentsService = editor.get('Components'); + * var ComponentsService = editor.Components; * ``` * * @module Components diff --git a/src/editor/main.js b/src/editor/main.js index 29dce336c..0be2896cc 100644 --- a/src/editor/main.js +++ b/src/editor/main.js @@ -1,10 +1,29 @@ +/** + * + * * [getConfig](#getconfig) + * * [getHtml](#gethtml) + * * [getCss](#getcss) + * * [getComponents](#getcomponents) + * * [setComponents](#setcomponents) + * * [getStyle](#getstyle) + * * [setStyle](#setstyle) + * * [getSelected](#getselected) + * * [store](#store) + * * [load](#load) + * * [render](#render) + * + * Editor class contains the top level API which you'll probably use to custom the editor or extend it with plugins. + * You get the Editor instance on init method + * + * ```js + * var editor = grapesjs.init({...}); + * ``` + * + * @module Editor + * @param {Object} config Configurations + */ define(function (require){ - /** - * @class Grapes - * @param {Object} Configurations - * - * @return {Object} - * */ + var Editor = function(config) { var c = config || {}, defaults = require('./config/config'), @@ -119,6 +138,14 @@ define(function (require){ * Set components inside editor's canvas. This method overrides actual components * @param {Array|Object|string} components HTML string or components model * @return {this} + * @example + * editor.setComponents('
New component
'); + * // or + * editor.setComponents({ + * type: 'text', + * classes:['cls'], + * content: 'New component' + * }); */ setComponents: function(components){ editorModel.setComponents(components); @@ -137,6 +164,13 @@ define(function (require){ * Set style inside editor's canvas. This method overrides actual style * @param {Array|Object|string} style CSS string or style model * @return {this} + * @example + * editor.setStyle('.cls{color: red}'); + * //or + * editor.setStyle({ + * selectors: ['cls'] + * style: { color: 'red' } + * }); */ setStyle: function(style){ editorModel.setStyle(style); diff --git a/src/grapesjs/main.js b/src/grapesjs/main.js index 958a60aea..1768a785d 100644 --- a/src/grapesjs/main.js +++ b/src/grapesjs/main.js @@ -45,8 +45,8 @@ define(function (require) { if(!els) throw new Error("'container' is required"); - config.el = document.querySelector(els); - var editor = new Editor(config); + c.el = document.querySelector(els); + var editor = new Editor(c); // Execute all plugins var plugs = plugins.getAll(); diff --git a/src/panels/main.js b/src/panels/main.js index 4af7df6d7..28d39ff0c 100644 --- a/src/panels/main.js +++ b/src/panels/main.js @@ -11,7 +11,7 @@ * You can init the editor with all panels and buttons necessary via configuration * * ```js - * var editor = new GrapesJS({ + * var editor = grapesjs.init({ * ... * panels: {...} // Check below for the possible properties * ... @@ -22,7 +22,7 @@ * Before using methods you should get first the module from the editor instance, in this way: * * ```js - * var panelService = editor.get('Panels'); + * var panelManager = editor.Panels; * ``` * * @module Panels @@ -83,7 +83,7 @@ define(function(require) { * @param {Object|Panel} panel Object with right properties or an instance of Panel * @return {Panel} Added panel. Useful in case of passed argument was an Object * @example - * var newPanel = panelService.addPanel({ + * var newPanel = panelManager.addPanel({ * id: 'myNewPanel', * visible : true, * buttons : [...], @@ -98,7 +98,7 @@ define(function(require) { * @param {string} id Id string * @return {Panel|null} * @example - * var myPanel = panelService.getPanel('myNewPanel'); + * var myPanel = panelManager.getPanel('myNewPanel'); */ getPanel : function(id){ var res = panels.where({id: id}); @@ -111,7 +111,7 @@ define(function(require) { * @param {Object|Button} button Button object or instance of Button * @return {Button|null} Added button. Useful in case of passed button was an Object * @example - * var newButton = panelService.addButton('myNewPanel',{ + * var newButton = panelManager.addButton('myNewPanel',{ * id: 'myNewButton', * className: 'someClass', * command: 'someCommand', @@ -130,7 +130,7 @@ define(function(require) { * @param {string} id Button's ID * @return {Button|null} * @example - * var button = panelService.getButton('myPanel','myButton'); + * var button = panelManager.getButton('myPanel','myButton'); */ getButton : function(panelId, id){ var pn = this.getPanel(panelId); diff --git a/src/storage_manager/main.js b/src/storage_manager/main.js index 12ed776b1..6af8e6b2a 100644 --- a/src/storage_manager/main.js +++ b/src/storage_manager/main.js @@ -15,7 +15,7 @@ * Before using methods you should get first the module from the editor instance, in this way: * * ```js - * var storageManager = editor.get('StorageManager'); + * var storageManager = editor.StorageManager; * ``` * * @module StorageManager diff --git a/src/style_manager/main.js b/src/style_manager/main.js index 492fd0d45..958a405ee 100644 --- a/src/style_manager/main.js +++ b/src/style_manager/main.js @@ -13,7 +13,7 @@ * You can init the editor with all sectors and properties via configuration * * ```js - * var editor = new GrapesJS({ + * var editor = grapesjs.init({ * ... * styleManager: {...} // Check below for the possible properties * ... @@ -23,7 +23,7 @@ * Before using methods you should get first the module from the editor instance, in this way: * * ```js - * var styleManager = editor.get('StyleManager'); + * var styleManager = editor.StyleManager; * ``` * * @module StyleManager