Parcourir la source

Docs: title feature guide and snippet.

Piotr Jasiun il y a 6 ans
Parent
commit
4d1d438ff0

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

@@ -0,0 +1,48 @@
+<div id="snippet-title">
+</div>
+
+<h3>Console</h3>
+
+<pre><code class="title-console title-console__title">''</code></pre>
+<pre><code class="title-console title-console__body">''</code></pre>
+<pre><code class="title-console title-console__data">''</code></pre>
+
+<style>
+	#title-console {
+		max-height: 300px;
+		overflow: auto;
+		white-space: normal;
+		background: #2b2c26;
+		margin-top: 20px;
+		transition: background-color 500ms;
+	}
+
+	#title-console.updated {
+		background: green;
+	}
+
+	.title-console__title,
+	.title-console__body {
+		margin-bottom: 10px;
+	}
+
+	.title-console__title::before,
+	.title-console__body::before,
+	.title-console__data::before {
+		display: inline-block;
+		margin-right: 5px;
+		opacity: 0.5;
+	}
+
+	.title-console__title::before {
+		content: 'Title:'
+	}
+
+	.title-console__body::before {
+		content: 'Body:'
+	}
+
+	.title-console__data::before {
+		content: 'Data:';
+	}
+</style>

+ 64 - 0
packages/ckeditor5-heading/docs/_snippets/features/title.js

@@ -0,0 +1,64 @@
+/**
+ * @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 console, window, document, setTimeout */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import Title from '@ckeditor/ckeditor5-heading/src/title';
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor.builtinPlugins.push( Title );
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-title' ), {
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.editor = editor;
+
+		const titlePlugin = editor.plugins.get( 'Title' );
+		const titleConsole = new Console( document.querySelector( '.title-console__title' ) );
+		const bodyConsole = new Console( document.querySelector( '.title-console__body' ) );
+		const dataConsole = new Console( document.querySelector( '.title-console__data' ) );
+
+		editor.model.document.on( 'change:data', () => {
+			titleConsole.update( titlePlugin.getTitle() );
+			bodyConsole.update( titlePlugin.getBody() );
+			dataConsole.update( editor.getData() );
+		} );
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );
+
+class Console {
+	constructor( element ) {
+		this.element = element;
+		this.consoleUpdates = 0;
+		this.previousData = '';
+	}
+
+	update( data ) {
+		if ( this.previousData == data ) {
+			return;
+		}
+
+		this.previousData = data;
+
+		const element = this.element;
+
+		this.consoleUpdates++;
+
+		element.classList.add( 'updated' );
+		element.textContent = `'${ data }'`;
+
+		setTimeout( () => {
+			if ( --this.consoleUpdates == 0 ) {
+				element.classList.remove( 'updated' );
+			}
+		}, 500 );
+	}
+}

+ 45 - 0
packages/ckeditor5-heading/docs/features/title.md

@@ -0,0 +1,45 @@
+---
+category: features
+---
+
+# Title
+
+The {@link module:heading/title~Title} feature add support for the title field to your document. It makes sure that there will be always a single title field at the beginning of your document.
+
+## Demo
+
+{@snippet features/title}
+
+## Keyboard navigation
+
+Title plugin let you navigate between title and body element using <kbd>Tab</kbd> and back, using <kbd>Shift</kbd> + <kbd>Tab</kbd>, providing form-line experience, as well as as use <kbd>Enter</kbd> and <kbd>Backspace</kbd> keys to move caret between title and body.
+
+## Placehoder integration
+
+Title plugin is integrated with the {@link features/editor-placeholder placeholder} configuration. If you define it, it will be users as the placeholder for the body element.
+
+## Installation
+
+To add this feature to your editor, install the [`@ckeditor/ckeditor5-heading`](https://www.npmjs.com/package/@ckeditor/ckeditor5-heading) package:
+
+```bash
+npm install --save @ckeditor/ckeditor5-heading
+```
+
+Then add the `Title` plugin to your plugin list:
+
+```js
+import Title from '@ckeditor/ckeditor5-heading/src/title';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Title, ... ]
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+

+ 10 - 2
packages/ckeditor5-heading/src/title.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 
+/**
+ * @module heading/title
+ */
+
 import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import Enter from '@ckeditor/ckeditor5-enter/src/enter';
 import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';
@@ -88,7 +92,7 @@ export default class Title extends Plugin {
 	}
 
 	/**
-	 * Sets the title of the document.
+	 * Sets the title of the document. This methods does not change any content outside the title element.
 	 *
 	 * @param {String} data Data to be set as a document title.
 	 */
@@ -100,7 +104,11 @@ export default class Title extends Plugin {
 	}
 
 	/**
-	 * Returns the title of the document.
+	 * Returns the title of the document. Note, that because this plugins does not allows any formatting inside
+	 * the title element, output of this method will be plain text, with no HTML tags. However, the title element
+	 * may contains some markers, like {@link features/comments#comments-markup comments} or
+	 * {@link features/track-changes#suggestions-markup suggestions} markers. In such case a special tag for the
+	 * marker will be included in the title text.
 	 *
 	 * @returns {String} Title of the document.
 	 */