Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document server functions in block style variations section #16997

Merged
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
cbb3f52
Expand the block style variations documentation to document server fu…
jorgefilipecosta Aug 10, 2019
eafaa34
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
8f8668b
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
8faf658
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
c852856
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
bfddbbb
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
86eeb23
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
54fbf84
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
0770815
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
7618892
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
dd95d92
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
f110639
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
d481db7
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
6c170b0
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
0c8fd9e
Update docs/designers-developers/developers/filters/block-filters.md
jorgefilipecosta Aug 12, 2019
c371a74
Fix line break and code block closing
jorgefilipecosta Aug 12, 2019
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions docs/designers-developers/developers/filters/block-filters.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,71 @@ wp.domReady( function() {
} );
```

### Server-side registration helper

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 and unregistering block styles, two server-side functions are also available: `register_block_style`, and `unregister_block_style`.

#### register_block_style

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`:
jorgefilipecosta marked this conversation as resolved.
Show resolved Hide resolved
- `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 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.
jorgefilipecosta marked this conversation as resolved.
Show resolved Hide resolved
- `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 provides 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 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' );

// ...

register_block_style(
'core/quote',
array(
'name' => 'fancy-quote',
'label' => 'Fancy Quote',
'style_handle' => 'myguten-style',
)
);
```
jorgefilipecosta marked this conversation as resolved.
Show resolved Hide resolved

#### unregister_block_style

`unregister_block_style` allows unregistering a block style previously registered on the server using `register_block_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:
jorgefilipecosta marked this conversation as resolved.
Show resolved Hide resolved

```php
unregister_block_style( 'core/quote', 'fancy-quote' );
```

**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

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.
Expand Down