浏览代码

Docs: Created Editor placeholder guide.

Aleksander Nowodzinski 6 年之前
父节点
当前提交
8a4e359abc
共有 3 个文件被更改,包括 91 次插入0 次删除
  1. 3 0
      docs/_snippets/features/placeholder.html
  2. 19 0
      docs/_snippets/features/placeholder.js
  3. 69 0
      docs/features/placeholder.md

+ 3 - 0
docs/_snippets/features/placeholder.html

@@ -0,0 +1,3 @@
+<div id="snippet-placeholder">
+	<p></p>
+</div>

+ 19 - 0
docs/_snippets/features/placeholder.js

@@ -0,0 +1,19 @@
+/**
+ * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/* globals console, window, document */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-placeholder' ), {
+		placeholder: 'Type the content here!'
+	} )
+	.then( editor => {
+		window.editor = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

+ 69 - 0
docs/features/placeholder.md

@@ -0,0 +1,69 @@
+---
+category: features
+---
+
+# Editor placeholder
+
+CKEditor 5 can display a configurable placeholder text when the content is empty. The placeholder helps users locate the editor in the application and prompts to input the content. It works similarly to the native DOM [`placeholder` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#The_placeholder_attribute) used by inputs.
+
+See the demo of the placeholder feature:
+
+{@snippet features/placeholder}
+
+## Configuring the placeholder
+
+There are two different ways of configuring the editor placeholder text:
+
+### Using the DOM attribute
+
+Set the `placeholder` attribute on an element passed to the `Editor.create()` method (for instance {@link module:editor-classic/classiceditor~ClassicEditor.create `ClassicEditor.create()`}) to configure the placeholder:
+
+```html
+<div id="editor" placeholder="Type the content here!">
+	<p>Editor content</p>
+</div>
+```
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ) )
+	.then( editor => {
+		console.log( editor );
+	} )
+	.catch( error => {
+		console.error( error );
+	} );
+```
+
+### Using the editor configuration
+
+You can use the {@link module:core/editor/editorconfig~EditorConfig#placeholder `editor.config.placeholder`} configuration option:
+
+* when no element was passed into `Editor.create()` method,
+* to override the `placeholder` attribute value, for instance, if an element was passed into `Editor.create()` but the placeholder text should be different.
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		placeholder: 'Type the content here!'
+	} )
+	.then( editor => {
+		console.log( editor );
+	} )
+	.catch( error => {
+		console.error( error );
+	} );
+```
+
+## Styling the placeholder
+
+The editor placeholder text is displayed using a CSS pseudo–element (`::before`) related to the first empty element in the editor content (usually a paragraph). You can use the following snippet to change the appearance of the placeholder:
+
+```css
+.ck.ck-editor__editable > .ck-placeholder::before {
+    color: #ff7e7e;
+    font-family: Georgia;
+}
+```
+
+**Note**: The `.ck-placeholder` class is also used to display placeholders in other places, for instance, {@link features/image#image-captions image captions}. Make sure your custom styles apply to the right subset of placeholders.