浏览代码

Merge pull request #8281 from ckeditor/docs-heading-buttons

Docs (heading): Expanded the heading feature documentation with toolbar buttons feature info. Closes: #982.
Anna Tomanek 5 年之前
父节点
当前提交
700f2de5ad

+ 5 - 0
packages/ckeditor5-heading/docs/_snippets/features/custom-heading-buttons.html

@@ -0,0 +1,5 @@
+<div id="snippet-custom-heading-buttons">
+	<h1>Heading 1</h1>
+	<h2>Heading 2</h2>
+	<p>This is <a href="https://ckeditor.com">CKEditor 5</a>.</p>
+</div>

+ 26 - 0
packages/ckeditor5-heading/docs/_snippets/features/custom-heading-buttons.js

@@ -0,0 +1,26 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/* globals ClassicEditor, console, document, window */
+ClassicEditor
+	.create( document.querySelector( '#snippet-custom-heading-buttons' ), {
+		toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', 'heading4', 'heading5', 'heading6', '|', 'undo', 'redo' ],
+		heading: {
+			options: [
+				{ model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
+				{ model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
+				{ model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
+				{ model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
+				{ model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
+				{ model: 'heading5', view: 'h5', title: 'Heading 5', class: 'ck-heading_heading5' },
+				{ model: 'heading6', view: 'h6', title: 'Heading 6', class: 'ck-heading_heading6' }
+			]
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 9 - 0
packages/ckeditor5-heading/docs/_snippets/features/heading-buttons.html

@@ -0,0 +1,9 @@
+<div id="snippet-heading-buttons">
+	<h1>Choosing the best user experience</h1>
+	<h2>Usability</h2>
+	<p>There are certain situations, both user-oriented or context-dependent, in which different solutions work better. Splitting the heading dropdown into separate buttons does certainly speed up the access, while at the same time taking up more space. It is up to the user to decide whether easier accessability prevails over a tidy toolbar.</p>
+	<h2>Personal preference</h2>
+	<p>Usability and editing needs might be one of the factors but still there is the personal preference &mdash; the user's previous experience and habits might come forth and be a decisive factor.</p>
+	<h2>Flexibility</h2>
+	<p>Whatever the reason may be to use both the standard heading dropdown list or the separate heading toolbar buttons, <a href="https://ckeditor.com/">CKEditor 5</a> WYSIWYG editor offers both of these options for greater comfort of rich-text creation and user satisfaction.</p>
+</div>

+ 23 - 0
packages/ckeditor5-heading/docs/_snippets/features/heading-buttons.js

@@ -0,0 +1,23 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/* globals ClassicEditor, console, document, window */
+ClassicEditor
+	.create( document.querySelector( '#snippet-heading-buttons' ), {
+		toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', '|', 'undo', 'redo' ],
+		heading: {
+			options: [
+				{ model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
+				{ model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
+				{ model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
+				{ model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' }
+			]
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 0 - 0
packages/ckeditor5-heading/docs/_snippets/features/heading-source.html


+ 13 - 0
packages/ckeditor5-heading/docs/_snippets/features/heading-source.js

@@ -0,0 +1,13 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/* globals window */
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import HeadingButtonsUI from '@ckeditor/ckeditor5-heading/src/headingbuttonsui';
+import ParagraphButtonUI from '@ckeditor/ckeditor5-paragraph/src/paragraphbuttonui';
+ClassicEditor.builtinPlugins.push(
+	HeadingButtonsUI,
+	ParagraphButtonUI
+);
+window.ClassicEditor = ClassicEditor;

+ 61 - 4
packages/ckeditor5-heading/docs/features/headings.md

@@ -4,10 +4,12 @@ category: features
 
 
 # Headings
 # Headings
 
 
-{@snippet build-classic-source}
+{@snippet features/heading-source}
 
 
 The {@link module:heading/heading~Heading} feature enables support for headings. These are used by the creators to structure their documents. They also aid both the readers, making the content more organized and easier to read, and the search indexers scanning for crucial information.
 The {@link module:heading/heading~Heading} feature enables support for headings. These are used by the creators to structure their documents. They also aid both the readers, making the content more organized and easier to read, and the search indexers scanning for crucial information.
 
 
+Headings can easily be added with toolbar dropdown, buttons or with {@link features/autoformat Markdown code} as you type. They can also be cleared with the {@link features/remove-format remove format} feature.
+
 <info-box info>
 <info-box info>
 	This feature is enabled by default in all builds.
 	This feature is enabled by default in all builds.
 </info-box>
 </info-box>
@@ -28,22 +30,31 @@ By default, when your editor build does not include the title plugin, a `<h1>` e
 
 
 ## Demo
 ## Demo
 
 
+Use the toolbar dropdown to style a heading, or type one or more `#` characters (depending on the heading level), followed by a space, to start a new heading with the {@link features/autoformat autoformatting feature}.
+
 {@snippet features/default-headings}
 {@snippet features/default-headings}
 
 
+## Heading buttons
+
+The heading feature lets you also use a set of heading buttons instead of the dropdown list. The toolbar buttons are configurable and it is possible to include a paragraph button, too. Compare the heading toolbar dropdown from the demo above with the heading buttons below to check the functionality and usability of this variation.
+
+{@snippet features/heading-buttons}
+
 ## Related features
 ## Related features
 
 
 There are more CKEditor 5 features that can help you format your content:
 There are more CKEditor 5 features that can help you format your content:
 * {@link features/basic-styles Basic font styles} &ndash; The essentials, like **bold**, *italic* and others.
 * {@link features/basic-styles Basic font styles} &ndash; The essentials, like **bold**, *italic* and others.
 * {@link features/title Document title} &ndash; Clearly divide your content into a title and body.
 * {@link features/title Document title} &ndash; Clearly divide your content into a title and body.
 * {@link features/indent Block indentation}  &ndash; Set indentation for text blocks such as paragraphs or lists.
 * {@link features/indent Block indentation}  &ndash; Set indentation for text blocks such as paragraphs or lists.
-* {@link features/lists Lists}  &ndash; Organize your content better with ordered and unordered list you can style.
+* {@link features/lists Lists}  &ndash; Organize your content better with ordered and unordered lists you can style.
 * {@link features/remove-format Remove format} &ndash; Easily clean basic text formatting.
 * {@link features/remove-format Remove format} &ndash; Easily clean basic text formatting.
+* {@link features/autoformat Autoformatting} &ndash; Add formatting elements (such as headings) as you type with Markdown code.
 
 
 ## Configuration
 ## Configuration
 
 
 ### Configuring heading levels
 ### Configuring heading levels
 
 
-It is, of course, possible to configure which heading levels the editor should support and how they should be named in the Headings dropdown. Use the {@link module:heading/heading~HeadingConfig#options `heading.options`} configuration option to do so.
+You can configure which heading levels the editor will support and how they should be named in the Headings dropdown. Use the {@link module:heading/heading~HeadingConfig#options `heading.options`} configuration option to do so.
 
 
 For example, the following editor will support only two levels of headings &mdash; `<h1>` and `<h2>`:
 For example, the following editor will support only two levels of headings &mdash; `<h1>` and `<h2>`:
 
 
@@ -124,6 +135,32 @@ ClassicEditor
 
 
 {@snippet features/custom-heading-elements}
 {@snippet features/custom-heading-elements}
 
 
+### Configuring toolbar buttons
+
+In order to use individual toolbar buttons instead of the heading dropdown, you need to properly configure the feature. You also need to import proper UI elements; see the [installation section](#installation-with-toolbar-heading-buttons) for instructions on how to do it.
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		toolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', 'heading4', 'heading5', 'heading6', '|', 'undo', 'redo' ],
+		heading: {
+			options: [
+				{ model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
+				{ model: 'heading1', view: 'h1', title: 'Heading 1', class: 'ck-heading_heading1' },
+				{ model: 'heading2', view: 'h2', title: 'Heading 2', class: 'ck-heading_heading2' },
+				{ model: 'heading3', view: 'h3', title: 'Heading 3', class: 'ck-heading_heading3' },
+				{ model: 'heading4', view: 'h4', title: 'Heading 4', class: 'ck-heading_heading4' },
+				{ model: 'heading5', view: 'h5', title: 'Heading 5', class: 'ck-heading_heading5' },
+				{ model: 'heading6', view: 'h6', title: 'Heading 6', class: 'ck-heading_heading6' }
+			]
+		}
+	} )
+	.then( ... )
+    .catch( ... );
+```
+{@snippet features/custom-heading-buttons}
+
+
 ## Installation
 ## Installation
 
 
 <info-box info>
 <info-box info>
@@ -150,6 +187,15 @@ ClassicEditor
 	.catch( ... );
 	.catch( ... );
 ```
 ```
 
 
+### Installation with toolbar heading buttons
+
+In order to be able to configure the toolbar buttons for headings and paragraph, you need to import the following into your plugin list and configuration:
+
+```js
+import HeadingButtonsUI from '@ckeditor/ckeditor5-heading/src/headingbuttonsui';
+import ParagraphButtonUI from '@ckeditor/ckeditor5-paragraph/src/paragraphbuttonui';
+```
+
 <info-box info>
 <info-box info>
 	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
 	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
 </info-box>
 </info-box>
@@ -159,13 +205,24 @@ ClassicEditor
 The {@link module:heading/heading~Heading} plugin registers:
 The {@link module:heading/heading~Heading} plugin registers:
 
 
 * The `'heading'` dropdown.
 * The `'heading'` dropdown.
-* The `'heading'` command that accepts value based on the {@link module:heading/heading~HeadingConfig#options `heading.options`} configuration option.
+* The `'heading'` command that accepts a value based on the {@link module:heading/heading~HeadingConfig#options `heading.options`} configuration option.
 
 
 	You can turn the currently selected block(s) to headings by executing one of these commands:
 	You can turn the currently selected block(s) to headings by executing one of these commands:
 
 
 	```js
 	```js
 	editor.execute( 'heading', { value: 'heading2' } );
 	editor.execute( 'heading', { value: 'heading2' } );
 	```
 	```
+ 
+The {@link module:heading/headingbuttonsui~HeadingButtonsUI} plugin registers six UI button components that will execute the `'heading'` command with the proper value of the `value` attribute:
+
+* `'heading1'`
+* `'heading2'`
+* `'heading3'`
+* `'heading4'`
+* `'heading5'`
+* `'heading6'`
+    
+The {@link module:paragraph/paragraphbuttonui~ParagraphButtonUI} plugin registers the UI button component: `'paragraph'`.
 
 
 <info-box>
 <info-box>
 	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.
 	We recommend using the official {@link framework/guides/development-tools#ckeditor-5-inspector CKEditor 5 inspector} for development and debugging. It will give you tons of useful information about the state of the editor such as internal data structures, selection, commands, and many more.

+ 1 - 1
packages/ckeditor5-paragraph/src/paragraphbuttonui.js

@@ -12,7 +12,7 @@ import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
 import icon from '../theme/icons/paragraph.svg';
 import icon from '../theme/icons/paragraph.svg';
 
 
 /**
 /**
- * This plugin defines the `'paragraphs'` button. It can be used together with
+ * This plugin defines the `'paragraph'` button. It can be used together with
  * {@link module:heading/headingbuttonsui~HeadingButtonsUI} to replace the standard heading dropdown.
  * {@link module:heading/headingbuttonsui~HeadingButtonsUI} to replace the standard heading dropdown.
  *
  *
  * This plugin is not loaded automatically by the {@link module:paragraph/paragraph~Paragraph} plugin. It must
  * This plugin is not loaded automatically by the {@link module:paragraph/paragraph~Paragraph} plugin. It must