Skip to content

Commit

Permalink
Merge pull request #36 from 10up/add/block-locking-referance
Browse files Browse the repository at this point in the history 
add reference for block locking UI in WordPress 6.0
  • Loading branch information
@fabiankaegy
fabiankaegy authored May 24, 2022
2 parents f868f86 + e82a74c commit 2eb7c07
Show file tree
Hide file tree
Showing 3 changed files with 121 additions and 64 deletions.
117 changes: 117 additions & 0 deletions reference/03-Blocks/block-locking.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
# Block Locking

![Block Locking UI](../../static/img/block-locking-ui.gif)

The Block Locking API was introduces in WordPress 5.9. With it blocks can be locked from being able to get moved and or removed from the editor. In WordPress 6.0 this API got a visual user interface so that editors can lock and unlock blocks themselves.

:::note
Blocks can opt out of showing the block locking UI to the user via the `__experimentalLock` block supports option. There also is a way to override what users are able to use the block locking UI via the `__experimentalCanLockBlocks` editor setting.
:::note

## Locking the ability to remove / move a block

Individual blocks can lock down their ability to be moved and or removed. This is done via an attribute that is added by WordPress to every single block called `lock`. The `lock` attribute is an object that accepts two properties: `move` and `remove`. Both of them are `Boolean` values. There is no UI to control the lock state of a block. It can only be controlled via code.

In a pattern you can set these attributes via the html comment of the block where you can set its attributes.

```php
<!-- wp:columns -->
<div class="wp-block-columns">
// highlight-start
<!-- wp:column { "lock": { "move": false, "remove": false } } -->
// highlight-end
<div class="wp-block-column">
...
</div>
<!-- /wp:column -->

// highlight-start
<!-- wp:column { "lock": { "move": false, "remove": false } } -->
// highlight-end
<div class="wp-block-column">
...
</div>
<!-- /wp:column -->
</div>
<!-- /wp:columns -->
```

## Restricting which inner blocks can be used

The core column, group, and cover block support the ability to restrict which blocks are allowed within the inner blocks area. This is being done via two attributes that exist on the se blocks. The `allowedBlocks` and `templateLock` attributes can be set via the html comment in patterns to restrict which blocks can be inserted within a specific pattern. And with the ability to also define a `templateLock` you can even make it so that editors cannot move or remove any of the children within a column for example.

```php
<!-- wp:columns -->
<div class="wp-block-columns">
// highlight-start
<!-- wp:column { "allowedBlocks": [ "core/image" ], "templateLock": "all" } } -->
// highlight-end
<div class="wp-block-column">
...
</div>
<!-- /wp:column -->

// highlight-start
<!-- wp:column { "allowedBlocks": [ "core/heading", "core/paragraph" ], "templateLock": "all" } } -->
// highlight-end
<div class="wp-block-column">
...
</div>
<!-- /wp:column -->
</div>
<!-- /wp:columns -->
```

:::tip
Since these patterns are php files you can make the `allowedBlocks` list filterable via an `apply_filters` hook.
:::tip

## Disabling the block locking UI

### For a specific block

If you have a block that should not expose the block locking UI to any user you can opt out of it on a block level by setting the `supports.__experimentalLock` option to false.

```json
{
"name": "namespace/block",
"title": "Example",
"supports": {
// highlight-next-line
"__experimentalLock": false
}
}
```

### Override block locking UI setting

There are many circumstances where block locking should actually be used to prevent certain users from changing a locked section. By filtering the `block_editor_settings_all` you can override which users should be able to use the block locking UI altogether.

```php
add_filter(
'block_editor_settings_all',
static function( $settings, $context ) {
// Allow for the Editor role and above.
$settings['__experimentalCanLockBlocks'] = current_user_can( 'delete_others_posts' );

// Only enable for specific user(s).
$user = wp_get_current_user();
if ( in_array( $user->user_email, array( '[email protected]' ), true ) ) {
$settings['__experimentalCanLockBlocks'] = false;
}

// Disable for posts/pages.
if ( $context->post && $context->post->post_type === 'page' ) {
$settings['__experimentalCanLockBlocks'] = false;
}

return $settings;
},
10,
2
);
```

## Links

- [Locking in Custom Post Types](../04-custom-post-types.md)
68 changes: 4 additions & 64 deletions reference/03-Blocks/block-patterns.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,70 +81,6 @@ register_block_pattern(
);
```

## Locking Patterns

You can also use patterns to lock down some aspects of the editorial experience. When creating a pattern you can restrict the ability for a user to move and or remove certain blocks. Additionally you can also restrict what types of blocks are allowed to be used within a columns or group block.

With these controls it becomes much easier to create a refined controlled editorial experience.

### Locking the ability to remove / move a block

Individual blocks can lock down their ability to be moved and or removed. This is done via an attribute that is added by WordPress to every single block called `lock`. The `lock` attribute is an object that accepts two properties: `move` and `remove`. Both of them are `Boolean` values. There is no UI to control the lock state of a block. It can only be controlled via code.

In a pattern you can set these attributes via the html comment of the block where you can set its attributes.

```php
<!-- wp:columns -->
<div class="wp-block-columns">
// highlight-start
<!-- wp:column { "lock": { "move": false, "remove": false } } -->
// highlight-end
<div class="wp-block-column">
...
</div>
<!-- /wp:column -->

// highlight-start
<!-- wp:column { "lock": { "move": false, "remove": false } } -->
// highlight-end
<div class="wp-block-column">
...
</div>
<!-- /wp:column -->
</div>
<!-- /wp:columns -->
```

### Restricting which inner blocks can be used

The core column, group, and cover block support the ability to restrict which blocks are allowed within the inner blocks area. This is being done via two attributes that exist on the se blocks. The `allowedBlocks` and `templateLock` attributes can be set via the html comment in patterns to restrict which blocks can be inserted within a specific pattern. And with the ability to also define a `templateLock` you can even make it so that editors cannot move or remove any of the children within a column for example.

```php
<!-- wp:columns -->
<div class="wp-block-columns">
// highlight-start
<!-- wp:column { "allowedBlocks": [ "core/image" ], "templateLock": "all" } } -->
// highlight-end
<div class="wp-block-column">
...
</div>
<!-- /wp:column -->

// highlight-start
<!-- wp:column { "allowedBlocks": [ "core/heading", "core/paragraph" ], "templateLock": "all" } } -->
// highlight-end
<div class="wp-block-column">
...
</div>
<!-- /wp:column -->
</div>
<!-- /wp:columns -->
```

:::tip
Since these patterns are php files you can make the `allowedBlocks` list filterable via an `apply_filters` hook.
:::tip

## Caveats with using Block Patterns

:::caution
Expand All @@ -154,3 +90,7 @@ There is one item that you need to be aware about in regards to Block Patterns.
If you find an issue with the markup of a pattern that you want to fix it is only going to impact new instances of the pattern that are created after you updated it. And you will have to manually go into every instance that was created using the pattern and make the update manually, or create an update script to update it in the database directly.

If you want to get around this limitation you can of course also build block patterns made up of [custom-blocks](./custom-blocks) that don't actually store their markup in the database. That way you can get the benefits of both worlds.

## Links

- [Block Locking - 10up Gutenberg Reference](./block-locking.md)
Binary file added static/img/block-locking-ui.gif
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 2eb7c07

Please sign in to comment.