Skip to content
This repository has been archived by the owner on Jun 26, 2020. It is now read-only.

Commit

Permalink
Merge branch 'master' into t/ckeditor5/742
Browse files Browse the repository at this point in the history
  • Loading branch information
Kamil Piechaczek committed Mar 28, 2018
2 parents ea6b83b + 1659a93 commit 6fc9e65
Show file tree
Hide file tree
Showing 5 changed files with 51 additions and 51 deletions.
44 changes: 22 additions & 22 deletions docs/framework/guides/document-editor.md
View file
Expand Up @@ -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}

Expand All @@ -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';
Expand All @@ -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">
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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;
Expand All @@ -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);
Expand Down Expand Up @@ -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. */
Expand All @@ -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
Expand All @@ -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;
Expand All @@ -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;
Expand All @@ -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;
Expand All @@ -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;
Expand All @@ -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.
2 changes: 1 addition & 1 deletion package.json
View file
Expand Up @@ -23,7 +23,7 @@
"eslint": "^4.15.0",
"eslint-config-ckeditor5": "^1.0.7",
"husky": "^0.14.3",
"lint-staged": "^6.0.0"
"lint-staged": "^7.0.0"
},
"engines": {
"node": ">=6.0.0",
Expand Down
34 changes: 17 additions & 17 deletions src/decouplededitor.js
View file
Expand Up @@ -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
Expand All @@ -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()`}.
Expand All @@ -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
Expand Down Expand Up @@ -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 => {
Expand All @@ -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';
Expand All @@ -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 => {
Expand All @@ -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>' )
Expand Down Expand Up @@ -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}:
*
Expand All @@ -187,15 +187,15 @@ 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.
*
* @member {HTMLElement} module:core/editor/editorconfig~EditorConfig#toolbarContainer
*/

/**
* 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}:
*
Expand All @@ -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.
*
Expand Down
6 changes: 3 additions & 3 deletions src/decouplededitorui.js
View file
Expand Up @@ -54,15 +54,15 @@ 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
*/
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
Expand All @@ -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 );
Expand Down

0 comments on commit 6fc9e65

Please sign in to comment.