|
|
@@ -210,6 +210,9 @@ export default class Schema {
|
|
|
* const paragraphElement = writer.createElement( 'paragraph' );
|
|
|
* schema.isBlock( paragraphElement ); // -> true
|
|
|
*
|
|
|
+ * See the {@glink framework/guides/deep-dive/schema#block-elements Block elements} section of the "Schema" deep dive}
|
|
|
+ * guide for more details.
|
|
|
+ *
|
|
|
* @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
|
|
|
*/
|
|
|
isBlock( item ) {
|
|
|
@@ -219,8 +222,8 @@ export default class Schema {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * Returns `true` if the given item is should be treated as a limit element.
|
|
|
- * If it should act as a boundary between actions inside and outside.
|
|
|
+ * Returns `true` if the given item should be treated as a limit element.
|
|
|
+ *
|
|
|
* It considers the item to be a limit element if its
|
|
|
* {@link module:engine/model/schema~SchemaItemDefinition}'s
|
|
|
* {@link module:engine/model/schema~SchemaItemDefinition#isLimit `isLimit`} or
|
|
|
@@ -232,14 +235,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.
|
|
|
- *
|
|
|
- * It considers `isObject` with higher priority than `isLimit`. Meaning, even if
|
|
|
- * `isLimit` was explicitly set to `false` in `SchemaItemDefinition`, but `isObject` was set to `true`,
|
|
|
- * `isLimit()` will return `true`.
|
|
|
- *
|
|
|
- * **Note**: In the above scenario {@link module:engine/model/schema~Schema#getDefinition `schema.getDefinition( item ).isLimit`}
|
|
|
- * will be `false`, to match the exact definition given.
|
|
|
+ * See the {@glink framework/guides/deep-dive/schema#limit-elements Limit elements} section of the "Schema" deep dive}
|
|
|
+ * guide for more details.
|
|
|
*
|
|
|
* @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
|
|
|
*/
|
|
|
@@ -255,7 +252,7 @@ export default class Schema {
|
|
|
|
|
|
/**
|
|
|
* Returns `true` if the given item is should be treated as an object element.
|
|
|
- * If it should act as a self-sufficient element.
|
|
|
+ *
|
|
|
* It considers the item to be an object element if its
|
|
|
* {@link module:engine/model/schema~SchemaItemDefinition}'s
|
|
|
* {@link module:engine/model/schema~SchemaItemDefinition#isObject `isObject`} property
|
|
|
@@ -267,7 +264,8 @@ export default class Schema {
|
|
|
* const imageElement = writer.createElement( 'image' );
|
|
|
* schema.isObject( imageElement ); // -> true
|
|
|
*
|
|
|
- * See the {@glink framework/guides/deep-dive/schema "Schema" deep dive} guide.
|
|
|
+ * See the {@glink framework/guides/deep-dive/schema#object-elements Object elements} section of the "Schema" deep dive}
|
|
|
+ * guide for more details.
|
|
|
*
|
|
|
* @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
|
|
|
*/
|
|
|
@@ -287,6 +285,9 @@ export default class Schema {
|
|
|
* const text = writer.createText('foo' );
|
|
|
* schema.isInline( text ); // -> true
|
|
|
*
|
|
|
+ * See the {@glink framework/guides/deep-dive/schema#inline-elements Inline elements} section of the "Schema" deep dive}
|
|
|
+ * guide for more details.
|
|
|
+ *
|
|
|
* @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
|
|
|
*/
|
|
|
isInline( item ) {
|
|
|
@@ -1018,34 +1019,35 @@ mix( Schema, ObservableMixin );
|
|
|
*
|
|
|
* You can define the following rules:
|
|
|
*
|
|
|
- * * {@link #allowIn `allowIn`} – Defines in which other items this item will be allowed.
|
|
|
- * * {@link #allowAttributes `allowAttributes`} – Defines allowed attributes of the given item.
|
|
|
- * * {@link #allowContentOf `allowContentOf`} – Inherits "allowed children" from other items.
|
|
|
- * * {@link #allowWhere `allowWhere`} – Inherits "allowed in" from other items.
|
|
|
- * * {@link #allowAttributesOf `allowAttributesOf`} – Inherits attributes from other items.
|
|
|
- * * {@link #inheritTypesFrom `inheritTypesFrom`} – Inherits `is*` properties of other items.
|
|
|
- * * {@link #inheritAllFrom `inheritAllFrom`} – A shorthand for `allowContentOf`, `allowWhere`,
|
|
|
- * `allowAttributesOf`, `inheritTypesFrom`.
|
|
|
- * * Additionally, you can define the following `is*` properties: `isBlock`, `isLimit`, `isObject`, `isInline`. Read about them below.
|
|
|
+ * * {@link ~SchemaItemDefinition#allowIn `allowIn`} – Defines in which other items this item will be allowed.
|
|
|
+ * * {@link ~SchemaItemDefinition#allowAttributes `allowAttributes`} – Defines allowed attributes of the given item.
|
|
|
+ * * {@link ~SchemaItemDefinition#allowContentOf `allowContentOf`} – Inherits "allowed children" from other items.
|
|
|
+ * * {@link ~SchemaItemDefinition#allowWhere `allowWhere`} – Inherits "allowed in" from other items.
|
|
|
+ * * {@link ~SchemaItemDefinition#allowAttributesOf `allowAttributesOf`} – Inherits attributes from other items.
|
|
|
+ * * {@link ~SchemaItemDefinition#inheritTypesFrom `inheritTypesFrom`} – Inherits `is*` properties of other items.
|
|
|
+ * * {@link ~SchemaItemDefinition#inheritAllFrom `inheritAllFrom`} –
|
|
|
+ * A shorthand for `allowContentOf`, `allowWhere`, `allowAttributesOf`, `inheritTypesFrom`.
|
|
|
*
|
|
|
- * # The is* properties
|
|
|
+ * # The `is*` properties
|
|
|
*
|
|
|
- * There are 4 commonly used `is*` properties. Their role is to assign additional semantics to schema items.
|
|
|
+ * There are a couple commonly used `is*` properties. Their role is to assign additional semantics to schema items.
|
|
|
* You can define more properties but you will also need to implement support for them in the existing editor features.
|
|
|
*
|
|
|
- * * {@link #isBlock `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`).
|
|
|
- * * {@link #isInline `isInline`} – Whether an item is "text-like" and should be treated as an inline node.
|
|
|
+ * * {@link ~SchemaItemDefinition#isBlock `isBlock`} – Whether this item is paragraph-like.
|
|
|
+ * Generally speaking, content is usually made out of blocks like paragraphs, list items, images, headings, etc.
|
|
|
+ * * {@link ~SchemaItemDefinition#isInline `isInline`} – Whether an item is "text-like" and should be treated as an inline node.
|
|
|
* Examples of inline elements: `$text`, `softBreak` (`<br>`), etc.
|
|
|
- * * {@link #isLimit `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.
|
|
|
- * * {@link #isObject `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 ~SchemaItemDefinition#isLimit `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.
|
|
|
+ * All objects are treated as limit elements, too.
|
|
|
+ * * {@link ~SchemaItemDefinition#isObject `isObject`} – Whether an item is "self-contained" and should be treated as a whole.
|
|
|
+ * Examples of object elements: `image`, `table`, `video`, etc. An object is also a limit, so
|
|
|
* {@link module:engine/model/schema~Schema#isLimit `isLimit()`} returns `true` for object elements automatically.
|
|
|
*
|
|
|
+ * Read more about the meaning of these types in the
|
|
|
+ * {@glink framework/guides/deep-dive/schema#defining-additional-semantics Dedicated section of the "Schema" deep dive} guide.
|
|
|
+ *
|
|
|
* # Generic items
|
|
|
*
|
|
|
* There are three basic generic items: `$root`, `$block` and `$text`.
|
|
|
@@ -1067,7 +1069,7 @@ mix( Schema, ObservableMixin );
|
|
|
* (paragraphs, lists items, headings, images) which, in turn, may contain text inside.
|
|
|
*
|
|
|
* By inheriting from the generic items you can define new items which will get extended by other editor features.
|
|
|
- * Read more about generic types in the {@glink framework/guides/deep-dive/schema Defining schema} guide.
|
|
|
+ * Read more about generic types in the {@glink framework/guides/deep-dive/schema Schema deep dive} guide.
|
|
|
*
|
|
|
* # Example definitions
|
|
|
*
|
|
|
@@ -1127,7 +1129,7 @@ mix( Schema, ObservableMixin );
|
|
|
* * If you want to publish your feature so other developers can use it, try to use
|
|
|
* generic items as much as possible.
|
|
|
* * Keep your model clean. Limit it to the actual data and store information in a normalized way.
|
|
|
- * * Remember about definining the `is*` properties. They do not affect the allowed structures, but they can
|
|
|
+ * * Remember about defining the `is*` properties. They do not affect the allowed structures, but they can
|
|
|
* affect how the editor features treat your elements.
|
|
|
*
|
|
|
* @typedef {Object} module:engine/model/schema~SchemaItemDefinition
|
|
|
@@ -1145,17 +1147,25 @@ mix( Schema, ObservableMixin );
|
|
|
* 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`).
|
|
|
+ *
|
|
|
+ * Read more about the block elements in the
|
|
|
+ * {@glink framework/guides/deep-dive/schema#block-elements Block elements} section of the "Schema" deep dive} guide.
|
|
|
+ *
|
|
|
* @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.
|
|
|
+ *
|
|
|
+ * Read more about the inline elements in the
|
|
|
+ * {@glink framework/guides/deep-dive/schema#inline-elements Inline elements} section of the "Schema" deep dive} guide.
|
|
|
+ *
|
|
|
* @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.
|
|
|
+ * Read more about the limit elements in the
|
|
|
+ * {@glink framework/guides/deep-dive/schema#limit-elements Limit elements} section of the "Schema" deep dive} guide.
|
|
|
*
|
|
|
- * 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.
|
|
|
@@ -1163,7 +1173,8 @@ mix( Schema, ObservableMixin );
|
|
|
* **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.
|
|
|
+ * Read more about the object elements in the
|
|
|
+ * {@glink framework/guides/deep-dive/schema#object-elements Object elements} section of the "Schema" deep dive} guide.
|
|
|
*/
|
|
|
|
|
|
/**
|