From 9796a18f57baa48d34d503558d3dbbe92d20f185 Mon Sep 17 00:00:00 2001 From: jacobherrington Date: Thu, 25 Oct 2018 16:55:39 -0500 Subject: [PATCH 1/5] Improve grammar and make descriptions more concise --- docs/README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/README.md b/docs/README.md index daef7c849..fee25bccb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,22 +3,22 @@ [[toc]] ## What is GrapesJS? -At first look you might probably think it's just another kind of page/HTML builder, but actually is something more. GrapesJS is a multi-purpose, Web Builder Framework, which means it allows you easily create your, drag & drop enabled, builder of "THINGS". For "THINGS" we consider anything web structure related, so HTML at first, but don't just think about web pages, we use HTML-like structure basically everywhere: Newsletters (eg. [MJML](https://mjml.io/)), Native Mobile Applications (eg. [React Native](https://github.com/facebook/react-native)), Native Desktop Applications (eg. [Vuido](https://vuido.mimec.org)), PDFs (eg. [React PDF](https://github.com/diegomura/react-pdf)), etc. So, for everything you can imagine as a set of elements like `... other nested elements ...` you can create easily a GrapesJS builder around it and then use it independently in some of your applications. -GrapesJS comes along with different features and tools which enable you to craft easy to use builders, which will allow your users to create complex HTML-like templates without any knowledge of coding. +At first glance might think this is just another page/HTML builder, but it's something more. GrapesJS is a multi-purpose, Web Builder Framework, which means it allows you to easily create a drag & drop enabled builder of "things". By "things" we mean anything with HTML-like structure, which entails much more than web pages. We use HTML-like structure basically everywhere: Newsletters (eg. [MJML](https://mjml.io/)), Native Mobile Applications (eg. [React Native](https://github.com/facebook/react-native)), Native Desktop Applications (eg. [Vuido](https://vuido.mimec.org)), PDFs (eg. [React PDF](https://github.com/diegomura/react-pdf)), etc. So, for everything you can imagine as a set of elements like `... other nested elements ...` you can create easily a GrapesJS builder around it and then use it independently your applications. +GrapesJS ships with features and tools that enable you to craft easy to use builders. Which allows your users to create complex HTML-like templates without any knowledge of coding. ## Why GrapesJS? -Mainly, GrapesJS was designed to be used inside some CMS to speed up the creation of dynamic templates and replace common WYSIWYG editors, which are good for content editing but inappropriate for creating HTML structures. Then, with the same concept, instead of creating just an application we decided to create a framework that could be extended and used by everyone for any kind purpose. +GrapesJS was designed primarily to for use inside Content Management Systems to speed up the creation of dynamic templates and replace common WYSIWYG editors. Which are good for content editing, but inappropriate for creating HTML structures. Instead of creating an application we decided to create an extensible framework that could be used by anyone for any purpose. ## Quick Start -To show up of what GrapesJS is capable of we have created some presets. +To showcase the power of GrapesJS we have created some presets. * [grapesjs-preset-webpage](https://github.com/artf/grapesjs-preset-webpage) - [Webpage Builder](http://artf.github.io/grapesjs/demo.html) * [grapesjs-preset-newsletter](https://github.com/artf/grapesjs-preset-newsletter) - [Newsletter Builder](http://artf.github.io/grapesjs/demo-newsletter-editor.html) @@ -34,7 +34,7 @@ You can actually use them as a starting point for your editors, so, just follow Latest version: [![npm](https://img.shields.io/npm/v/grapesjs.svg?colorB=e67891)](https://www.npmjs.com/package/grapesjs) -You can download GrapesJS from one of this sources +You can download GrapesJS from one of these sources * CDNs * unpkg @@ -54,3 +54,4 @@ You can download GrapesJS from one of this sources ## Changelog To track changes made in the library we rely on [Github Releases](https://github.com/artf/grapesjs/releases) + From 14dc5e0ed8bc641d372b46f97472da5e5d2aee33 Mon Sep 17 00:00:00 2001 From: jacobherrington Date: Thu, 25 Oct 2018 17:13:48 -0500 Subject: [PATCH 2/5] Improve grammar --- docs/getting-started.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 3a1b4384e..40d5cb3c7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -8,12 +8,11 @@ meta: # Getting Started -This guide is a step-by-step introduction for everyone who wants to start creating its own builder with GrapesJS. This is not a complete guide of all functionalities but just a concise overview of most common modules. -Let's see how to create a completely customized page builder from scratch. The last demo of this page represents the [final result](#final-result) +This is a step-by-step guide for anyone who wants to create their own builder with GrapesJS. This is not a comprehensive guide, just a concise overview of most common modules. Follow along to create a page builder from scratch. Skip to the end of this page to see the [final result](#final-result) ## Import the library -Before start using GrapesJS you have to import it inside your project, so let's import its latest version +Before you start using GrapesJS, you'll have to import it. Let's import the latest version ```html @@ -24,7 +23,7 @@ If you need plugins, put them below the main grapesjs script --> ``` -or if you're in node environment +or if you're in a Node environment ```js import 'grapesjs/dist/css/grapes.min.css'; @@ -35,9 +34,8 @@ import grapesjs from 'grapesjs'; ## Start from the canvas -The first step is to define the interface of our editor and for this purpose we gonna start from basic HTML layouts. -Finding a common structure for the UI of any project is not an easy task that's why GrapesJS prefers to keep this process as simple as possible, by providing just few helpers but letting the user define the whole interface, this guarantees maximum flexibility. -The main part of the GrapesJS editor is the canvas, this is where you gonna create the whole structure of your templates and you definitely can't miss it. Let's try to initiate the editor with just the canvas and no panels. +The first step is to define the interface of our editor. For this purpose we gonna start with basic HTML layouts. Finding a common structure for the UI of any project is not an easy task. That's why GrapesJS prefers to keep this process as simple as possible. We provide a few helpers, but let the user define the interface. This guarantees maximum flexibility. +The main part of the GrapesJS editor is the canvas, this is where you create the structure of your templates and you can't miss it. Let's try to initiate the editor with the canvas and no panels. <<< @/docs/.vuepress/components/demos/DemoCanvasOnly.html <<< @/docs/.vuepress/components/demos/DemoCanvasOnly.js @@ -46,10 +44,10 @@ The main part of the GrapesJS editor is the canvas, this is where you gonna crea -With just the canvas you're already able to move, copy and delete components from the structure (when you select components in the canvas, the toolbar is shown). For now we just see the example template taken from the container. Let's see now how can we create and drag custom blocks into our canvas. +With just the canvas you're already able to move, copy and delete components from the structure. For now, we see the example template taken from the container. Next let's look at how to create and drag custom blocks into our canvas. ## Add Blocks -The block in GrapesJS is just a reusable piece of HTML that you can drop in the canvas. A block can be an image, a button, or an entire section with videos, forms and iframes. Let's start from creating another container and append inside it few basic blocks which we can later use to build more complex structures. +The block in GrapesJS is just a reusable piece of HTML that you can drop in the canvas. A block can be an image, a button, or an entire section with videos, forms and iframes. Let's start by creating another container and append a few basic blocks inside of it. Later we can use this technique to build more complex structures. ```html{4}
@@ -102,7 +100,7 @@ const editor = grapesjs.init({ -As you see we add our blocks via the initial configuration, which is ok, but obviously there might be the case you would like to add them dynamically, in this case you have to use the [Block Manager API](api/block_manager.html) +As you can see we add our blocks via the initial configuration. Obviously there might be a case in which you would like to add them dynamically, in this case you have to use the [Block Manager API](api/block_manager.html) ```js editor.BlockManager.add('my-block-id', { @@ -112,11 +110,11 @@ editor.BlockManager.add('my-block-id', { }) ``` ::: tip -If you want to get more about blocks we suggest to read its dedicated page: [Block Manager Module](modules/Blocks.html) +If you want to learn more about blocks we suggest to read its dedicated article: [Block Manager Module](modules/Blocks.html) ::: ## Define Components -Technically, once you drop your HTML block inside the canvas each element of the content is transformed in GrapesJS Component, which is an object containing informations about how the element is rendered in the canvas (managed in the View) and how it might look its final code (created by the properties in the Model). Generally, all Model properties are reflected in the View, so, for example, if you add a new attribute to the model, not only it will be available in the export code (will see later how to get it) but also the element you see in the canvas is updated with new attributes. +Technically, once you drop your HTML block inside the canvas each element of the content is transformed into a GrapesJS Component. A GrapesJS Component is an object containing information about how the element is rendered in the canvas (managed in the View) and how it might look its final code (created by the properties in the Model). Generally, all Model properties are reflected in the View, so, for example, if you add a new attribute to the model, not only it will be available in the export code (will see later how to get it) but also the element you see in the canvas is updated with new attributes. While this is a common behavior what it's cool about Components that you can create a totally decoupled view and show to the user whatever you desire (so not necessary reflecting the model). For example, by dragging a placeholder text you can fetch and show instead a dynamic content. If want to get more about Custom Components and how to create and extend them, we recommend to check out [Component Manager Module](modules/Components.html). GrapesJS comes along with few [built-in Components](modules/Components.html#built-in-components) which enable different core features once rendered in canvas. Just to mention few of them, by double clicking on the image component you will see show up the default [Asset Manager](modules/Assets.html), which you can customize or integrate you own, by double clicking on the text component you're able to edit it via the built-in Rich Text Editor, which is also customizable and [replaceable](guides/Replace-Rich-Text-Editor.html). @@ -723,3 +721,4 @@ and here is our final result + From a0ad028e066e7f0c790d8767a8e95a9e6e778dc5 Mon Sep 17 00:00:00 2001 From: jacobherrington Date: Fri, 26 Oct 2018 06:39:09 -0500 Subject: [PATCH 3/5] Improve grammar, correct typos --- docs/getting-started.md | 56 ++++++++++++++++++++--------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 40d5cb3c7..e411da5a6 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -114,10 +114,10 @@ If you want to learn more about blocks we suggest to read its dedicated article: ::: ## Define Components -Technically, once you drop your HTML block inside the canvas each element of the content is transformed into a GrapesJS Component. A GrapesJS Component is an object containing information about how the element is rendered in the canvas (managed in the View) and how it might look its final code (created by the properties in the Model). Generally, all Model properties are reflected in the View, so, for example, if you add a new attribute to the model, not only it will be available in the export code (will see later how to get it) but also the element you see in the canvas is updated with new attributes. -While this is a common behavior what it's cool about Components that you can create a totally decoupled view and show to the user whatever you desire (so not necessary reflecting the model). For example, by dragging a placeholder text you can fetch and show instead a dynamic content. If want to get more about Custom Components and how to create and extend them, we recommend to check out [Component Manager Module](modules/Components.html). +Technically, once you drop your HTML block inside the canvas each element of the content is transformed into a GrapesJS Component. A GrapesJS Component is an object containing information about how the element is rendered in the canvas (managed in the View) and how it might look its final code (created by the properties in the Model). Generally, all Model properties are reflected in the View. Therefore, if you add a new attribute to the model, it will be available in the export code (which we will learn more about later), and the element you see in the canvas will be updated with new attributes. +This isn't totally out of the ordinary, but the unique thing about Components that you can create a totally decoupled View. This means you can show the user whatever you desire regardless of what is in the Model. For example, by dragging a placeholder text you can fetch and show instead a dynamic content. If you want to learn more about Custom Components, you should check out [Component Manager Module](modules/Components.html). -GrapesJS comes along with few [built-in Components](modules/Components.html#built-in-components) which enable different core features once rendered in canvas. Just to mention few of them, by double clicking on the image component you will see show up the default [Asset Manager](modules/Assets.html), which you can customize or integrate you own, by double clicking on the text component you're able to edit it via the built-in Rich Text Editor, which is also customizable and [replaceable](guides/Replace-Rich-Text-Editor.html). +GrapesJS comes with a few [built-in Components](modules/Components.html#built-in-components) that enable different features once rendered in the canvas. For example, by double clicking on an image component you will see the default [Asset Manager](modules/Assets.html), which you can customize or integrate you own. By double clicking on the text component you're able to edit it via the built-in Rich Text Editor, which is also customization and [replaceable](guides/Replace-Rich-Text-Editor.html). As we have seen before you can create Blocks directly as Components ```js @@ -142,7 +142,7 @@ editor.BlockManager.add('my-block-id', { }) ``` ::: tip -Check the [Components API](api/components.html) and see how to interact with components dynamically +Check out the [Components API](api/components.html) to learn how to interact with components dynamically ::: An example on how to select some inner component and replace its children with new contents @@ -224,8 +224,8 @@ editor.Panels.addPanel({ -So, we have defined where to render the panel with `el: '#basic-panel'` and then for each button we added a `command` property. The command could be the id, an object with `run` and `stop` functions or simply a single function. -Try to use [Commands](api/commands.html) when possible, they allow you to track actions globally and execute also callbacks before and after their execution (you can even interrupt them). +We have defined where to render the panel with `el: '#basic-panel'` and then for each button we added a `command` property. The command could be the id, an object with `run` and `stop` functions or simply a single function. +Try to use [Commands](api/commands.html) when possible, they allow you to track actions globally. Commands also execute callbacks before and after their execution (you can even interrupt them). ```js editor.on('run:export-template:before', opts => { @@ -239,12 +239,12 @@ editor.on('abort:export-template', () => console.log('Command aborted')); ``` ::: tip -Check the [Panels API](api/panels.html) to see all the available methods +Check out the [Panels API](api/panels.html) to see all the available methods ::: ## Layers -Another utility tool you might find useful when working with web elements is a layer manger. It's just a tree overview of the structure nodes and enables you to manage it easier. To enable it you just have to specify where you want to render it +Another utility tool you might find useful when working with web elements is the layer manger. It's a tree overview of the structure nodes and enables you to manage it easier. To enable it you just have to specify where you want to render it ```html{4,5,6,7,8,9,10,11}
@@ -294,9 +294,9 @@ const editor = grapesjs.init({ ## Style Manager -Once you have defined the structure of the template probably the next step is the ability to style it. To meet this need GrapesJS includes the Style Manager module which is composed by CSS style properties and sectors. To make it more clear, let's see how to define a basic set. +Once you have defined the structure of the template the next step is the ability to style it. To meet this need GrapesJS includes the Style Manager module which is composed by CSS style properties and sectors. To make it more clear, let's see how to define a basic set. -Let's start from adding one more panel inside the `panel__right` and another one in `panel__top` which will contain a Layer/Style Manager switcher +Let's start by adding one more panel inside the `panel__right` and another one in `panel__top` which will contain a Layer/Style Manager switcher ```html{3,8}
@@ -438,9 +438,9 @@ Each component can also indicate what to style and what not. --> ## Traits -Most of the time you would style your components and place them somewhere in the structure, but sometimes your components might need custom attributes or even custom behaviors and for this need you can make use of traits. A common use of traits is the ability to update HTML element attributes (eg. `placeholder` for inputs or `alt` for images) but you can also define your own custom traits, access the selected Component model and do whatever you want. For this guide, we just gonna show you how to render available traits, for more details on how to extend them we suggest to read the [Trait Manager Module page](modules/Traits.html). +Most of the time you would style your components and place them somewhere in the structure, but sometimes your components might need custom attributes or even custom behaviors and for this need you can make use of traits. Traits are commonly used to update HTML element attributes (eg. `placeholder` for inputs or `alt` for images), but you can also define your own custom traits. Access the selected Component model and do whatever you want. For this guide, we going to show you how to render available traits, for more details on how to extend them we suggest you read the [Trait Manager Module page](modules/Traits.html). -Let's create a new container for traits, tell the editor where to render it and update the sidebar switcher +Let's create a new container for traits. Tell the editor where to render it and update the sidebar switcher ```html{5} ... @@ -498,10 +498,10 @@ editor.Commands.add('show-traits', { -Now if you switch to the Trait panel and select some of the inner component you should see its default traits. +Now if you switch to the Trait panel and select one of the inner components you should see its default traits. ## Responsive templates -GrapesJS implements also a module which allows you to work with responsive templates easily. Let's see how to define different devices and some button for device switching +GrapesJS implements a module which allows you to work with responsive templates easily. Let's see how to define different devices and a button for device switching ```html{3}
@@ -566,7 +566,7 @@ editor.Commands.add('set-device-mobile', { -As you can see from the commands definition we just use the `editor.setDevice` method to change the size of the viewport. In case you need to trigger some action on device change you can setup a listener like this: +As you can see from the commands definition we use the `editor.setDevice` method to change the size of the viewport. In case you need to trigger an action on device change you can setup a listener like this: ```js editor.on('change:device', () => console.log('Current device: ', editor.getDevice())); @@ -597,13 +597,13 @@ editor.setDevice('Mobile'); ``` ::: tip -Check the [Device Manager API](api/panels.html) to get all available methods +Check out the [Device Manager API](api/panels.html) to see all the available methods ::: ## Store & load data -Once you finished with defining you builder interface the next step would be to setup the storing and loading process. -GrapesJS implements 2 simple type of storages inside its Storage Manager, the local (by using `localStorage`, active by default) and the remote one. Those are enough to cover most of the cases, but it's also possible to add new implementations ([grapesjs-indexeddb](https://github.com/artf/grapesjs-indexeddb) is a good example). -Let's see how the default options looks like +Once you have finished with defining your builder interface the next step would be to setup the storing and loading process. +GrapesJS implements 2 simple type of storages inside its Storage Manager: The local (by using `localStorage`, active by default) and the remote one. Those are enough to cover most of the cases, but it's also possible to add new implementations ([grapesjs-indexeddb](https://github.com/artf/grapesjs-indexeddb) is a good example). +Let's see how the default options work ```js grapesjs.init({ @@ -622,9 +622,9 @@ grapesjs.init({ }); ``` -Worth noting the default `id` parameter which adds a prefix for all keys to store. If you check the `localStorage` inside the devtool panel you'll see something like `{ 'gjs-components': '....' ...}` in this way it prevents the risk of collisions. +It is worth noting that the default `id` parameter adds a prefix for all keys to store. If you check the `localStorage` inside the devtool panel you'll see something like `{ 'gjs-components': '....' ...}` this way it lessens the risk of collisions. -Let's check also the configuration required to setup the remote storage +Let's look at the configuration required to setup the remote storage ```js grapesjs.init({ @@ -639,8 +639,8 @@ grapesjs.init({ } }); ``` -As you might noticed, we've left some default option unchanged, increased changes necessary for autosave triggering and passed remote endpoints. -If you prefer you could also disable the autosaving and do it by yourself using some custom command +As you might noticed, we've left some default options unchanged: Increased changes necessary for autosave triggering and passed remote endpoints. +If you prefer you could also disable the autosaving and you can do so using a custom command ```js // ... @@ -664,13 +664,13 @@ If you prefer you could also disable the autosaving and do it by yourself using // ... ``` -To get a better overview of the Storage Manager, how correctly you should store/load the template and how to define new storages you have to read the [Storage Manager Module](modules/Storage.html) page +To get a better overview of the Storage Manager and how you should store/load the template, or how to define new storages you should read the [Storage Manager Module](modules/Storage.html) page ## Theming -One last step that might actually improve a lot your editor personality is how it's look visually. To achieve an easy theming we have adapted an atomic design for this purpose. To customize the main palette of colors all you have to do is to change few CSS rules or if you include GrapesJS styles via SCSS you can make use of its [internal variables](https://github.com/artf/grapesjs/blob/dev/src/styles/scss/_gjs_variables.scss) and declare yours before the import +One last step that might actually improve a lot your editor personality is how it's look visually. To achieve an easy theming we have adapted an atomic design for this purpose. To customize the main palette of colors all you have to do is to change few CSS rules. Alternatively if you include GrapesJS styles via SCSS you can make use of its [internal variables](https://github.com/artf/grapesjs/blob/dev/src/styles/scss/_gjs_variables.scss) and declare your variables before the import ```scss -// Put your variables before the grapesjs style import +// Put your variables before the GrapesJS style import // Palette variables $primaryColor: #444; @@ -683,8 +683,8 @@ $quaternaryColor: #d278c9; @import "grapesjs/src/styles/scss/main.scss"; ``` -In case of a simple CSS you just have to put your rules after the GrapesJS styles. -To complete our builder let's customize its color palette and to make it more visually "readable" we gonna replace all button labels with SVG icons +In case of a simple CSS you'll have to put your rules after the GrapesJS styles. +To complete our builder let's customize its color palette and to make it more visually "readable" we can replace all button labels with SVG icons ```css /* We can remove the border we've set at the beginnig */ From d6836f22999cc16e790e5503b5167dd92b4395e3 Mon Sep 17 00:00:00 2001 From: jacobherrington Date: Fri, 26 Oct 2018 06:52:41 -0500 Subject: [PATCH 4/5] Improve grammar in the docs --- docs/modules/Assets.md | 43 +++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/docs/modules/Assets.md b/docs/modules/Assets.md index c1a390b24..62efeea75 100644 --- a/docs/modules/Assets.md +++ b/docs/modules/Assets.md @@ -6,14 +6,14 @@ title: Asset Manager

GrapesJS - Asset Manager

-In this section, you will see how to setup and take the full advantage of built-in Asset Manager in GrapesJS, which is intentionally lightweight and implements just an `image` in its core, but as you'll see next it's easy to extend and create your own asset types. +In this section, you will see how to setup and take the full advantage of built-in Asset Manager in GrapesJS. The Asset Manager is lightweight and implements just an `image` in its core, but as you'll see next it's easy to extend and create your own asset types. [[toc]] ## Configuration -To change default configurations you have to pass `assetManager` property with the main configuration object +To change default configurations you'll have to pass `assetManager` property with the main configuration object ```js const editor = grapesjs.init({ @@ -33,7 +33,7 @@ const amConfig = editor.AssetManager.getConfig(); ``` -Below the list of currently available options +Below is a list of currently available options ```js // Default assets @@ -119,7 +119,7 @@ Below the list of currently available options modalTitle: 'Select Image', ``` -Not always docs are in inline with its code, therefore we'd suggest to keep an eye at the current state of configurations by checking the dedicated source file [Asset Manager Config](https://github.com/artf/grapesjs/blob/dev/src/asset_manager/config/config.js) +Sometimes the code gets ahead of the docs, therefore we'd suggest to keep an eye at the current state of configurations by checking the dedicated source file [Asset Manager Config](https://github.com/artf/grapesjs/blob/dev/src/asset_manager/config/config.js) @@ -127,7 +127,7 @@ Not always docs are in inline with its code, therefore we'd suggest to keep an e ## Initialization -The Asset Manager is ready to work by default, so just pass few urls to see them loaded +The Asset Manager is ready to work by default, so pass few URLs to see them loaded ```js const editor = grapesjs.init({ @@ -155,7 +155,7 @@ const editor = grapesjs.init({ ``` -If you want a complete list of available properties check the source [AssetImage Model](https://github.com/artf/grapesjs/blob/dev/src/asset_manager/model/AssetImage.js) +If you want a complete list of available properties check out the source [AssetImage Model](https://github.com/artf/grapesjs/blob/dev/src/asset_manager/model/AssetImage.js) The built-in Asset Manager modal is implemented and is showing up when requested. By default, you can make it appear by dragging Image Components in canvas, double clicking on images and all other stuff related to images (eg. CSS styling) @@ -163,7 +163,7 @@ The built-in Asset Manager modal is implemented and is showing up when requested -Showing up of the modal is registered with a command, so you can make it appear with this +Making the modal appear is registered with a command, so you can make it appear with this ```js // This command shows only assets with `image` type @@ -218,7 +218,7 @@ am.add([ ]); ``` -Now if you call the `render()`, without any argument, you will see all the assets rendered +Now if you call the `render()`, without an argument, you will see all the assets rendered ```js // without any argument @@ -241,7 +241,7 @@ am.getAll().length // Still have 3 assets am.getAllVisible().length // but only 2 are shown ``` -Obviously, you can mix more arrays of assets +You can also mix arrays of assets ```js am.render([...assets1, ...assets2, ...assets3]); @@ -261,10 +261,10 @@ For more APIs methods check out the [API Reference](API-Asset-Manager) ### Define new Asset type -Generally speaking, an asset is not only an image, it could be a `video`, `svg-icon`, or any other kind of `document`. Each type of the asset is applied in our templates/pages differently. If you need to change the image of the Component all you need is another `url` in `src` attribute, but in case of `svg-icon`, for instance, its not the same, you might want to replace the element with a new `` content. Besides this you also have to deal with the presentation/preview of the asset inside the panel/modal, like for example showing a thumbnail for big images or the possibility to preview videos. +Generally speaking, images aren't the only asset you'll use, it could be a `video`, `svg-icon`, or any other kind of `document`. Each type of asset is applied in our templates/pages differently. If you need to change the image of the Component all you need is another `url` in `src` attribute. However In case of a `svg-icon`, its not the same, you might want to replace the element with a new `` content. Besides this you also have to deal with the presentation/preview of the asset inside the panel/modal. For example, showing a thumbnail for big images or the possibility to preview videos. -Defining a new asset it means we have to push on top of the 'Stack of Types' a new layer. This stack is iterated by the editor at any addition of the asset and tries to associate the correct type. +Defining a new asset it means we have to push on top of the 'Stack of Types' a new layer. This stack is iterated over by the editor at any addition of the asset and tries to associate the correct type. ```js am.add('https://.../image.png'); @@ -277,7 +277,7 @@ am.add({type: 'video', src: '...'}); // an object, has 'video' type key -> 'video' type ``` -Obviously, it's up to you tell the editor how to recognize your type and for this purpose you have to use `isType()` method. +It's up to you tell the editor how to recognize your type and for this purpose you should to use `isType()` method. Let's see now an example of how we'd start to defining a type like `svg-icon` @@ -300,7 +300,7 @@ am.addType('svg-icon', { }) ``` -With this snippet you can already add SVGs, the asset manager will assign correctly the appropriate type. +With this snippet you can already add SVGs, the asset manager will assign the appropriate type. ```js // Add some random SVG @@ -325,7 +325,7 @@ You should see something like this -The SVG asset is not correctly rendered and this is because we haven't yet configured its view +The SVG asset is not rendered correctly and this is because we haven't yet configured its view ```js am.addType('svg-icon', { @@ -386,7 +386,7 @@ am.addType('svg-icon', { ``` -Our custom `svg-icon` asset is ready to use, you can also add a `model` to the `addType` definition which should group the business logic of your asset but usually it's optional so you can skip this part. +Our custom `svg-icon` asset is ready to use. You can also add a `model` to the `addType` definition to group the business logic of your asset, but usually it's optional. ```js @@ -417,7 +417,7 @@ am.addType('svg-icon', { ### Extend Asset Types -Extending asset types is basically the same as adding them, you can just choose what type to extend and how. +Extending asset types is basically the same as adding them, you can choose what type to extend and how. ```js // svgIconType will contain the definition (model, view, isType) @@ -469,13 +469,13 @@ am.addType('image', { ## Uploading assets -Asset Manager includes an easy to use, drag and drop, uploader and integrates few UI helpers. The default uploader is already visible when you open the Asset Manager. +Asset Manager includes an easy to use, drag-and-drop uploader with a few UI helpers. The default uploader is already visible when you open the Asset Manager. -You can click on the uploader to start select your files or just drag them directly from your computer to trigger the uploader. Obviously, before make it work you have to setup your server in order to receive your assets and specify the upload endpoint in configurations +You can click on the uploader to select your files or just drag them directly from your computer to trigger the uploader. Obviously, before it will work you have to setup your server to receive your assets and specify the upload endpoint in your configuration ```js @@ -500,7 +500,7 @@ let editor = grapesjs.init({ ### Listeners -If you want to execute some action before/after the uploading process (eg. loading animation) or even on response, you can make use of these listeners +If you want to execute an action before/after the uploading process (eg. loading animation) or even on response, you can make use of these listeners ```js // The upload is started @@ -533,7 +533,7 @@ editor.on('asset:upload:response', (response) => { ### Response -When the uploading is over, by default (via config parameter `autoAdd: 1`), the editor expects to receive a JSON of uploaded assets in a `data` key as a response and tries to add them to the main collection. The JSON might look like this: +When the uploading is over, by default (via config parameter `autoAdd: 1`), the editor expects to receive a JSON blob of uploaded assets in a `data` key as a response and tries to add them to the main collection. The JSON might look like this: ```js { @@ -557,7 +557,7 @@ When the uploading is over, by default (via config parameter `autoAdd: 1`), the ### Setup Dropzone -There is also another helper which improve the uploading of assets, a full-width editor dropzone. +There is another helper which improves the uploading of assets: A full-width editor dropzone. @@ -589,3 +589,4 @@ Currently available events you can listen to * `asset:upload:end` - After the upload is ended * `asset:upload:error` - On any error in upload, passes the error as an argument * `asset:upload:response` - On upload response, passes the result as an argument + From 636587c9d0ff5513591429b54106f1db268d46b3 Mon Sep 17 00:00:00 2001 From: jacobherrington Date: Fri, 26 Oct 2018 07:03:52 -0500 Subject: [PATCH 5/5] Improve grammar in the docs --- docs/modules/Blocks.md | 7 ++++--- docs/modules/Components.md | 17 +++++++++-------- 2 files changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/modules/Blocks.md b/docs/modules/Blocks.md index 17ad328c4..755c61d0b 100644 --- a/docs/modules/Blocks.md +++ b/docs/modules/Blocks.md @@ -8,9 +8,9 @@ title: Block Manager The Block is a group of [Components] and can be easily reused inside templates. -To better understand the difference between components and blocks, the component is more atomic so, for example, a single image, a text box or a map fits perfectly in this concept. The block is what the end user will drag inside the canvas, so it could contain a single image (single Component) or the entire section like, for example, the footer with a lot of components inside (texts, images, inputs, etc). +The difference between components and blocks: The component is more atomic, so a single image, a text box or a map is a component. The block is what the end user will drag inside the canvas, so it could contain a single image (single Component) or the entire section like, for example, the footer with a lot of components inside (texts, images, inputs, etc). -Check [Components] page to see the list of built-in components and how to create your own. +Check out the [Components] page to see the list of built-in components and how to create your own. Let's see how to add a new block to the editor using the [Blocks API] @@ -52,7 +52,7 @@ blockManager.add('my-map-block', { }) ``` -From the v0.3.70 it's also possible to pass the HTML string with Component's properties as attributes. +From v0.3.70 it's also possible to pass the HTML string with Component's properties as attributes. ```js blockManager.add('the-row-block', { @@ -72,3 +72,4 @@ https://github.com/artf/grapesjs/blob/dev/src/dom_components/model/Component.js [Component]: [Components]: [Blocks API]: + diff --git a/docs/modules/Components.md b/docs/modules/Components.md index ea1cbcc24..ae46d4648 100644 --- a/docs/modules/Components.md +++ b/docs/modules/Components.md @@ -4,7 +4,7 @@ title: Component Manager # Component Manager -The Component is the base element for the template composition and, usually, elements like images, text boxes, maps, etc. fit perfectly in this concept. The concept of the component was made to allow the developer to bind different behaviors to different elements. Like for example, opening the Asset Manager on double click of the image. +The Component is the base element for template composition. It is atomic, so elements like images, text boxes, maps, etc. fit the definition of a Component. The concept of the component was made to allow the developer to bind different behaviors to different elements. Like for example, opening the Asset Manager on double click of the image. [[toc]] @@ -33,7 +33,7 @@ When we pass an HTML string to the editor like this:
``` -The editor will create and store, for each DOM element, its object representation and all next changes to the template will be made on top of this structure, which will then reflect on canvas. So, each object, usually called *Model* (or state/store), will be the source of truth for the template, but what exactly does it mean? For instance, in more practical way, once the template is rendered on the canvas, if you try to remove one of the elements using the browser inspector and then ask the editor to print the HTML (using `editor.getHtml()`) you'll see, from the code, that the element will still be there, this because the editor relies on Models and not on the DOM inside the canvas. This approach allows us to be extremely flexible on how to generate the final code (from the *Model*) and how to render it inside the canvas (from the *View*). +For each DOM element the editor will create and store an object representation. Every future change to the template will be made on top of this structure, which will then reflect on the canvas. So each object, usually called *Model* (or state/store), will be the source of truth for the template, but what exactly does that mean? In more practical example, once the template is rendered on the canvas, if you try to remove one of the elements using the browser inspector and then ask the editor to print the HTML (using `editor.getHtml()`) you'll see that the element will still be present. This is because the editor relies on Models and not on the DOM inside the canvas. This approach allows us to be extremely flexible on how we generate the final code (from the *Model*) and how to render it inside the canvas (from the *View*). @@ -54,7 +54,7 @@ isComponent: function(el) { } ``` -This method gives us the possibility to recognize and bind component types to each HTMLElement (div, img, iframe, etc.). Each HTML element introduced inside the canvas will be processed by `isComponent` of all available types and if it matches, the object represented the type should be returned. So, for example, with the image component this method looks like: +This method gives us the possibility to recognize and bind component types to each HTMLElement (div, img, iframe, etc.). Each HTML element introduced inside the canvas will be processed by `isComponent` of all available types and if it matches, the object represented the type should be returned. For example, with the image component this method looks like: ```js // Image component @@ -64,7 +64,7 @@ isComponent: function(el) { } ``` -Let's try with something that might look a little bit tricky. What about a Google's Map?!? Google's maps are generally embedded as `iframe`s, but the template can be composed by a lot of different `iframe`s, how can I tell the editor that a particular iframe is actually a Google's Map. Well, this part is up to you to understand which is the right pattern to choose, you have the `HTMLElement` so you can make all checks you want and in this particular case this pattern is used: +Let's try with something that might look a little bit tricky. What about a Google Map?!? Google Maps are generally embedded as `iframe`s, but the template can be composed by a lot of different `iframe`s. How can I tell the editor that a particular iframe is actually a Google's Map? Well, you'll have to figure out the right pattern, you have the `HTMLElement` so you can make all the checks you want. In this particular case this pattern is used: ```js // Map component @@ -75,17 +75,17 @@ isComponent: function(el) { }, ``` -So, as you see, in addition to `tagName` check, we also used the `src` property, but, as you'll see, you can actually override it with your own logic by extending the built-in component. +In addition to `tagName` check, we also used the `src` property, but you can actually override it with your own logic by extending the built-in component. ## Define new Component -Let's see now an example, with another HTML element, which is not handled by default Component types. What about `input` elements? +Let's see an example with another HTML element that is not handled by default Component types. What about `input` elements? -With the default GrapesJS configuration `input`s are treated just like any other element, you can move it around, style it, etc., but usually we'd like to handle this type of element more specifically. In this case, we have to create a new Component type. +With the default GrapesJS configuration `input`s are treated like any other element; you can move it around, style it, etc. However, we'd like to handle this type of element more specifically. In this case, we have to create a new Component type. -Let's define just few specs for our new *Input* type: +Let's define few specs for our new *Input* type: * Can be dropped only inside `form` elements * Can't drop other elements inside it @@ -268,3 +268,4 @@ Solution 1: turn off `autorender` ``` Solution 2: put all the stuff inside a plugin ([Creating plugins](https://github.com/artf/grapesjs/wiki/Creating-plugins)) +