Przeglądaj źródła

Docs: Integration guides corrected. [skip ci]

Anna Tomanek 8 lat temu
rodzic
commit
fd93caecf2

+ 23 - 23
docs/builds/guides/integration/advanced-setup.md

@@ -11,11 +11,11 @@ In this guide, we would like to show you ways to closer integrate CKEditor with
 
 ## Bundler
 
-CKEditor 5 is currently built using [webpack](https://webpack.js.org) (>=2.x.x). All builds, examples and demos are generated using this bundler. It should also be possible to build CKEditor using other bundlers (if they are configured properly), such as [Rollup](https://github.com/rollup/rollup) or [Browserify](http://browserify.org/) but those setups are not officially supported yet. Also, the [`@ckeditor/ckeditor5-dev-webpack-plugin`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin), which allows localizing the editor, is available only for webpack. More work on this subject will be done after v1.0.0.
+CKEditor 5 is currently built using [webpack](https://webpack.js.org) (>=2.x.x). All builds, examples and demos are generated using this bundler. It should also be possible to build CKEditor using other bundlers (if they are configured properly), such as [Rollup](https://github.com/rollup/rollup) or [Browserify](http://browserify.org/) but these setups are not officially supported yet. Also, the [`@ckeditor/ckeditor5-dev-webpack-plugin`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin) that allows to localize the editor is only available for webpack. More work on this subject will be done after v1.0.0.
 
-Therefore, **the prerequisite to this guide is that you are using webpack as your build tool**.
+Therefore, **a prerequisite to this guide is that you are using webpack as your build tool**.
 
-## Scenario 1. Integrating existing builds
+## Scenario 1: Integrating existing builds
 
 This is the simplest scenario. It assumes that you want to use {@link builds/guides/overview#Available-builds one of the existing builds} "as-is" (you can, of course, still {@link builds/guides/integration/configuration configure the editor}). It also gives the fastest build times.
 
@@ -29,7 +29,7 @@ First, install the build of your choice {@link builds/guides/integration/install
 npm install --save @ckeditor/ckeditor5-build-classic
 ```
 
-Now, simply import the editor build into your code:
+Now, import the editor build into your code:
 
 ```js
 // Using ES6 imports:
@@ -52,17 +52,17 @@ ClassicEditor
 	} );
 ```
 
-Since you are using an already built editor (so a result of passing CKEditor 5's source through webpack), you don't need any additional webpack configuration. In this case CKEditor works as a ready-to-use library.
+Since you are using an already built editor (so a result of passing CKEditor 5's source through webpack), you do not need any additional webpack configuration. In this case CKEditor works as a ready-to-use library.
 
-## Scenario 2. Building from source
+## Scenario 2: Building from source
 
-This scenario allows you to fully control the building process of CKEditor. This means that you will not actually use the builds anymore, but instead build CKEditor from source directly into your project. Such an integration method gives you the full control of which features will be included and how webpack will be configured.
+This scenario allows you to fully control the building process of CKEditor. This means that you will not actually use the builds anymore, but instead build CKEditor from source directly into your project. This integration method gives you full control over which features will be included and how webpack will be configured.
 
 <info-box>
-	Similar results to what this method allows can be achieved by {@link builds/guides/development/custom-builds customizing an existing build} and integrating your custom build like in scenario 1. That method will give faster build times (since CKEditor will be built once and committed), however, it requires maintaining a separate repository and installing the code from that repository in your project (e.g. by publishing a new npm package or using tools like [Lerna](https://github.com/lerna/lerna)). This makes it less convenient than the method described in this scenario.
+	Similar results to what this method allows can be achieved by {@link builds/guides/development/custom-builds customizing an existing build} and integrating your custom build like in scenario 1. This will give faster build times (since CKEditor will be built once and committed), however, it requires maintaining a separate repository and installing the code from that repository into your project (e.g. by publishing a new npm package or using tools like [Lerna](https://github.com/lerna/lerna)). This makes it less convenient than the method described in this scenario.
 </info-box>
 
-First of all, you need to install source packages that you will use. If you base your integration on one of the existing builds you can take them from that build's `package.json` (see e.g. [classic build's `package.json`](https://github.com/ckeditor/ckeditor5-build-classic/tree/master/package.json)). At this moment you can choose the editor creator and features you want.
+First of all, you need to install source packages that you will use. If you base your integration on one of the existing builds, you can take them from that build's `package.json` file (see e.g. [classic build's `package.json`](https://github.com/ckeditor/ckeditor5-build-classic/tree/master/package.json)). At this moment you can choose the editor creator and features you want.
 
 Copy these dependencies to your `package.json` and call `npm install` to install them. The `dependencies` (or `devDependencies`) section of `package.json` should look more or less like this:
 
@@ -85,7 +85,7 @@ Copy these dependencies to your `package.json` and call `npm install` to install
 }
 ```
 
-The second step is install dependencies needed to build the editor. The list may differ if you want to customize how the webpack config, but this is the typical setup:
+The second step is to install dependencies needed to build the editor. The list may differ if you want to customize the webpack configuration, but this is a typical setup:
 
 ```js
 npm install --save \
@@ -102,13 +102,13 @@ You may also want to install [`babel-minify-webpack-plugin`](https://github.com/
 
 ### Webpack configuration
 
-Now, you can configure webpack. There are couple of things which you need to take care of when building CKEditor:
+Now, you can configure webpack. There are a couple of things which you need to take care of when building CKEditor:
 
-* Handling SASS files of CKEditor's theme. They are included in the CKEditor source using `import 'path/to/theme.sass'` statements, so you need a [proper loaders](https://webpack.js.org/loaders/).
+* Handling SASS files of CKEditor's theme. They are included in the CKEditor source using `import 'path/to/theme.sass'` statements, so you need [proper loaders](https://webpack.js.org/loaders/).
 * Similarly, you need to handle bundling SVG icons, which are also imported directly into the source. For that you need the [`raw-loader`](https://webpack.js.org/loaders/raw-loader/).
 * Finally, to localize the editor you need to use the [`@ckeditor/ckeditor5-dev-webpack-plugin`](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-webpack-plugin) webpack plugin.
 
-The minimal config, assuming that you use the same methods of handling assets as CKEditor builds, will look like this:
+The minimal configuration, assuming that you use the same methods of handling assets as CKEditor builds, will look like this:
 
 ```js
 const CKEditorWebpackPlugin = require( '@ckeditor/ckeditor5-dev-webpack-plugin' );
@@ -153,9 +153,9 @@ module.exports = {
 };
 ```
 
-### Running the editor – method 1.
+### Running the editor – method 1
 
-Now, you can import all the needed plugins and the creator directly to your code and use it there. The easiest way to do so is to copy it from the `src/ckeditor.js` file available in every build repository.
+You can now import all the needed plugins and the creator directly into your code and use it there. The easiest way to do so is to copy it from the `src/ckeditor.js` file available in every build repository.
 
 ```js
 import ClassicEditorBase from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
@@ -215,9 +215,9 @@ ClassicEditor.build = {
 };
 ```
 
-Such a module will export an editor creator class which has all the plugins and configuration that you need already built in. To use such editor, simply import that class and call the static `.create()` method like in all {@link builds/guides/integration/basic-api#Creating-an-editor examples}.
+This module will export an editor creator class which has all the plugins and configuration that you need already built-in. To use such editor, simply import that class and call the static `.create()` method like in all {@link builds/guides/integration/basic-api#Creating-an-editor examples}.
 
-### Running the editor – method 2.
+### Running the editor – method 2
 
 The second variant how to run the editor is to use the creator class directly, without creating an intermediary subclass. The above code would translate to:
 
@@ -256,7 +256,7 @@ ClassicEditor
 			ParagraphPlugin
 		],
 
-		// So is the rest of the default config.
+		// So is the rest of the default configuration.
 		toolbar: [
 			'headings',
 			'bold',
@@ -287,17 +287,17 @@ ClassicEditor
 
 ### Building
 
-Finally, you can build your app. Simply run webpack on your project and the editor will be a part of it.
+Finally, you can build your application. Run webpack on your project and the editor will be a part of it.
 
-### Option – extracting CSS
+### Option: Extracting CSS
 
-One of the most common requirements is to extract CKEditor's CSS to a separate file (it is included in the output JS file by default). To do that, you can use the [`extract-text-webpack-plugin`](https://www.npmjs.com/package/extract-text-webpack-plugin) plugin:
+One of the most common requirements is to extract CKEditor's CSS to a separate file (by default it is included in the output JavaScript file). To do that, you can use the [`extract-text-webpack-plugin`](https://www.npmjs.com/package/extract-text-webpack-plugin) plugin:
 
 ```bash
 npm install --save extract-text-webpack-plugin
 ```
 
-And add it to your webpack config:
+And add it to your webpack configuration:
 
 ```js
 const ExtractTextPlugin = require( 'extract-text-webpack-plugin' );
@@ -337,4 +337,4 @@ module.exports = {
 };
 ```
 
-Webpack will now create a separate file called `styles.css` which you will need to load manually in your HTML (using the `<link rel="stylesheet">` tag).
+Webpack will now create a separate file called `styles.css` which you will need to load manually into your HTML (using the `<link rel="stylesheet">` tag).

+ 17 - 17
docs/builds/guides/integration/basic-api.md

@@ -10,19 +10,19 @@ order: 20
 
 Each CKEditor 5 build provides a different class that handles the creation of editor instances:
 
-* Classic editor  {@link module:editor-classic/classiceditor~ClassicEditor}
-* Inline editor  {@link module:editor-inline/inlineeditor~InlineEditor}
-* Balloon editor  {@link module:editor-balloon/ballooneditor~BalloonEditor}
+* Classic editor &ndash; {@link module:editor-classic/classiceditor~ClassicEditor}
+* Inline editor &ndash; {@link module:editor-inline/inlineeditor~InlineEditor}
+* Balloon editor &ndash; {@link module:editor-balloon/ballooneditor~BalloonEditor}
 
 Most of the examples in the documentation use the `ClassicEditor` class, but things should work in a similar way with other builds.
 
 ## Creating an editor
 
-Regardless of chosen build, creating an editor is done using a static `create()` method.
+Regardless of the chosen build, creating an editor is done using the static `create()` method.
 
 ### Example – Classic editor
 
-In your HTML page add an element that CKEditor should replace:
+Add an element that CKEditor should replace to your HTML page:
 
 ```html
 <textarea name="content" id="editor">
@@ -30,7 +30,7 @@ In your HTML page add an element that CKEditor should replace:
 </textarea>
 ```
 
-Then call {@link module:editor-classic/classiceditor~ClassicEditor#create `ClassicEditor.create()`} to **replace** `<textarea>` with a {@link builds/guides/overview#Classic-editor Classic editor}:
+Then call {@link module:editor-classic/classiceditor~ClassicEditor#create `ClassicEditor.create()`} to **replace** the `<textarea>` element with a {@link builds/guides/overview#Classic-editor Classic editor}:
 
 ```js
 ClassicEditor
@@ -43,11 +43,11 @@ ClassicEditor
 	} );
 ```
 
-In the above case, the `<textarea>` element is hidden and replaced with an editor. The `<textarea>` data is used to initialize the editor content. A `<div>` element can be used in the same fashion.
+In this case the `<textarea>` element is hidden and replaced with an editor. The `<textarea>` data is used to initialize the editor content. A `<div>` element can be used in the same way.
 
 ### Example – Inline editor
 
-Similarly to the previous example, add an element where CKEditor should initialize:
+Similarly to the previous example, add an element where CKEditor should initialize to your page:
 
 ```html
 <div id="editor">
