8
0
Quellcode durchsuchen

Docs: Added block toolbar documentation.

Aleksander Nowodzinski vor 7 Jahren
Ursprung
Commit
7ac34b1eb8

+ 12 - 0
packages/ckeditor5-ui/docs/_snippets/features/blocktoolbar.html

@@ -0,0 +1,12 @@
+<div id="snippet-block-toolbar">
+	<h2>The three greatest things you learn from traveling</h2>
+	<p>Like all the great things on earth traveling teaches us by example. Here are some of the most precious lessons I’ve learned over the years of traveling.</p>
+	<h3>Appreciation of diversity</h3>
+	<p>Getting used to an entirely different culture can be challenging. While it’s also nice to learn about cultures online or from books, nothing comes close to experiencing cultural diversity in person. You learn to appreciate each and every single one of the differences while you become more culturally fluid.</p>
+</div>
+
+<style>
+	.ck.ck-block-toolbar-button {
+		transform: translateX( -10px );
+	}
+</style>

+ 29 - 0
packages/ckeditor5-ui/docs/_snippets/features/blocktoolbar.js

@@ -0,0 +1,29 @@
+/**
+ * @license Copyright (c) 2003-2018, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals console, window, document */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import BlockToolbar from '@ckeditor/ckeditor5-ui/src/toolbar/block/blocktoolbar';
+import HeadingButtonsUI from '@ckeditor/ckeditor5-heading/src/headingbuttonsui';
+import ParagraphButtonUI from '@ckeditor/ckeditor5-paragraph/src/paragraphbuttonui';
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-block-toolbar' ), {
+		plugins: ClassicEditor.build.plugins.concat( [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI ] ),
+		toolbar: {
+			items: [ 'bold', 'italic', 'code', 'link', 'blockQuote', 'undo', 'redo' ],
+			viewportTopOffset: 60
+		},
+		blockToolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', '|', 'bulletedList', 'numberedList' ],
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.editorBasic = editor;
+	} )
+	.catch( err => {
+		console.error( err );
+	} );

+ 65 - 0
packages/ckeditor5-ui/docs/features/blocktoolbar.md

@@ -0,0 +1,65 @@
+---
+title: Block toolbar
+category: features
+---
+
+The {@link module:ui/toolbar/block/blocktoolbar~BlockToolbar} plugin provides an additional [configurable](#configuration) toolbar on the left-hand side of the content area (the gutter). The toolbar is represented by a button with a pilcrow (&#182;) and positioned next to the block element that the selection is anchored to (e.g. a paragraph), following the caret as the user edits the content and navigates the document.
+
+Because the toolbar is always connected to the block of content, it naturally gives accommodation to the features which modify entire blocks (e.g. create headers, paragraphs) rather than inline styles (e.g. bold, italic, etc.).
+
+## Example
+
+<info-box hint>
+	Move the caret around to see the block toolbar button following the selection. Click the button to use the toolbar.
+</info-box>
+
+{@snippet features/blocktoolbar}
+
+## Configuration
+
+The content of toolbar can be defined using the {@link module:core/editor/editorconfig~EditorConfig#blockToolbar} configuration. See the [installation instruction](#installation) to learn more.
+
+To adjust the position of the block toolbar button to match the styles of your website, use the CSS `transform` property:
+
+```css
+.ck.ck-block-toolbar-button {
+	transform: translateX( -10px );
+}
+```
+
+## Installation
+
+<info-box hint>
+	Remember to add proper features to the editor configuration first. The block toolbar provides a space for the buttons, it does not bring the actual features. For example: the `heading1` button will not work if there is no {@link features/headings Headings} feature in the editor.
+</info-box>
+
+To add this feature to your editor install the [`@ckeditor/ckeditor5-ui`](https://www.npmjs.com/package/@ckeditor/ckeditor5-ui) package:
+
+```
+npm install --save @ckeditor/ckeditor5-ui
+```
+
+And add it to your plugin list:
+
+```js
+import BlockToolbar from '@ckeditor/ckeditor5-ui/src/toolbar/block/blocktoolbar';
+import HeadingButtonsUI from '@ckeditor/ckeditor5-heading/src/headingbuttonsui';
+import ParagraphButtonUI from '@ckeditor/ckeditor5-paragraph/src/paragraphbuttonui';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ BlockToolbar, ParagraphButtonUI, HeadingButtonsUI, ... ],
+		blockToolbar: [ 'paragraph', 'heading1', 'heading2', 'heading3', '|', 'bulletedList', 'numberedList' ]
+		toolbar: [ ... ]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/development/installing-plugins installing plugins}.
+</info-box>
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-ui.