8
0
Просмотр исходного кода

Add sections on isLimit and isObject to the schema guide. Closes: #6829

Tomek Wytrębowicz 5 лет назад
Родитель
Сommit
956fbd852c

+ 43 - 1
packages/ckeditor5-engine/docs/framework/guides/deep-dive/schema.md

@@ -8,7 +8,7 @@ This article assumes that you have already read the {@link framework/guides/arch
 
 ## Quick recap
 
-The editor's schema is available in the {@link module:engine/model/model~Model#schema `editor.model.schema`} property. It defines allowed model structures (how model elements can be nested) and allowed attributes (of both elements and text nodes). This information is later used by editing features and the editing engine to decide how to process the model, where to enable features, etc.
+The editor's schema is available in the {@link module:engine/model/model~Model#schema `editor.model.schema`} property. It defines allowed model structures (how model elements can be nested), allowed attributes (of both elements and text nodes), and other characteristics (inline vs. block, atomicity in regards of external actions). This information is later used by editing features and the editing engine to decide how to process the model, where to enable features, etc.
 
 Schema rules can be defined by using the {@link module:engine/model/schema~Schema#register `Schema#register()`} or {@link module:engine/model/schema~Schema#extend `Schema#extend()`} methods. The former can be used only once for a given item name which ensures that only a single editing feature can introduce this item. Similarly, `extend()` can only be used for defined items.
 
@@ -44,6 +44,48 @@ While this would be incorrect:
 </$root>
 ```
 
+## Declaring as a limit element
+
+Consider a feature like an image caption. The caption text area should construct a boundary to some internal actions.
+
+ - A selection that starts inside should not end outside.
+ - Pressing <kbd>Backspace</kbd> or <kbd>Delete</kbd> should not delete the area. Pressing <kbd>Enter</kbd> should not split the area.
+
+ It should also act as a boundary for external actions:
+
+ - A selection that starts outside, should not end inside.
+
+```js
+schema.register( 'myCaption', {
+    isLimit: true
+} );
+```
+
+{@link module:engine/model/schema~SchemaItemDefinition#isLimit `isLimit`} makes the engine construct such boundaries, and let {@link module:engine/model/utils/selection-post-fixer `selection-post-fixer`} update the user's selection if needed.
+
+<info-box>
+    "Limit element" does not mean "editable element". The concept of "editability" is reserved for the view and expressed by {@link module:engine/view/editableelement~EditableElement `EditableElement` class}.
+</info-box>
+
+## Declaring as a self-sufficient object
+
+For the image caption as in the example above it does not make much sense to select the caption box, then copy or drag it somewhere else.
+A caption without the image it describes does not make much sense. However, the image is more self-sufficient. Most likely users should be able to select the entire image (with all its internals), then copy or move it around. {@link module:engine/model/schema~SchemaItemDefinition#isObject `isObject`} should be used to mark such behavior.
+
+```js
+schema.register( 'myImage', {
+    isObject: true
+} );
+```
+
+Every "object" is also a "limit" element. 
+
+<info-box>
+    It means for every element with `isObject` set to `true`, {@link module:engine/model/schema~Schema#isLimit `schema.isLimit( element )`} will always return `true`. 
+
+    However, {@link module:engine/model/schema~Schema#getDefinition `schema.getDefinition( 'element' )`} may return `false` in a case when `{ isLimit: true, isObject: true}` was registered.
+</info-box>
+
 ## Generic items
 
 There are three basic generic items: `$root`, `$block` and `$text`. They are defined as follows:

+ 25 - 9
packages/ckeditor5-engine/src/model/schema.js

@@ -220,7 +220,9 @@ export default class Schema {
 
 	/**
 	 * Returns `true` if the given item is defined to be
-	 * a limit element by {@link module:engine/model/schema~SchemaItemDefinition}'s `isLimit` or `isObject` property
+	 * a limit element by {@link module:engine/model/schema~SchemaItemDefinition}'s
+	 * {@link module:engine/model/schema~SchemaItemDefinition#isLimit `isLimit`} or
+	 * {@link module:engine/model/schema~SchemaItemDefinition#isObject `isObject`} property
 	 * (all objects are also limits).
 	 *
 	 *		schema.isLimit( 'paragraph' ); // -> false
@@ -228,6 +230,8 @@ export default class Schema {
 	 *		schema.isLimit( editor.model.document.getRoot() ); // -> true
 	 *		schema.isLimit( 'image' ); // -> true
 	 *
+	 * See the {@glink framework/guides/deep-dive/schema "Schema" deep dive} guide.
+	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
 	 */
 	isLimit( item ) {
@@ -1023,8 +1027,8 @@ mix( Schema, ObservableMixin );
  * * {@link #isLimit `isLimit`} &ndash; It can be understood as whether this element should not be split by <kbd>Enter</kbd>.
  * Examples of limit elements: `$root`, table cell, image caption, etc. In other words, all actions that happen inside
  * a limit element are limited to its content. **Note:** All objects (`isObject`) are treated as limit elements, too.
- * * {@link #isObject `isObject`} &ndash; Whether an item is "self-contained" and should be treated as a whole. Examples of object elements:
- * `image`, `table`, `video`, etc. **Note:** An object is also a limit, so
+ * * {@link #isObject `isObject`} &ndash; Whether an item is "self-contained" and should be treated as a whole.
+ * Examples of object elements: `image`, `table`, `video`, etc. **Note:** An object is also a limit, so
  * {@link module:engine/model/schema~Schema#isLimit `isLimit()`} returns `true` for object elements automatically.
  *
  * # Generic items
@@ -1121,18 +1125,30 @@ mix( Schema, ObservableMixin );
  * @property {String|Array.<String>} inheritTypesFrom Inherits `is*` properties of other items.
  * @property {String} inheritAllFrom A shorthand for `allowContentOf`, `allowWhere`, `allowAttributesOf`, `inheritTypesFrom`.
  *
- * @property {Boolean} isBlock Whether this item is paragraph-like. Generally speaking, content is usually made out of blocks
+ * @property {Boolean} isBlock
+ * Whether this item is paragraph-like. Generally speaking, content is usually made out of blocks
  * like paragraphs, list items, images, headings, etc. All these elements are marked as blocks. A block
  * should not allow another block inside. Note: There is also the `$block` generic item which has `isBlock` set to `true`.
  * Most block type items will inherit from `$block` (through `inheritAllFrom`).
- * @property {Boolean} isInline Whether an item is "text-like" and should be treated as an inline node. Examples of inline elements:
+ * @property {Boolean} isInline
+ * Whether an item is "text-like" and should be treated as an inline node. Examples of inline elements:
  * `$text`, `softBreak` (`<br>`), etc.
- * @property {Boolean} isLimit It can be understood as whether this element should not be split by <kbd>Enter</kbd>.
+ * @property {Boolean} isLimit
+ * It can be understood as whether this element should not be split by <kbd>Enter</kbd>.
  * Examples of limit elements: `$root`, table cell, image caption, etc. In other words, all actions that happen inside
- * a limit element are limited to its content. **Note:** All objects (`isObject`) are treated as limit elements, too.
- * @property {Boolean} isObject Whether an item is "self-contained" and should be treated as a whole. Examples of object elements:
- * `image`, `table`, `video`, etc. **Note:** An object is also a limit, so
+ * a limit element are limited to its content.
+ *
+ * **Note:** All objects (`isObject`) are treated as limit elements, too.
+ *
+ * See the {@glink framework/guides/deep-dive/schema#declaring-as-a-limit-element Dedicated section in "Schema" deep dive} guide.
+ * @property {Boolean} isObject
+ * Whether an item is "self-contained" and should be treated as a whole. Examples of object elements:
+ * `image`, `table`, `video`, etc.
+ *
+ * **Note:** An object is also a limit, so
  * {@link module:engine/model/schema~Schema#isLimit `isLimit()`} returns `true` for object elements automatically.
+ *
+ * See the {@glink framework/guides/deep-dive/schema#declaring-as-a-self-sufficient-object Dedicated section in "Schema" deep dive} guide.
  */
 
 /**