@@ -55,7 +55,7 @@ Similarly to the previous example, add an element where CKEditor should initiali
 </div>
 ```
 
-Then call {@link module:editor-inline/inlineeditor~InlineEditor#create `InlineEditor.create()`} to **attach** {@link builds/guides/overview#Inline-editor Inline editor} to a `<div>` element:
+Then call {@link module:editor-inline/inlineeditor~InlineEditor#create `InlineEditor.create()`} to **attach** {@link builds/guides/overview#Inline-editor Inline editor} to the `<div>` element:
 
 ```js
 InlineEditor
@@ -70,9 +70,9 @@ InlineEditor
 
 ### Example – Balloon editor
 
-The procedure is the same as for Inline editor, the only difference is that we will use {@link module:editor-balloon/ballooneditor~BalloonEditor#create `BalloonEditor.create()`}.
+The procedure is the same as for Inline editor &mdash; the only difference is that you need to use the {@link module:editor-balloon/ballooneditor~BalloonEditor#create `BalloonEditor.create()`} method.
 
-Add an element where CKEditor should initialize (as with ):
+Add an element where CKEditor should initialize to your page:
 
 ```html
 <div id="editor">
@@ -80,7 +80,7 @@ Add an element where CKEditor should initialize (as with ):
 </div>
 ```
 
-Then call {@link module:editor-balloon/ballooneditor~BalloonEditor#create `BalloonEditor.create()`} to **attach** {@link builds/guides/overview#Balloon-editor Balloon editor} to a `<div>` element:
+Then call {@link module:editor-balloon/ballooneditor~BalloonEditor#create `BalloonEditor.create()`} to **attach** {@link builds/guides/overview#Balloon-editor Balloon editor} to the `<div>` element:
 
 ```js
 BalloonEditor
@@ -94,7 +94,7 @@ BalloonEditor
 ```
 
 <info-box tip>
-	Every editor class may accept different parameters in the `create()` method and may handle initialization differently. For instance, the classic editor will replace a given element with an editor, while the inline editor will use the given element to initialize the editor on it. See each editor's documentation to learn the details.
+	Every editor class may accept different parameters in the `create()` method and may handle the initialization differently. For instance, the classic editor will replace a given element with an editor, while the inline editor will use the given element to initialize the editor on it. See each editor's documentation to learn the details.
 
 	The interface of the editor class is not enforced either. Since different implementations of editors may vary heavily in terms of functionality, the editor class implementers have full freedom regarding the API. Therefore, the examples in this guide may not work with some editor classes.
 </info-box>
@@ -105,7 +105,7 @@ Once the editor is created, it is possible to interact with it through its API.
 
 ### Setting the editor data
 
-To replace the editor content with new data, just use the `setData` method:
+To replace the editor content with new data, use the `setData()` method:
 
 ```js
 editor.setData( '<p>Some text.</p>' );
@@ -113,7 +113,7 @@ editor.setData( '<p>Some text.</p>' );
 
 ### Getting the editor data
 
-If the editor content needs to be retrieved for any reason, like for sending it to the server through an Ajax call, simply use the `getData` method:
+If the editor content needs to be retrieved for any reason, like for sending it to the server through an Ajax call, use the `getData()` method:
 
 ```js
 const data = editor.getData();
@@ -121,7 +121,7 @@ const data = editor.getData();
 
 ### Destroying the editor
 
-In modern applications, it is common to create and remove elements from the page interactively through JavaScript. CKEditor instances should be destroyed in such cases by using the `destroy()` method:
+In modern applications, it is common to create and remove elements from the page interactively through JavaScript. In such cases CKEditor instances should be destroyed by using the `destroy()` method:
 
 ```js
 editor.destroy()
@@ -134,7 +134,7 @@ Once destroyed, resources used by the editor instance are released and the origi
 
 ## UMD support
 
-Because builds are distributed as [UMD modules](https://github.com/umdjs/umd), it is worth noting that editor classes can be retrieved in various ways:
+Because builds are distributed as [UMD modules](https://github.com/umdjs/umd), editor classes can be retrieved in various ways:
 
 * by a [CommonJS](http://wiki.commonjs.org/wiki/CommonJS)-compatible loader (e.g. [webpack](https://webpack.js.org) or [Browserify](http://browserify.org/)),
 * by [RequireJS](http://requirejs.org/) (or any other AMD library),

+ 3 - 3
docs/builds/guides/integration/configuration.md

@@ -1,6 +1,6 @@
 ---
 # Scope:
-# * Introduction on how to set configurations.
+# * Introduction to setting configurations.
 # * Introduction to the top and must-know configurations.
 # * Point where to find the list of configuration options.
 
@@ -35,7 +35,7 @@ As you can see, configurations are set by a simple JavaScript object passed to t
 
 Builds come with all features included in the distribution package enabled by default. They are defined as plugins for CKEditor.
 
-In some cases, you may need to have different editor setups in your application, all based on the same build. For that purpose, you need to control the plugins available in an editor at runtime.
+In some cases, you may need to have different editor setups in your application, all based on the same build. For that purpose, you need to control the plugins available in the editor at runtime.
 
 In the example below `Heading` and `Link` plugins are removed:
 
@@ -51,7 +51,7 @@ ClassicEditor
 	} );
 ```
 <info-box>
-Be careful when removing plugins using `config.removePlugins` from CKEditor builds. If removed plugins were providing toolbar buttons then the default toolbar configuration included in a build will become invalid. In such case provide the updated toolbar configuration as in the example above.
+Be careful when removing plugins using `config.removePlugins` from CKEditor builds. If removed plugins were providing toolbar buttons, the default toolbar configuration included in a build will become invalid. In such case you need to provide the updated toolbar configuration as in the example above.
 </info-box>
 
 ### List of plugins

+ 7 - 5
docs/builds/guides/integration/installation.md

@@ -16,7 +16,9 @@ There are several options to download CKEditor 5 builds:
 * [npm](#npm)
 * [Zip download](#Zip-download)
 
-For the list of available builds check the {@link builds/guides/overview#Available-builds Overview} page. Once you download the editor jump to the {@link builds/guides/integration/basic-api Basic API guide} to see how to create editors.
+For the list of available builds check the {@link builds/guides/overview#Available-builds Overview} page.
+
+After downloading the editor jump to the {@link builds/guides/integration/basic-api Basic API guide} to see how to create editors.
 
 ### CDN
 
@@ -44,9 +46,9 @@ CKEditor will then be available at `node_modules/ckeditor5-build-[name]/ckeditor
 This download method is not available yet.
 </info-box>
 
-Go to [CKEditor 5 builds download page](https://ckeditor.com/ckeditor5-builds/download) and download your preferred build. For example, you may download the `ckeditor5-build-classic-1.0.0.zip` file for the Classic editor build.
+Go to the [CKEditor 5 builds download page](https://ckeditor.com/ckeditor5-builds/download) and download your preferred build. For example, you may download the `ckeditor5-build-classic-1.0.0.zip` file for the Classic editor build.
 
-Extract the above `.zip` file into a dedicated directory inside your project. It is recommended to include the editor version in the directory name to ensure proper cache invalidation once a new version of CKEditor is installed.
+Extract the `.zip` file into a dedicated directory inside your project. It is recommended to include the editor version in the directory name to ensure proper cache invalidation once a new version of CKEditor is installed.
 
 ## Included files
 
@@ -54,7 +56,7 @@ TODO
 
 ## Loading the API
 
-Once downloaded and installed in your application, it is time to make the API available in your pages. For that purpose, it is enough to load the API entry point script:
+After downloading and installing a CKEditor 5 build in your application, it is time to make the editor API available in your pages. For that purpose, it is enough to load the API entry point script:
 
 ```html
 <script src="[ckeditor-build-path]/ckeditor.js"></script>
@@ -63,7 +65,7 @@ Once downloaded and installed in your application, it is time to make the API av
 Once the CKEditor script is loaded, you can {@link builds/guides/integration/basic-api use the API} to create editors in your page.
 
 <info-box>
-	The `build/ckeditor.js` file is generated in the [UMD format](https://github.com/umdjs/umd) so you can also import it to your application if you use CommonJS modules (like in Node.js) or AMD modules (like in Require.js). Read more in the {@link builds/guides/integration/basic-api#UMD-support Basic API guide}.
+	The `build/ckeditor.js` file is generated in the [UMD format](https://github.com/umdjs/umd) so you can also import it into your application if you use CommonJS modules (like in Node.js) or AMD modules (like in Require.js). Read more in the {@link builds/guides/integration/basic-api#UMD-support Basic API guide}.
 
 	Also, for a more advanced setup, you may wish to bundle the CKEditor script with other scripts used by your application. See {@linkTODO Bundling} for more information about it.
 </info-box>

+ 4 - 1
docs/builds/index.md

@@ -12,9 +12,12 @@ CKEditor 5 Builds are the fastest and easiest way to use CKEditor 5 in your appl
 ## Documentation 
 
  * {@link builds/guides/overview Guides} &ndash; Learn how to install, integrate and configure CKEditor 5 Builds. More complex aspects, like creating custom builds, are explained here, too.
- * {@link examples/index Examples} &ndash; Try live demos of all available builds.
  * {@link features/index Features} &ndash; Learn about some of the features included in CKEditor 5 Builds.
 
+## Examples
+
+Try {@link examples/index live demos} of all available builds.
+
 ## Contribute
 
 CKEditor is an Open Source project and your contribution is most welcome. Feel free to {@link builds/guides/reporting-issues report bugs} or improve the code on [GitHub](https://github.com/ckeditor/ckeditor5). Since CKEditor is localized, you can also help [to translate it](https://www.transifex.com/ckeditor/ckeditor5/). You do not need to be a programmer to contribute to the project!