From 9059dacb8646c567dd8b6ce8f13f384b2cb3a8b2 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Fri, 30 Nov 2018 11:27:09 -0800 Subject: [PATCH 1/7] Update glossar with missing terms --- docs/designers-developers/glossary.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/designers-developers/glossary.md b/docs/designers-developers/glossary.md index afa574179db276..f8c90a336a19f2 100644 --- a/docs/designers-developers/glossary.md +++ b/docs/designers-developers/glossary.md @@ -7,13 +7,13 @@ - **Block Inserter**: Primary interface for selecting from the available blocks, triggered by plus icon buttons on Blocks or in the top-left of the editor interface. - **Block name**: A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. `core/image` - **Block type**: In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition. -- **Classic block**: +- **Classic block**: A block which embeds the TinyMCE editor as a block, TinyMCE was the base of the previous core editor. Older content created prior to the block editor will be loaded in to a single Classic block. - **Dynamic block**: A type of block where the content of which may change and cannot be determined at the time of saving a post, instead calculated any time the post is shown on the front of a site. These blocks may save fallback content or no content at all in their JavaScript implementation, instead deferring to a PHP block implementation for runtime rendering. - **RichText**: A common component enabling rich content editing including bold, italics, hyperlinks, etc. It is not too much unlike the single editor region of the legacy post editor, and is in fact powered by the same TinyMCE library. - **Inspector**: A block settings region shown in place of the post settings when a block is selected. Fields may be shown here to allow the user to customize the selected block. - **Post settings**: A sidebar region containing metadata fields for the post, including scheduling, visibility, terms, and featured image. -- **Reusable block**: -- **Sidebar**: +- **Reusable block**: A block that is saved and then can be shared as a reusable, repeatable piece of content. +- **Sidebar**: The panel on the right which contains the document and block settings. The sidebar is toggled using the Settings gear icon. - **Serialization**: The process of converting a block's attributes object into HTML markup, typically occurring when saving the post. - **Static block**: A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content. - **TinyMCE**: [TinyMCE](https://www.tinymce.com/) is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor. From bda8bbbb88871d780ec3ae91596af99a0dee748e Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Fri, 30 Nov 2018 11:27:43 -0800 Subject: [PATCH 2/7] Convert glossary to use dl/dt/dd dtags. Fixes #9976 --- docs/designers-developers/glossary.md | 78 ++++++++++++++++++++------- 1 file changed, 59 insertions(+), 19 deletions(-) diff --git a/docs/designers-developers/glossary.md b/docs/designers-developers/glossary.md index f8c90a336a19f2..e377d491b8b9ec 100644 --- a/docs/designers-developers/glossary.md +++ b/docs/designers-developers/glossary.md @@ -1,21 +1,61 @@ # Glossary -- **Attribute sources**: An object describing the attributes shape of a block. The keys can be named as most appropriate to describe the state of a block type. The value for each key is a function which describes the strategy by which the attribute value should be extracted from the content of a saved post's content. When processed, a new object is created, taking the form of the keys defined in the attribute sources, where each value is the result of the attribute source function. -- **Attributes**: The object representation of the current state of a block in post content. When loading a saved post, this is determined by the attribute sources for the block type. These values can change over time during an editing session when the user modifies a block, and are used when determining how to serialize the block. -- **Block**: The abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. -- **Block Categories**: These are not a WordPress taxonomy, but instead used internally to sort blocks in the Block Inserter. -- **Block Inserter**: Primary interface for selecting from the available blocks, triggered by plus icon buttons on Blocks or in the top-left of the editor interface. -- **Block name**: A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. `core/image` -- **Block type**: In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition. -- **Classic block**: A block which embeds the TinyMCE editor as a block, TinyMCE was the base of the previous core editor. Older content created prior to the block editor will be loaded in to a single Classic block. -- **Dynamic block**: A type of block where the content of which may change and cannot be determined at the time of saving a post, instead calculated any time the post is shown on the front of a site. These blocks may save fallback content or no content at all in their JavaScript implementation, instead deferring to a PHP block implementation for runtime rendering. -- **RichText**: A common component enabling rich content editing including bold, italics, hyperlinks, etc. It is not too much unlike the single editor region of the legacy post editor, and is in fact powered by the same TinyMCE library. -- **Inspector**: A block settings region shown in place of the post settings when a block is selected. Fields may be shown here to allow the user to customize the selected block. -- **Post settings**: A sidebar region containing metadata fields for the post, including scheduling, visibility, terms, and featured image. -- **Reusable block**: A block that is saved and then can be shared as a reusable, repeatable piece of content. -- **Sidebar**: The panel on the right which contains the document and block settings. The sidebar is toggled using the Settings gear icon. -- **Serialization**: The process of converting a block's attributes object into HTML markup, typically occurring when saving the post. -- **Static block**: A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content. -- **TinyMCE**: [TinyMCE](https://www.tinymce.com/) is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor. -- **Toolbar**: A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block. -- **Template**: +
+
Attribute sources
+
An object describing the attributes shape of a block. The keys can be named as most appropriate to describe the state of a block type. The value for each key is a function which describes the strategy by which the attribute value should be extracted from the content of a saved post's content. When processed, a new object is created, taking the form of the keys defined in the attribute sources, where each value is the result of the attribute source function.
+ +
Attributes
+
The object representation of the current state of a block in post content. When loading a saved post, this is determined by the attribute sources for the block type. These values can change over time during an editing session when the user modifies a block, and are used when determining how to serialize the block.
+ +
Block
+
The abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.
+ +
Block Categories
+
These are not a WordPress taxonomy, but instead used internally to sort blocks in the Block Inserter.
+ +
Block Inserter
+
Primary interface for selecting from the available blocks, triggered by plus icon buttons on Blocks or in the top-left of the editor interface.
+ +
Block name
+
A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. `core/image`
+ +
Block type
+
In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition.
+ +
Classic block
+
A block which embeds the TinyMCE editor as a block, TinyMCE was the base of the previous core editor. Older content created prior to the block editor will be loaded in to a single Classic block.
+ +
Dynamic block
+
A type of block where the content of which may change and cannot be determined at the time of saving a post, instead calculated any time the post is shown on the front of a site. These blocks may save fallback content or no content at all in their JavaScript implementation, instead deferring to a PHP block implementation for runtime rendering.
+ +
Inspector
+
A block settings region shown in place of the post settings when a block is selected. Fields may be shown here to allow the user to customize the selected block.
+ +
Post settings
+
A sidebar region containing metadata fields for the post, including scheduling, visibility, terms, and featured image.
+ +
RichText
+
A common component enabling rich content editing including bold, italics, hyperlinks, etc. It is not too much unlike the single editor region of the legacy post editor, and is in fact powered by the same TinyMCE library.
+ +
Reusable block
+
A block that is saved and then can be shared as a reusable, repeatable piece of content.
+ +
Sidebar
+
The panel on the right which contains the document and block settings. The sidebar is toggled using the Settings gear icon.
+ +
Serialization
+
The process of converting a block's attributes object into HTML markup, typically occurring when saving the post.
+ +
Static block
+
A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content.
+ +
TinyMCE
+
[TinyMCE](https://www.tinymce.com/) is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor.
+ +
Toolbar
+
A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block.
+ +
Template:
+
+ +
From e9425505fbda268ec015b543c0da62a4e60d2777 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Fri, 30 Nov 2018 11:38:01 -0800 Subject: [PATCH 3/7] Fix TinyMCE link --- docs/designers-developers/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/glossary.md b/docs/designers-developers/glossary.md index e377d491b8b9ec..3927a770704cb4 100644 --- a/docs/designers-developers/glossary.md +++ b/docs/designers-developers/glossary.md @@ -50,7 +50,7 @@
A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content.
TinyMCE
-
[TinyMCE](https://www.tinymce.com/) is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor.
+
TinyMCE is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor.
Toolbar
A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block.
From 603eed0e43dbc4d9c90494f64fb44b3ebab9879b Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Fri, 30 Nov 2018 11:43:17 -0800 Subject: [PATCH 4/7] remove spacing around tags --- docs/designers-developers/glossary.md | 76 +++++++++++++-------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/designers-developers/glossary.md b/docs/designers-developers/glossary.md index 3927a770704cb4..b0f4861f371bc4 100644 --- a/docs/designers-developers/glossary.md +++ b/docs/designers-developers/glossary.md @@ -1,61 +1,61 @@ # Glossary
-
Attribute sources
-
An object describing the attributes shape of a block. The keys can be named as most appropriate to describe the state of a block type. The value for each key is a function which describes the strategy by which the attribute value should be extracted from the content of a saved post's content. When processed, a new object is created, taking the form of the keys defined in the attribute sources, where each value is the result of the attribute source function.
+
Attribute sources
+
An object describing the attributes shape of a block. The keys can be named as most appropriate to describe the state of a block type. The value for each key is a function which describes the strategy by which the attribute value should be extracted from the content of a saved post's content. When processed, a new object is created, taking the form of the keys defined in the attribute sources, where each value is the result of the attribute source function.
-
Attributes
-
The object representation of the current state of a block in post content. When loading a saved post, this is determined by the attribute sources for the block type. These values can change over time during an editing session when the user modifies a block, and are used when determining how to serialize the block.
+
Attributes
+
The object representation of the current state of a block in post content. When loading a saved post, this is determined by the attribute sources for the block type. These values can change over time during an editing session when the user modifies a block, and are used when determining how to serialize the block.
-
Block
-
The abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.
+
Block
+
The abstract term used to describe units of markup that, composed together, form the content or layout of a webpage. The idea combines concepts of what in WordPress today we achieve with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience.
-
Block Categories
-
These are not a WordPress taxonomy, but instead used internally to sort blocks in the Block Inserter.
+
Block Categories
+
These are not a WordPress taxonomy, but instead used internally to sort blocks in the Block Inserter.
-
Block Inserter
-
Primary interface for selecting from the available blocks, triggered by plus icon buttons on Blocks or in the top-left of the editor interface.
+
Block Inserter
+
Primary interface for selecting from the available blocks, triggered by plus icon buttons on Blocks or in the top-left of the editor interface.
-
Block name
-
A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. `core/image`
+
Block name
+
A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. `core/image`
-
Block type
-
In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition.
+
Block type
+
In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition.
-
Classic block
-
A block which embeds the TinyMCE editor as a block, TinyMCE was the base of the previous core editor. Older content created prior to the block editor will be loaded in to a single Classic block.
+
Classic block
+
A block which embeds the TinyMCE editor as a block, TinyMCE was the base of the previous core editor. Older content created prior to the block editor will be loaded in to a single Classic block.
-
Dynamic block
-
A type of block where the content of which may change and cannot be determined at the time of saving a post, instead calculated any time the post is shown on the front of a site. These blocks may save fallback content or no content at all in their JavaScript implementation, instead deferring to a PHP block implementation for runtime rendering.
+
Dynamic block
+
A type of block where the content of which may change and cannot be determined at the time of saving a post, instead calculated any time the post is shown on the front of a site. These blocks may save fallback content or no content at all in their JavaScript implementation, instead deferring to a PHP block implementation for runtime rendering.
-
Inspector
-
A block settings region shown in place of the post settings when a block is selected. Fields may be shown here to allow the user to customize the selected block.
+
Inspector
+
A block settings region shown in place of the post settings when a block is selected. Fields may be shown here to allow the user to customize the selected block.
-
Post settings
-
A sidebar region containing metadata fields for the post, including scheduling, visibility, terms, and featured image.
+
Post settings
+
A sidebar region containing metadata fields for the post, including scheduling, visibility, terms, and featured image.
-
RichText
-
A common component enabling rich content editing including bold, italics, hyperlinks, etc. It is not too much unlike the single editor region of the legacy post editor, and is in fact powered by the same TinyMCE library.
+
RichText
+
A common component enabling rich content editing including bold, italics, hyperlinks, etc. It is not too much unlike the single editor region of the legacy post editor, and is in fact powered by the same TinyMCE library.
-
Reusable block
-
A block that is saved and then can be shared as a reusable, repeatable piece of content.
+
Reusable block
+
A block that is saved and then can be shared as a reusable, repeatable piece of content.
-
Sidebar
-
The panel on the right which contains the document and block settings. The sidebar is toggled using the Settings gear icon.
+
Sidebar
+
The panel on the right which contains the document and block settings. The sidebar is toggled using the Settings gear icon.
-
Serialization
-
The process of converting a block's attributes object into HTML markup, typically occurring when saving the post.
+
Serialization
+
The process of converting a block's attributes object into HTML markup, typically occurring when saving the post.
-
Static block
-
A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content.
+
Static block
+
A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content.
-
TinyMCE
-
TinyMCE is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor.
+
TinyMCE
+
TinyMCE is a web-based JavaScript WYSIWYG (What You See Is What You Get) editor.
-
Toolbar
-
A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block.
+
Toolbar
+
A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block.
-
Template:
-
+
Template:
+
From c478e3fcb8b4a8e9c1108f6a70fe5a4f47058a5f Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Fri, 30 Nov 2018 15:01:25 -0800 Subject: [PATCH 5/7] Add template definition, with link --- docs/designers-developers/glossary.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/designers-developers/glossary.md b/docs/designers-developers/glossary.md index b0f4861f371bc4..df1b9f2a7aa706 100644 --- a/docs/designers-developers/glossary.md +++ b/docs/designers-developers/glossary.md @@ -55,7 +55,7 @@
Toolbar
A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block.
-
Template:
-
+
Template
+
A block template is defined as a list of block items. Such blocks can have predefined attributes, placeholder content, and be static or dynamic. Block templates allow to specify a default initial state for an editor session. See Templates documentation for more.
From 0e7e403c1f40722fd836a7ec67d41ca72f035158 Mon Sep 17 00:00:00 2001 From: Marcus Kazmierczak Date: Thu, 6 Dec 2018 15:48:49 -0800 Subject: [PATCH 6/7] Updates per review --- docs/designers-developers/glossary.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/designers-developers/glossary.md b/docs/designers-developers/glossary.md index df1b9f2a7aa706..06dc6c88bec422 100644 --- a/docs/designers-developers/glossary.md +++ b/docs/designers-developers/glossary.md @@ -17,7 +17,7 @@
Primary interface for selecting from the available blocks, triggered by plus icon buttons on Blocks or in the top-left of the editor interface.
Block name
-
A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. `core/image`
+
A unique identifier for a block type, consisting of a plugin-specific namespace and a short label describing the block's intent. e.g. core/image
Block type
In contrast with the blocks composing a particular post, a block type describes the blueprint by which any block of that type should behave. So while there may be many images within a post, each behaves consistent with a unified image block type definition.
@@ -44,7 +44,7 @@
The panel on the right which contains the document and block settings. The sidebar is toggled using the Settings gear icon.
Serialization
-
The process of converting a block's attributes object into HTML markup, typically occurring when saving the post.
+
The process of converting a block's attributes object into HTML markup, this occurs each time a block is edited.
Static block
A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content.
@@ -56,6 +56,6 @@
A set of button controls. In the context of a block, usually referring to the toolbar of block controls shown above the selected block.
Template
-
A block template is defined as a list of block items. Such blocks can have predefined attributes, placeholder content, and be static or dynamic. Block templates allow to specify a default initial state for an editor session. See Templates documentation for more.
+
A template is a pre-defined arrangement of blocks, possibly with predefined attributes or placeholder content. You can provide a template for a post type, to give users a starting point when creating a new piece of content, or inside a custom block with the InnerBlocks component. See the templates documentation for more information. See templates documentation for more information.
From 5302b847865e5561e28d24ac3fbeab4d522192e9 Mon Sep 17 00:00:00 2001 From: Chris Van Patten Date: Thu, 6 Dec 2018 15:56:12 -0800 Subject: [PATCH 7/7] Update docs/designers-developers/glossary.md Co-Authored-By: mkaz --- docs/designers-developers/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/glossary.md b/docs/designers-developers/glossary.md index 06dc6c88bec422..f51c0d16d5dbab 100644 --- a/docs/designers-developers/glossary.md +++ b/docs/designers-developers/glossary.md @@ -44,7 +44,7 @@
The panel on the right which contains the document and block settings. The sidebar is toggled using the Settings gear icon.
Serialization
-
The process of converting a block's attributes object into HTML markup, this occurs each time a block is edited.
+
The process of converting a block's attributes object into HTML markup, which occurs each time a block is edited.
Static block
A type of block where the content of which is known at the time of saving a post. A static block will be saved with HTML markup directly in post content.