Przeglądaj źródła

Add block indentation feature guide stub.

Maciej Gołaszewski 6 lat temu
rodzic
commit
bd6fc30596

+ 0 - 0
packages/ckeditor5-indent/docs/_snippets/features/build-indent-block-source.html


+ 14 - 0
packages/ckeditor5-indent/docs/_snippets/features/build-indent-block-source.js

@@ -0,0 +1,14 @@
+/**
+ * @license Copyright (c) 2003-2019, 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 IndentBlock from '@ckeditor/ckeditor5-indent-block/src/indentblock';
+
+ClassicEditor.builtinPlugins.push( IndentBlock );
+
+window.ClassicEditor = ClassicEditor;

+ 37 - 0
packages/ckeditor5-indent/docs/_snippets/features/custom-indent-block-classes.html

@@ -0,0 +1,37 @@
+<style>
+	.custom-block-indent-a {
+		margin-left: 10%;
+	}
+
+	.custom-block-indent-b {
+		margin-left: 20%;
+	}
+
+	.custom-block-indent-c {
+		margin-left: 30%;
+	}
+
+	.custom-block-indent-d {
+		margin-left: 40%;
+	}
+
+	.custom-block-indent-e {
+		margin-left: 50%;
+	}
+</style>
+
+<div id="snippet-indent-block-classes">
+	<h2 class="custom-block-indent-b">
+		This heading has second indentation class set.
+	</h2>
+
+	<p>
+		This paragraph has no indentation.<br>
+		Cookie chupa chups marshmallow jelly beans. Bear claw chocolate bar chupa chups oat cake caramels chupa chups oat cake marzipan. Candy chupa chups chocolate. Cake soufflé candy canes fruitcake jelly-o oat cake. Macaroon tootsie roll candy marzipan sesame snaps cupcake wafer gingerbread. Oat cake cake cake sesame snaps pastry halvah.
+	</p>
+
+	<p class="custom-block-indent-e">
+		This paragraph has fifth (last) indentation class set.<br>
+		Cookie chupa chups marshmallow jelly beans. Bear claw chocolate bar chupa chups oat cake caramels chupa chups oat cake marzipan. Candy chupa chups chocolate. Cake soufflé candy canes fruitcake jelly-o oat cake. Macaroon tootsie roll candy marzipan sesame snaps cupcake wafer gingerbread. Oat cake cake cake sesame snaps pastry halvah.
+	</p>
+</div>

+ 43 - 0
packages/ckeditor5-indent/docs/_snippets/features/custom-indent-block-classes.js

@@ -0,0 +1,43 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-indent-block-classes' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'indent',
+				'outdent',
+				'|',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		indentBlock: {
+			classes: [
+				'custom-block-indent-a',
+				'custom-block-indent-b',
+				'custom-block-indent-c',
+				'custom-block-indent-d',
+				'custom-block-indent-e'
+			]
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 21 - 0
packages/ckeditor5-indent/docs/_snippets/features/indent-block.html

@@ -0,0 +1,21 @@
+<div id="snippet-indent-block">
+	<p>
+		This paragraph has no indentation.<br>
+		Cookie chupa chups marshmallow jelly beans. Bear claw chocolate bar chupa chups oat cake caramels chupa chups oat cake marzipan. Candy chupa chups chocolate. Cake soufflé candy canes fruitcake jelly-o oat cake. Macaroon tootsie roll candy marzipan sesame snaps cupcake wafer gingerbread. Oat cake cake cake sesame snaps pastry halvah.
+	</p>
+
+	<p style="margin-left:100px;">
+		This paragraph has indentation of 100px (second indentation step).<br>
+		Cookie chupa chups marshmallow jelly beans. Bear claw chocolate bar chupa chups oat cake caramels chupa chups oat cake marzipan. Candy chupa chups chocolate. Cake soufflé candy canes fruitcake jelly-o oat cake. Macaroon tootsie roll candy marzipan sesame snaps cupcake wafer gingerbread. Oat cake cake cake sesame snaps pastry halvah.
+	</p>
+
+	<p style="margin-left:75px;">
+		This paragraph has indentation of 75px (between indentation step 1 and 2).<br>
+		Cookie chupa chups marshmallow jelly beans. Bear claw chocolate bar chupa chups oat cake caramels chupa chups oat cake marzipan. Candy chupa chups chocolate. Cake soufflé candy canes fruitcake jelly-o oat cake. Macaroon tootsie roll candy marzipan sesame snaps cupcake wafer gingerbread. Oat cake cake cake sesame snaps pastry halvah.
+	</p>
+
+	<p style="margin-left:50px;">
+		This paragraph has indentation of 50px (second indentation step).<br>
+		Cookie chupa chups marshmallow jelly beans. Bear claw chocolate bar chupa chups oat cake caramels chupa chups oat cake marzipan. Candy chupa chups chocolate. Cake soufflé candy canes fruitcake jelly-o oat cake. Macaroon tootsie roll candy marzipan sesame snaps cupcake wafer gingerbread. Oat cake cake cake sesame snaps pastry halvah.
+	</p>
+</div>

+ 38 - 0
packages/ckeditor5-indent/docs/_snippets/features/indent-block.js

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-indent-block' ), {
+		cloudServices: CS_CONFIG,
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'indent',
+				'outdent',
+				'|',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		indentBlock: {
+			offset: 50,
+			unit: 'px'
+		}
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 141 - 0
packages/ckeditor5-indent/docs/features/indent-block.md

@@ -0,0 +1,141 @@
+---
+title: Block indentation
+category: features
+---
+
+{@snippet features/build-indent-block-source}
+
+## Demo
+
+The block indentation feature allows to set indentation of text blocks like paragraphs or headings.
+
+{@snippet features/indent-block}
+
+## Configuring the block indentation feature
+
+### Using offset and unit
+
+By default the block indentation is controlled by setting the indentation step offset and unit. Executing indent (or outdent) commands will increase (or decreas) current block indentation by given offset.
+
+The editor ind the {@link features/indent-block#demo demo} section was configured using offset and unit:
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		toolbar: {
+			items: [ 'heading', '|', 'indent', 'outdent', '|', 'bulletedList', 'numberedList', '|', 'undo', 'redo' ]
+		},
+		indentBlock: {
+			offset: 50,
+			unit: 'px'
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+### Using CSS classes
+
+Alternatively the block indentation feature can be configured to set indentation by applying one of defined CSS classes:
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		toolbar: {
+			items: [ 'heading', '|', 'indent', 'outdent', '|', 'bulletedList', 'numberedList', '|', 'undo', 'redo' ]
+		},
+		indentBlock: {
+			classes: [
+				'custom-block-indent-a', // First step - smallest indentation.
+				'custom-block-indent-b',
+				'custom-block-indent-c',
+				'custom-block-indent-d',
+				'custom-block-indent-e'  // Last step - biggest indentation.
+			]
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+The editor will restrict indentation levels to a set of provided classes. The biggest indentation is the class that has last index in the array.
+
+In the demo below the CSS classes are defined as follows:
+
+```css
+	.custom-block-indent-a {
+		margin-left: 10%;
+	}
+
+	.custom-block-indent-b {
+		margin-left: 20%;
+	}
+
+	.custom-block-indent-c {
+		margin-left: 30%;
+	}
+
+	.custom-block-indent-d {
+		margin-left: 40%;
+	}
+
+	.custom-block-indent-e {
+		margin-left: 50%;
+	}
+```
+
+{@snippet features/custom-indent-block-classes}
+
+## Installation
+
+To add this feature to your editor, install the [`@ckeditor/ckeditor5-indent-block`](https://www.npmjs.com/package/@ckeditor/ckeditor5-indent-block) package:
+
+```bash
+npm install --save @ckeditor/ckeditor5-indent-block
+```
+
+Then add it to your plugin list and the toolbar configuration:
+
+```js
+import Font from '@ckeditor/ckeditor5-indent-block/src/indentblock';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ IndentBlock, ... ],
+		toolbar: [ 'indent', 'outdent', ... ]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
+## Common API
+
+The {@link module:indent-block/indentblock~IndentBlock} plugin registers the following components:
+
+* The {@link module:indent-block/indentblockcommand~IndentBlockCommand `'indentBlock'`} command.
+
+	You can increase block indentation in which the selection is set by:
+
+	```js
+	editor.execute( 'indentBlock' );
+	```
+
+* The {@link module:indent-block/indentblockcommand~IndentBlockCommand `'outdentBlock'`} command.
+
+	You can decrease block indentation in which the selection is set by:
+
+	```js
+	editor.execute( 'outdentBlock' );
+	```
+
+<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.
+</info-box>
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-font.