From 07c20c898fe6c58d81188ef199455afad35aa96e Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Mon, 29 May 2023 14:17:32 +0100 Subject: [PATCH 1/3] Add documentation about the entites abstraction and the undo/redo stack --- docs/explanations/architecture/README.md | 1 + docs/explanations/architecture/entities.md | 63 ++++++++++++++++++++++ docs/manifest.json | 6 +++ docs/toc.json | 1 + 4 files changed, 71 insertions(+) create mode 100644 docs/explanations/architecture/entities.md diff --git a/docs/explanations/architecture/README.md b/docs/explanations/architecture/README.md index 774df183618d4..2cecdfd70e2d6 100644 --- a/docs/explanations/architecture/README.md +++ b/docs/explanations/architecture/README.md @@ -6,6 +6,7 @@ Let’s look at the big picture and the architectural and UX principles of the b - [Key concepts](/docs/explanations/architecture/key-concepts.md). - [Data format and data flow](/docs/explanations/architecture/data-flow.md). +- [Entities and undo/redo](/docs/explanations/architecture/entities.md). - [Site editing templates](/docs/explanations/architecture/full-site-editing-templates.md). - [Styles in the editor](/docs/explanations/architecture/styles.md). - [Performance](/docs/explanations/architecture/performance.md). diff --git a/docs/explanations/architecture/entities.md b/docs/explanations/architecture/entities.md new file mode 100644 index 0000000000000..aece09dd87c80 --- /dev/null +++ b/docs/explanations/architecture/entities.md @@ -0,0 +1,63 @@ +# Entities and Undo/Redo. + +The WordPress editors, whether it's the post or site editor manipulate what we call entity records. These are objects that represent a post, a page, a user, a term, a template etc. They are the data that is stored in the database and that is manipulated by the editor. Each editor can fetch, edit and save multiple entity records at the same time. + +For instance, when opening a page in the site editor: + - you can edit properties of the page itself (title, content...) + - you can edit properties of the template of the page (content of the template, design...) + - you can edit properties of template parts (header, footer) used with the template. + +The editor keeps track of all these modifications and orchestrated the saving of all these modified records. This happens within the `@wordpress/core-data` package. + + +## Editing entities + +To be able to edit an entity, you need to first fetch it and load it into the `core-data` store. For example, the following code loads the post with ID 1 into the store. (The entity is the post, the post 1 is the entity record). + +````js +wp.data.dispatch( 'core' ).getEntityRecord( 'postType', 'post', 1 ); +```` + +Once the entity is loaded, you can edit it. For example, the following code sets the title of the post to "Hello World". For each fetched entity record, the `core-data` store keeps track of: + - the "persisted" record: The last state of the record as it was fetched from the backend. + - A list of "edits": Unsaved local modifications for one or several properties of the record. + +The package also exposes a set of actions to manipuate the fetched entity records. + +To entity a fetched entity record, you can call `editEntityRecord` and take the entity type, the entity ID and the new entity record as parameters. The following example sets the title of the post with ID 1 to "Hello World". + +````js +wp.data.dispatch( 'core' ).editEntityRecord( 'postType', 'post', 1, { title: 'Hello World' } ); +```` + +Once you have edited an entity record, you can save it. The following code saves the post with ID 1. + +````js +wp.data.dispatch( 'core' ).saveEditedEntityRecord( 'postType', 'post', 1 ); +```` + +## Undo/Redo + +Since the WordPress editors allow multiple entity records to be edited at the same time, the `core-data` package keeps track of all the entity records that have been fetched and edited in a common undo/redo stack. Each step in the undo/redo stack contains a list of "edits" that should be undone or redone at the same time when calling the `undo` or `redo` action. + +And to be able to perform both undo and redo operations propertly, each modification in the list of edits contains the following information: + + - Entity kind and name: Each entity in core-data is identified by a tuple kind, name. This corresponds to the identifier of the modified entity. + - Entity Record ID: The ID of the modified record. + - Property: The name of the modified property. + - From: The previous value of the property (needed to apply the undo operation). + - To: The new value of the property (needed to apply the redo operation). + +For example, when a user edits the title of a post, followed by a modification to the post slug, and then a modification of the title of a reusable block used with the post for instance. the following information is stored in the undo/redo stack: + + - `[ { kind: 'postType', name: 'post', id: 1, property: 'title', from: '', to: 'Hello World' } ]` + - `[ { kind: 'postType', name: 'post', id: 1, property: 'slug', from: 'Previous slug', to: 'This is the slug of the hello world post' } ]` + - `[ { kind: 'postType', name: 'wp_block', id: 2, property: 'title', from: 'Reusable Block', to: 'Awesome Reusable Block' } ]` + +The store also keep tracks of a "pointer" to the current "undo/redo" step. By default, the pointer always points to the last item in the stack. This pointer is updated when the user performs an undo or redo operation. + +### Transient changes + +The undo/redo core behavior also support what we call "transient modifications". These are modifications that are not stored in the undo/redo stack right way. For instance, when a user starts typing in a text field, the value of the field is modified in the store, but this modification is not stored in the undo/redo stack until after the user moves to the next word or after a few milliseconds. This is done to avoid creating a new undo/redo step for each character typed by the user. + +So by default, `core-data` store considers all modifications to properties that are marked as "transient" (like the `blocks` property in the post entity) as transient modifications. It keeps these modifications outside the undo/redo stack in what is called a "cache" of modifications and these modifications are only stored in the undo/redo stack when we explicitely call `__unstableCreateUndoLevel` or when the next non transient modification is performed. diff --git a/docs/manifest.json b/docs/manifest.json index d6759f051a679..f10b4dbe06a17 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -2039,6 +2039,12 @@ "markdown_source": "../docs/explanations/architecture/data-flow.md", "parent": "architecture" }, + { + "title": "Entities and Undo/Redo.", + "slug": "entities", + "markdown_source": "../docs/explanations/architecture/entities.md", + "parent": "architecture" + }, { "title": "Modularity", "slug": "modularity", diff --git a/docs/toc.json b/docs/toc.json index 7b48e68cbab56..d9acd5fbb38ae 100644 --- a/docs/toc.json +++ b/docs/toc.json @@ -302,6 +302,7 @@ "docs/explanations/architecture/README.md": [ { "docs/explanations/architecture/key-concepts.md": [] }, { "docs/explanations/architecture/data-flow.md": [] }, + { "docs/explanations/architecture/entities.md": [] }, { "docs/explanations/architecture/modularity.md": [] }, { "docs/explanations/architecture/performance.md": [] }, { From d5b76d858ab0005f6375a55d0ed5371be61042dd Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Mon, 29 May 2023 14:59:32 +0100 Subject: [PATCH 2/3] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: André <583546+oandregal@users.noreply.github.com> --- docs/explanations/architecture/entities.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/explanations/architecture/entities.md b/docs/explanations/architecture/entities.md index aece09dd87c80..0e3f8000f5b79 100644 --- a/docs/explanations/architecture/entities.md +++ b/docs/explanations/architecture/entities.md @@ -1,13 +1,13 @@ # Entities and Undo/Redo. -The WordPress editors, whether it's the post or site editor manipulate what we call entity records. These are objects that represent a post, a page, a user, a term, a template etc. They are the data that is stored in the database and that is manipulated by the editor. Each editor can fetch, edit and save multiple entity records at the same time. +The WordPress editors, whether it's the post or site editor, manipulate what we call entity records. These are objects that represent a post, a page, a user, a term, a template, etc. They are the data that is stored in the database and that is manipulated by the editor. Each editor can fetch, edit and save multiple entity records at the same time. For instance, when opening a page in the site editor: - you can edit properties of the page itself (title, content...) - you can edit properties of the template of the page (content of the template, design...) - you can edit properties of template parts (header, footer) used with the template. -The editor keeps track of all these modifications and orchestrated the saving of all these modified records. This happens within the `@wordpress/core-data` package. +The editor keeps track of all these modifications and orchestrates the saving of all these modified records. This happens within the `@wordpress/core-data` package. ## Editing entities @@ -22,9 +22,9 @@ Once the entity is loaded, you can edit it. For example, the following code sets - the "persisted" record: The last state of the record as it was fetched from the backend. - A list of "edits": Unsaved local modifications for one or several properties of the record. -The package also exposes a set of actions to manipuate the fetched entity records. +The package also exposes a set of actions to manipulate the fetched entity records. -To entity a fetched entity record, you can call `editEntityRecord` and take the entity type, the entity ID and the new entity record as parameters. The following example sets the title of the post with ID 1 to "Hello World". +To fetch an entity record, you can call `editEntityRecord`, which takes the entity type, the entity ID and the new entity record as parameters. The following example sets the title of the post with ID 1 to "Hello World". ````js wp.data.dispatch( 'core' ).editEntityRecord( 'postType', 'post', 1, { title: 'Hello World' } ); From 631a5e6c1ddcb95bbf3076b1a6f3f0567cacde16 Mon Sep 17 00:00:00 2001 From: Riad Benguella Date: Mon, 29 May 2023 15:05:26 +0100 Subject: [PATCH 3/3] Apply more suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: André <583546+oandregal@users.noreply.github.com> --- docs/explanations/architecture/entities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/explanations/architecture/entities.md b/docs/explanations/architecture/entities.md index 0e3f8000f5b79..368d0a73f87b6 100644 --- a/docs/explanations/architecture/entities.md +++ b/docs/explanations/architecture/entities.md @@ -48,7 +48,7 @@ And to be able to perform both undo and redo operations propertly, each modifica - From: The previous value of the property (needed to apply the undo operation). - To: The new value of the property (needed to apply the redo operation). -For example, when a user edits the title of a post, followed by a modification to the post slug, and then a modification of the title of a reusable block used with the post for instance. the following information is stored in the undo/redo stack: +For example, let's say a user edits the title of a post, followed by a modification to the post slug, and then a modification of the title of a reusable block used with the post for instance. The following information is stored in the undo/redo stack: - `[ { kind: 'postType', name: 'post', id: 1, property: 'title', from: '', to: 'Hello World' } ]` - `[ { kind: 'postType', name: 'post', id: 1, property: 'slug', from: 'Previous slug', to: 'This is the slug of the hello world post' } ]` @@ -58,6 +58,6 @@ The store also keep tracks of a "pointer" to the current "undo/redo" step. By de ### Transient changes -The undo/redo core behavior also support what we call "transient modifications". These are modifications that are not stored in the undo/redo stack right way. For instance, when a user starts typing in a text field, the value of the field is modified in the store, but this modification is not stored in the undo/redo stack until after the user moves to the next word or after a few milliseconds. This is done to avoid creating a new undo/redo step for each character typed by the user. +The undo/redo core behavior also supports what we call "transient modifications". These are modifications that are not stored in the undo/redo stack right away. For instance, when a user starts typing in a text field, the value of the field is modified in the store, but this modification is not stored in the undo/redo stack until after the user moves to the next word or after a few milliseconds. This is done to avoid creating a new undo/redo step for each character typed by the user. So by default, `core-data` store considers all modifications to properties that are marked as "transient" (like the `blocks` property in the post entity) as transient modifications. It keeps these modifications outside the undo/redo stack in what is called a "cache" of modifications and these modifications are only stored in the undo/redo stack when we explicitely call `__unstableCreateUndoLevel` or when the next non transient modification is performed.