Browse Source

Docs: Decoupled editor API docs and guide revised.

Anna Tomanek 7 years ago
parent
commit
c53aade058

+ 22 - 22
packages/ckeditor5-editor-decoupled/docs/framework/guides/document-editor.md

@@ -5,9 +5,9 @@ order: 30
 
 # Document editor
 
-The {@link examples/builds/document-editor document editor example} showcases the {@link builds/guides/quick-start#document-editor document editor build} designed for document editing with a customized UI representing the layout of a sheet of paper. It has been created on top of the {@link module:editor-decoupled/decouplededitor~DecoupledEditor `DecoupledEditor`} and makes the best of what it offers: a freedom to choose the location of the crucial UI elements in the application.
+The {@link examples/builds/document-editor document editor example} showcases the {@link builds/guides/quick-start#document-editor document editor build} designed for document editing with a customized UI representing the layout of a sheet of paper. It was created on top of the {@link module:editor-decoupled/decouplededitor~DecoupledEditor `DecoupledEditor`} and makes the best of what it offers: the freedom to choose the location of the crucial UI elements in the application.
 
-In this tutorial, you'll learn how to create your own document editor with the customized user interface, step–by–step.
+In this tutorial you will learn how to create your own document editor with a customized user interface, step–by–step.
 
 {@snippet examples/document-editor}
 
@@ -19,7 +19,7 @@ The `DecoupledDocumentEditor` includes all the necessary features for the task.
 	See the {@link builds/guides/quick-start#document-editor quick start guide} to learn how to install the document editor build.
 </info-box>
 
-Unlike the {@link builds/guides/overview#classic-editor classic editor}, the document editor does not require any data container in DOM. Instead, it accepts the string containing the initial data as a first argument of the static `create()` method. To get the output data, use the {@link module:core/editor/utils/dataapimixin~DataApi#getData `getData`} method.
+Unlike the {@link builds/guides/overview#classic-editor classic editor}, the document editor does not require any data container in the DOM. Instead, it accepts a string containing the initial data as the first argument of the static `create()` method. To get the output data, use the {@link module:core/editor/utils/dataapimixin~DataApi#getData `getData`} method.
 
 ```js
 import DecoupledDocumentEditor from '@ckeditor/ckeditor5-build-decoupled-document/src/ckeditor';
@@ -43,19 +43,19 @@ DecoupledDocumentEditor
 
 You may have noticed two configuration options used here: {@link module:core/editor/editorconfig~EditorConfig#toolbarContainer `config.toolbarContainer`} and {@link module:core/editor/editorconfig~EditorConfig#editableContainer `config.editableContainer`}. They specify the location of the editor toolbar and editable in your application.
 
-If you don't specify these configuration options, then you have to make sure the editor UI is injected into your application after it fires the {@link module:core/editor/editorwithui~EditorWithUI#event:uiReady `uiReady`} event. The toolbar element is accessible via `editor.ui.view.toolbar.element` and the editable element can be found under `editor.ui.view.editable.element`.
+If you do not specify these configuration options, you have to make sure the editor UI is injected into your application after it fires the {@link module:core/editor/editorwithui~EditorWithUI#event:uiReady `uiReady`} event. The toolbar element is accessible via `editor.ui.view.toolbar.element` and the editable element can be found under `editor.ui.view.editable.element`.
 
 <info-box>
-	The document editor supports the Easy Image provided by [CKEditor Cloud Services](https://ckeditor.com/ckeditor-cloud-services/) out of the box. Please refer to the {@link features/image-upload#easy-image documentation} to learn more.
+	The document editor supports the Easy Image plugin provided by [CKEditor Cloud Services](https://ckeditor.com/ckeditor-cloud-services/) out of the box. Please refer to the {@link features/image-upload#easy-image documentation} to learn more.
 </info-box>
 
 ## The user interface
 
-The code we just created will run the editor but still, the user interface is missing. Let's start off with a basic HTML structure to host the editor components (toolbar and editable).
+The code you have just created will run the editor but still, the user interface is missing. Start off with a basic HTML structure to host the editor components (toolbar and editable).
 
 ### HTML
 
-The following structure has two containers which correspond to the configuration we have just used. The editor will inject the toolbar and editable into respective containers as it starts.
+The following structure has two containers that correspond to the configuration you have just used. The editor will inject the toolbar and editable into respective containers as it starts.
 
 ```html
 <div class="document-editor">
@@ -64,15 +64,15 @@ The following structure has two containers which correspond to the configuration
 </div>
 ```
 
-The `<div class="document-editor">...</<div>` is the outermost container of the document editor and, although not mandatory, it is recommended to keep things together.
+The `<div class="document-editor">...</<div>` element is the outermost container of the document editor and, although not mandatory, it is recommended to keep things together.
 
 <info-box warning>
-	Make sure the HTML structure is available in DOM when the editor is created. To do so, put the editor bootstrap code somewhere later in HTML or use the [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event to defer your JavaScript execution until the DOM is up and ready.
+	Make sure the HTML structure is available in the DOM when the editor is created. To do so, put the editor bootstrap code somewhere later in HTML or use the [`DOMContentLoaded`](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) event to defer your JavaScript execution until the DOM is up and ready.
 </info-box>
 
 ### Styles
 
-Styles are what the document editor really needs to materialize. Let's begin with the styles of the main container:
+Styles are what the document editor really needs to materialize. Begin with the styles of the main container:
 
 ```css
 .document-editor {
@@ -89,7 +89,7 @@ Styles are what the document editor really needs to materialize. Let's begin wit
 }
 ```
 
-Then, let's make the toolbar look like it floats over the "page":
+Then, make the toolbar look like it floats over the "page":
 
 ```css
 .document-editor__toolbar {
@@ -103,7 +103,7 @@ Then, let's make the toolbar look like it floats over the "page":
 	border-bottom: 1px solid var(--ck-color-toolbar-border);
 }
 
-/* Adjust the look of the toolbar inside of the container. */
+/* Adjust the look of the toolbar inside the container. */
 .document-editor__toolbar .ck-toolbar {
 	border: 0;
 	border-radius: 0;
@@ -113,7 +113,7 @@ Then, let's make the toolbar look like it floats over the "page":
 The editable should look like a sheet of paper, centered in its scrollable container:
 
 ```css
-/* Make the editable container look like the inside of a native word processor app. */
+/* Make the editable container look like the inside of a native word processor application. */
 .document-editor__editable {
 	padding: calc( 2 * var(--ck-spacing-large) );
 	background: var(--ck-color-base-foreground);
@@ -142,7 +142,7 @@ The editable should look like a sheet of paper, centered in its scrollable conta
 }
 ```
 
-All we need to do now is style the actual content of the editor. First things first, we need to define some basic font styles:
+All you need to do now is style the actual content of the editor. Start with defining some basic font styles:
 
 ```css
 /* Set the default font for the "page" of the content. */
@@ -152,10 +152,10 @@ All we need to do now is style the actual content of the editor. First things fi
 }
 ```
 
-Then let's focus on headings and paragraphs. Note that what the users see in the headings dropdown should correspond to the actual edited content for the best user experience.
+Then focus on headings and paragraphs. Note that what the users see in the headings dropdown should correspond to the actual edited content for the best user experience.
 
 <info-box>
-	It is recommended the `.ck-content` CSS class is used to visually style the content of the editor (headings, paragraphs, lists, etc.).
+	It is recommended to use the `.ck-content` CSS class to visually style the content of the editor (headings, paragraphs, lists, etc.).
 </info-box>
 
 ```css
@@ -165,7 +165,7 @@ Then let's focus on headings and paragraphs. Note that what the users see in the
 	min-width: 8em;
 }
 
-/* Set the styles for the "Heading 1". */
+/* Set the styles for "Heading 1". */
 .document-editor .ck-content h2,
 .document-editor .ck-heading-dropdown .ck-heading_heading1 {
 	font-size: 2.18em;
@@ -177,7 +177,7 @@ Then let's focus on headings and paragraphs. Note that what the users see in the
 	margin-bottom: .142em;
 }
 
-/* Set the styles for the "Heading 2". */
+/* Set the styles for "Heading 2". */
 .document-editor .ck-content h3,
 .document-editor .ck-heading-dropdown .ck-heading_heading2 {
 	font-size: 1.75em;
@@ -188,14 +188,14 @@ Then let's focus on headings and paragraphs. Note that what the users see in the
 	color: var(--ck-color-list-item-text-active);
 }
 
-/* Set the styles for the "Heading 2". */
+/* Set the styles for "Heading 2". */
 .document-editor .ck-content h3 {
 	line-height: 1.86em;
 	padding-top: .171em;
 	margin-bottom: .357em;
 }
 
-/* Set the styles for the "Heading 3". */
+/* Set the styles for "Heading 3". */
 .document-editor .ck-content h4,
 .document-editor .ck-heading-dropdown .ck-heading_heading3 {
 	font-size: 1.31em;
@@ -207,7 +207,7 @@ Then let's focus on headings and paragraphs. Note that what the users see in the
 	margin-bottom: .952em;
 }
 
-/* Set the styles for the "Paragraph". */
+/* Set the styles for "Paragraph". */
 .document-editor .ck-content p,
 .document-editor .ck-heading-dropdown .ck-heading_paragraph {
 	font-size: 1em;
@@ -233,6 +233,6 @@ A finishing touch that makes the block quotes more sophisticated and the styling
 
 ## Summary
 
-The document editor is ready to use. Still, you may want to configure some features like {@link module:highlight/highlight~HighlightConfig highlight}, {@link module:font/fontsize~FontSizeConfig font size}, {@link module:font/fontfamily~FontFamilyConfig font family} for the best editing experience.
+The document editor is ready to use. Still, you may want to configure some features like {@link module:highlight/highlight~HighlightConfig highlight}, {@link module:font/fontsize~FontSizeConfig font size} or {@link module:font/fontfamily~FontFamilyConfig font family} for the best editing experience.
 
 Thanks to the {@link module:editor-decoupled/decouplededitor~DecoupledEditor `DecoupledEditor`} used as a foundation, you can experiment and create custom user interface layouts quickly while preserving the feature set, accessibility support (e.g. {@link features/keyboard-support keyboard navigation} in the toolbar) and more.

+ 17 - 17
packages/ckeditor5-editor-decoupled/src/decouplededitor.js

@@ -17,9 +17,9 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
 /**
  * The {@glink builds/guides/overview#decoupled-editor decoupled editor} implementation.
  * It provides an inline editable and a toolbar. However, unlike other editors,
- * it does not render these components anywhere in DOM unless configured.
+ * it does not render these components anywhere in the DOM unless configured.
  *
- * This type of an editor is dedicated for integrations which require a customized UI with an open
+ * This type of an editor is dedicated to integrations which require a customized UI with an open
  * structure, allowing developers to specify the exact location of the interface.
  *
  * See the document editor {@glink examples/builds/document-editor demo} to learn about possible use cases
@@ -37,7 +37,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * {@glink builds/guides/overview Builds} are ready-to-use editors with plugins bundled in. When using the editor from
  * source you need to take care of loading all plugins by yourself
  * (through the {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`} option).
- * Using the editor from source gives much better flexibility and allows easier customization.
+ * Using the editor from source gives much better flexibility and allows for easier customization.
  *
  * Read more about initializing the editor from source or as a build in
  * {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create `DecoupledEditor.create()`}.
@@ -50,7 +50,7 @@ export default class DecoupledEditor extends Editor {
 	/**
 	 * Creates an instance of the decoupled editor.
 	 *
-	 * **Note:** do not use the constructor to create editor instances. Use the static
+	 * **Note:** Do not use the constructor to create editor instances. Use the static
 	 * {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create `DecoupledEditor.create()`} method instead.
 	 *
 	 * @protected
@@ -81,14 +81,14 @@ export default class DecoupledEditor extends Editor {
 	/**
 	 * Creates a decoupled editor instance.
 	 *
-	 * Creating instance when using the {@glink builds/index CKEditor build}:
+	 * Creating an instance when using the {@glink builds/index CKEditor build}:
 	 *
 	 *		DecoupledEditor
 	 *			.create( '<p>Editor data</p>', {
-	 *				// The location of the toolbar in DOM.
+	 *				// The location of the toolbar in the DOM.
 	 *				toolbarContainer: document.querySelector( 'body div.toolbar-container' ),
 	 *
-	 *				// The location of the editable in DOM.
+	 *				// The location of the editable in the DOM.
 	 *				editableContainer: document.querySelector( 'body div.editable-container' )
 	 *			} )
 	 *			.then( editor => {
@@ -98,7 +98,7 @@ export default class DecoupledEditor extends Editor {
 	 *				console.error( err.stack );
 	 *			} );
 	 *
-	 * Creating instance when using CKEditor from source (make sure to specify the list of plugins to load and the toolbar):
+	 * Creating an instance when using CKEditor from source (make sure to specify the list of plugins to load and the toolbar):
 	 *
 	 *		import DecoupledEditor from '@ckeditor/ckeditor5-editor-decoupled/src/decouplededitor';
 	 *		import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
@@ -111,10 +111,10 @@ export default class DecoupledEditor extends Editor {
 	 *				plugins: [ Essentials, Bold, Italic, ... ],
 	 *				toolbar: [ 'bold', 'italic', ... ],
 	 *
-	 *				// The location of the toolbar in DOM.
+	 *				// The location of the toolbar in the DOM.
 	 *				toolbarContainer: document.querySelector( 'div.toolbar-container' ),
 	 *
-	 *				// The location of the editable in DOM.
+	 *				// The location of the editable in the DOM.
 	 *				editableContainer: document.querySelector( 'div.editable-container' )
 	 *			} )
 	 *			.then( editor => {
@@ -124,9 +124,9 @@ export default class DecoupledEditor extends Editor {
 	 *				console.error( err.stack );
 	 *			} );
 	 *
-	 * **Note**: {@link module:core/editor/editorconfig~EditorConfig#toolbarContainer `config.toolbarContainer`} and
-	 * {@link module:core/editor/editorconfig~EditorConfig#editableContainer `config.editableContainer`} are optional. It is
-	 * possible to define the location of the UI elements manually once the editor is up and running:
+	 * **Note**: The {@link module:core/editor/editorconfig~EditorConfig#toolbarContainer `config.toolbarContainer`} and
+	 * {@link module:core/editor/editorconfig~EditorConfig#editableContainer `config.editableContainer`} settings are optional.
+	 * It is possible to define the location of the UI elements manually once the editor is up and running:
 	 *
 	 *		DecoupledEditor
 	 *			.create( '<p>Editor data</p>' )
@@ -171,7 +171,7 @@ export default class DecoupledEditor extends Editor {
 mix( DecoupledEditor, DataApiMixin );
 
 /**
- * A configuration of the {@link module:editor-decoupled/decouplededitor~DecoupledEditor}.
+ * The configuration of the {@link module:editor-decoupled/decouplededitor~DecoupledEditor}.
  *
  * When specified, it controls the location of the {@link module:editor-decoupled/decouplededitoruiview~DecoupledEditorUIView#toolbar}:
  *
@@ -187,7 +187,7 @@ mix( DecoupledEditor, DataApiMixin );
  *				console.error( error );
  *			} );
  *
- * **Note**: If not specified, the toolbar must be manually injected into DOM. See
+ * **Note**: If not specified, the toolbar must be manually injected into the DOM. See
  * {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create `DecoupledEditor.create()`}
  * to learn more.
  *
@@ -195,7 +195,7 @@ mix( DecoupledEditor, DataApiMixin );
  */
 
 /**
- * A configuration of the {@link module:editor-decoupled/decouplededitor~DecoupledEditor}.
+ * The configuration of the {@link module:editor-decoupled/decouplededitor~DecoupledEditor}.
  *
  * When specified, it controls the location of the {@link module:editor-decoupled/decouplededitoruiview~DecoupledEditorUIView#editable}:
  *
@@ -211,7 +211,7 @@ mix( DecoupledEditor, DataApiMixin );
  *				console.error( error );
  *			} );
  *
- * **Note**: If not specified, the editable must be manually injected into DOM. See
+ * **Note**: If not specified, the editable must be manually injected into the DOM. See
  * {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create `DecoupledEditor.create()`}
  * to learn more.
  *

+ 3 - 3
packages/ckeditor5-editor-decoupled/src/decouplededitorui.js

@@ -54,7 +54,7 @@ export default class DecoupledEditorUI {
 		this._toolbarConfig = normalizeToolbarConfig( editor.config.get( 'toolbar' ) );
 
 		/**
-		 * A container of the {@link module:editor-decoupled/decouplededitoruiview~DecoupledEditorUIView#toolbar}.
+		 * The container for the {@link module:editor-decoupled/decouplededitoruiview~DecoupledEditorUIView#toolbar}.
 		 *
 		 * @type {HTMLElement|String}
 		 * @private
@@ -62,7 +62,7 @@ export default class DecoupledEditorUI {
 		this._toolbarContainer = editor.config.get( 'toolbarContainer' );
 
 		/**
-		 * A container of the {@link module:editor-decoupled/decouplededitoruiview~DecoupledEditorUIView#editable}.
+		 * The container for the {@link module:editor-decoupled/decouplededitoruiview~DecoupledEditorUIView#editable}.
 		 *
 		 * @type {HTMLElement|String}
 		 * @private
@@ -79,7 +79,7 @@ export default class DecoupledEditorUI {
 
 		view.render();
 
-		// Setup the editable.
+		// Set up the editable.
 		const editingRoot = editor.editing.view.document.getRoot();
 		view.editable.bind( 'isReadOnly' ).to( editingRoot );
 		view.editable.bind( 'isFocused' ).to( editor.editing.view.document );

+ 8 - 8
packages/ckeditor5-editor-decoupled/src/decouplededitoruiview.js

@@ -13,14 +13,14 @@ import ToolbarView from '@ckeditor/ckeditor5-ui/src/toolbar/toolbarview';
 import Template from '@ckeditor/ckeditor5-ui/src/template';
 
 /**
- * The decoupled editor UI view. It's a virtual view providing an inline
+ * The decoupled editor UI view. It is a virtual view providing an inline
  * {@link module:editor-decoupled/decouplededitoruiview~DecoupledEditorUIView#editable} and a
  * {@link module:editor-decoupled/decouplededitoruiview~DecoupledEditorUIView#toolbar}, but without any
- * specific arrangement of the components in DOM.
+ * specific arrangement of the components in the DOM.
  *
  * See {@link module:core/editor/editorconfig~EditorConfig#toolbarContainer `config.toolbarContainer`} and
  * {@link module:core/editor/editorconfig~EditorConfig#editableContainer `config.editableContainer`} to
- * learn more about the UI of a decoupled editor.
+ * learn more about the UI of the decoupled editor.
  *
  * @extends module:ui/editorui/editoruiview~EditorUIView
  */
@@ -49,7 +49,7 @@ export default class DecoupledEditorUIView extends EditorUIView {
 		 */
 		this.editable = new InlineEditableUIView( locale );
 
-		// This toolbar may be placed anywhere in the page so things like font-size needs to be reset in it.
+		// This toolbar may be placed anywhere in the page so things like font size need to be reset in it.
 		Template.extend( this.toolbar.template, {
 			attributes: {
 				class: 'ck-reset_all'
@@ -60,11 +60,11 @@ export default class DecoupledEditorUIView extends EditorUIView {
 	}
 
 	/**
-	 * Destroys the view and removes {@link #toolbar} and {@link #editable}
-	 * {@link module:ui/view~View#element `element`} from DOM, if required.
+	 * Destroys the view and removes the {@link #toolbar} and {@link #editable}
+	 * {@link module:ui/view~View#element `element`} from the DOM, if required.
 	 *
-	 * @param {Boolean} [removeToolbar] When `true`, remove the {@link #toolbar} element from DOM.
-	 * @param {Boolean} [removeEditable] When `true`, remove the {@link #editable} element from DOM.
+	 * @param {Boolean} [removeToolbar] When `true`, remove the {@link #toolbar} element from the DOM.
+	 * @param {Boolean} [removeEditable] When `true`, remove the {@link #editable} element from the DOM.
 	 */
 	destroy( removeToolbar, removeEditable ) {
 		super.destroy();