From cbb3f52567dd706198d20b733ccbecd444c013a8 Mon Sep 17 00:00:00 2001 From: Jorge Date: Sat, 10 Aug 2019 18:37:11 +0100 Subject: [PATCH 01/16] Expand the block style variations documentation to document server functions --- .../developers/filters/block-filters.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index d5ddd71b3bdad..61546af9270f0 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -53,6 +53,64 @@ wp.domReady( function() { } ); ``` +### Server-side registration helper + +While the samples provided full allow full control of the style registration client-side scripts, and its enqueuing, they require a considerable amount of code to register a block style. + +To simplify the process of registering/unregistering block styles, two server-side functions were implemented: `register_block_style`, and `unregister_block_style`. + +#### register_block_style + +The `register_block_style` function receives the identifier of the block as the first argument and an array describing properties of the style as the second argument. +The properties of the style array must include `name` and `label`: + - `name`: The identifier of the style used to compute a CSS class. + - `label`: A human-readable label for the style. + +Besides the two mandatory properties, the styles properties array should include a `inline_style` or a `style_handle` property: + - `inline_style`: Contains inline CSS code that registers the CSS class required for the style. + - `style_handle`: Contains the handle to an already registered style that should be enqueued in places where block styles are needed. + +The following code sample registers a style for the quote block named "Blue Quote", and enqueues an inline style that makes quote blocks with the "Blue Quote" style have blue color: + +```php +register_block_style( + 'core/quote', + array( + 'name' => 'blue-quote', + 'label' => __( 'Blue Quote' ), + 'inline_style' => '.wp-block-quote.is-style-blue-quote { color: blue; }', + ) +); +``` + +Alternatively, if the styles were already registered it is possible to just pass its handle and `register_block_style` function will make sure they are enqued. The following code sample provides an example of this use case: + +```php +(...) +wp_register_style( 'myguten-style', get_template_directory_uri() . '/custom-style.css' ); +(...) + +register_block_style( + 'core/quote', + array( + 'name' => 'fancy-quote', + 'label' => 'Fancy Quote', + 'style_handle' => 'myguten-style', + ) +); +``` +#### unregister_block_style + +`unregister_block_style` allows unregistering a block style previously registered on the server using `register_block_style`. +The function registers as the first argument the identifier/name of the block and as second argument the identifier/name of the style. + +The following code sample unregisteres the style named 'fancy-quote' from the quote block: +```php +unregister_block_style( 'core/quote', 'fancy-quote' ); +``` + +**Important:** The function `unregister_block_style`only unregisters styles that were registered on the server using a `register_block_style`. The function does not generate client-side code to unregister a style registered using client-side code. + ### Filters Extending blocks can involve more than just providing alternative styles, in this case, you can use one of the following filters to extend the block settings. From eafaa34d4387e6a407c00fbcdfe97d20829b3a3e Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:35:16 +0100 Subject: [PATCH 02/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index 61546af9270f0..a5ae9f543a54c 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -55,7 +55,7 @@ wp.domReady( function() { ### Server-side registration helper -While the samples provided full allow full control of the style registration client-side scripts, and its enqueuing, they require a considerable amount of code to register a block style. +While the samples provided do allow full control of block styles, they do require a considerable amount of code. To simplify the process of registering/unregistering block styles, two server-side functions were implemented: `register_block_style`, and `unregister_block_style`. From 8f8668bf5cb7b2ebcbbac95fb2d9edb41579b1f2 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:35:25 +0100 Subject: [PATCH 03/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index a5ae9f543a54c..8a72a54fee848 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -57,7 +57,7 @@ wp.domReady( function() { While the samples provided do allow full control of block styles, they do require a considerable amount of code. -To simplify the process of registering/unregistering block styles, two server-side functions were implemented: `register_block_style`, and `unregister_block_style`. +To simplify the process of registering and unregistering block styles, two server-side functions are also available: `register_block_style`, and `unregister_block_style`. #### register_block_style From 8faf6580c5d03e25e0a856b8c75c50d3890485aa Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:35:36 +0100 Subject: [PATCH 04/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index 8a72a54fee848..dabe239f4d985 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -62,6 +62,7 @@ To simplify the process of registering and unregistering block styles, two serve #### register_block_style The `register_block_style` function receives the identifier of the block as the first argument and an array describing properties of the style as the second argument. + The properties of the style array must include `name` and `label`: - `name`: The identifier of the style used to compute a CSS class. - `label`: A human-readable label for the style. From c852856e014a91e16ac8ff8f029af73880a0cb06 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:35:44 +0100 Subject: [PATCH 05/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index dabe239f4d985..1fab354633f8c 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -68,6 +68,7 @@ The properties of the style array must include `name` and `label`: - `label`: A human-readable label for the style. Besides the two mandatory properties, the styles properties array should include a `inline_style` or a `style_handle` property: + - `inline_style`: Contains inline CSS code that registers the CSS class required for the style. - `style_handle`: Contains the handle to an already registered style that should be enqueued in places where block styles are needed. From bfddbbb494a25f3fc2efb156974d51873b9dd53a Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:35:52 +0100 Subject: [PATCH 06/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index 1fab354633f8c..d7bca7334f321 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -67,7 +67,7 @@ The properties of the style array must include `name` and `label`: - `name`: The identifier of the style used to compute a CSS class. - `label`: A human-readable label for the style. -Besides the two mandatory properties, the styles properties array should include a `inline_style` or a `style_handle` property: +Besides the two mandatory properties, the styles properties array should also include an `inline_style` or a `style_handle` property: - `inline_style`: Contains inline CSS code that registers the CSS class required for the style. - `style_handle`: Contains the handle to an already registered style that should be enqueued in places where block styles are needed. From 86eeb23af9b25cfb6acd46968e5b49169c05fa49 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:35:59 +0100 Subject: [PATCH 07/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index d7bca7334f321..607a4232319ad 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -72,7 +72,7 @@ Besides the two mandatory properties, the styles properties array should also in - `inline_style`: Contains inline CSS code that registers the CSS class required for the style. - `style_handle`: Contains the handle to an already registered style that should be enqueued in places where block styles are needed. -The following code sample registers a style for the quote block named "Blue Quote", and enqueues an inline style that makes quote blocks with the "Blue Quote" style have blue color: +The following code sample registers a style for the quote block named "Blue Quote", and provides an inline style that makes quote blocks with the "Blue Quote" style have blue color: ```php register_block_style( From 54fbf84a2049b9255c14cb8f93a2d8554d65387a Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:36:07 +0100 Subject: [PATCH 08/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index 607a4232319ad..f62ecbc126b61 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -111,7 +111,7 @@ The following code sample unregisteres the style named 'fancy-quote' from the q unregister_block_style( 'core/quote', 'fancy-quote' ); ``` -**Important:** The function `unregister_block_style`only unregisters styles that were registered on the server using a `register_block_style`. The function does not generate client-side code to unregister a style registered using client-side code. +**Important:** The function `unregister_block_style` only unregisters styles that were registered on the server using `register_block_style`. The function does not unregister a style registered using client-side code. ### Filters From 0770815eb95d30877d12a57f539761a7b7d3a115 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:36:14 +0100 Subject: [PATCH 09/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index f62ecbc126b61..f0966fdea3bde 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -107,6 +107,7 @@ register_block_style( The function registers as the first argument the identifier/name of the block and as second argument the identifier/name of the style. The following code sample unregisteres the style named 'fancy-quote' from the quote block: + ```php unregister_block_style( 'core/quote', 'fancy-quote' ); ``` From 7618892c7c7b5c8703f01ac8a3099f94b3ed81d9 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:36:20 +0100 Subject: [PATCH 10/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index f0966fdea3bde..ab42b6e13a3da 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -104,7 +104,8 @@ register_block_style( #### unregister_block_style `unregister_block_style` allows unregistering a block style previously registered on the server using `register_block_style`. -The function registers as the first argument the identifier/name of the block and as second argument the identifier/name of the style. + +The function's first argument is the registered name of the block, and the name of the style as the second argument. The following code sample unregisteres the style named 'fancy-quote' from the quote block: From dd95d925cba565711e97b2410836d86e56e285aa Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:36:28 +0100 Subject: [PATCH 11/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index ab42b6e13a3da..c366568dcaa2f 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -61,7 +61,7 @@ To simplify the process of registering and unregistering block styles, two serve #### register_block_style -The `register_block_style` function receives the identifier of the block as the first argument and an array describing properties of the style as the second argument. +The `register_block_style` function receives the name of the block as the first argument and an array describing properties of the style as the second argument. The properties of the style array must include `name` and `label`: - `name`: The identifier of the style used to compute a CSS class. From f1106394175a15d7ed3d7bfb228f52b5100ca4dd Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:41:23 +0100 Subject: [PATCH 12/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index c366568dcaa2f..8d4c3a6b8ef5e 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -100,7 +100,6 @@ register_block_style( 'style_handle' => 'myguten-style', ) ); -``` #### unregister_block_style `unregister_block_style` allows unregistering a block style previously registered on the server using `register_block_style`. From d481db7912a7ce4d5c26405dcc229844a40454a3 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:41:32 +0100 Subject: [PATCH 13/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index 8d4c3a6b8ef5e..1b1211f9b64b8 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -88,7 +88,6 @@ register_block_style( Alternatively, if the styles were already registered it is possible to just pass its handle and `register_block_style` function will make sure they are enqued. The following code sample provides an example of this use case: ```php -(...) wp_register_style( 'myguten-style', get_template_directory_uri() . '/custom-style.css' ); (...) From 6c170b0f2002af4896193c52e1e96b4eeb6b51fa Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:41:42 +0100 Subject: [PATCH 14/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index 1b1211f9b64b8..a93e0fea8fe6e 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -89,7 +89,8 @@ Alternatively, if the styles were already registered it is possible to just pass ```php wp_register_style( 'myguten-style', get_template_directory_uri() . '/custom-style.css' ); -(...) + +// ... register_block_style( 'core/quote', From 0c8fd9e79b0bd58802ede06a50a4b74f5d35df54 Mon Sep 17 00:00:00 2001 From: Jorge Costa Date: Mon, 12 Aug 2019 09:41:49 +0100 Subject: [PATCH 15/16] Update docs/designers-developers/developers/filters/block-filters.md Co-Authored-By: Chris Van Patten --- docs/designers-developers/developers/filters/block-filters.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index a93e0fea8fe6e..4a8d2c5253d0c 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -85,7 +85,9 @@ register_block_style( ); ``` -Alternatively, if the styles were already registered it is possible to just pass its handle and `register_block_style` function will make sure they are enqued. The following code sample provides an example of this use case: +Alternatively, if a stylesheet was already registered which contains the CSS for the style variation, it is possible to just pass the stylesheet's handle so `register_block_style` function will make sure it is enqueue. + +The following code sample provides an example of this use case: ```php wp_register_style( 'myguten-style', get_template_directory_uri() . '/custom-style.css' ); From c371a7455b9bc0182741d6f7240b78f53e418a22 Mon Sep 17 00:00:00 2001 From: Jorge Date: Mon, 12 Aug 2019 10:27:37 +0100 Subject: [PATCH 16/16] Fix line break and code block closing --- docs/designers-developers/developers/filters/block-filters.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/designers-developers/developers/filters/block-filters.md b/docs/designers-developers/developers/filters/block-filters.md index 4a8d2c5253d0c..b0be75557076a 100644 --- a/docs/designers-developers/developers/filters/block-filters.md +++ b/docs/designers-developers/developers/filters/block-filters.md @@ -102,6 +102,8 @@ register_block_style( 'style_handle' => 'myguten-style', ) ); +``` + #### unregister_block_style `unregister_block_style` allows unregistering a block style previously registered on the server using `register_block_style`.