Skip to content

Commit

Permalink
Merge pull request #24 from Automattic/add/support-for-missing-settings
Browse files Browse the repository at this point in the history 
Add support for missing settings and change the allowedChildren to allowedBlocks
  • Loading branch information
@ingeniumed
ingeniumed committed Aug 28, 2023
2 parents f303f98 + 80b132a commit e74944e
Show file tree
Hide file tree
Showing 14 changed files with 195 additions and 91 deletions.
178 changes: 141 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,28 +4,28 @@

# VIP Governance plugin

This WordPress plugin enables additional governance capabilities to the block editor.

We have approached this plugin from an opt-in standpoint. In other words, enabling this plugin without any rules will severly limit the editing experience. The goal is to create a stable editor with new blocks and features being enabled explicitly via rules, rather than implicitly via updates.

We consider two dimensions:
This WordPress plugin enables additional governance capabilities to the block editor. This is accomplished via two dimensions:

- Insertion: restricts what kind of blocks can be inserted into the block editor. Only what’s allowed can be inserted, and nothing else. This means that even if new core blocks are introduced they would not be permitted.
- Interaction: This adds the ability to control the styling available for blocks at any level.

We have approached this plugin from an opt-in standpoint. In other words, enabling this plugin without any rules will severly limit the editing experience. The goal is to create a stable editor with new blocks and features being enabled explicitly via rules, rather than implicitly via updates.

## Table of contents

- [Installation](#installation)
- [Install via `git subtree`](#install-via-git-subtree)
- [Install via ZIP file](#install-via-zip-file)
- [Plugin activation](#plugin-activation)
- [Usage](#usage)
- [Your First Rule](#your-first-rule)
- [Schema Basics](#schema-basics)
- [Limitations](#limitations)
- [Sample Rules](#sample-rules)
- [Default](#default)
- [Restrictions](#restrictions)
- [Your First Rule](#your-first-rule)
- [Examples](#examples)
- [Default Rule Set](#default-rule-set)
- [Restrictive Rule Sets](#restrictive-rule-sets)
- [Default Restriction Example](#default-restriction-example)
- [User Role Specific Restriction Example](#user-role-restriction-example)
- [Limitations](#limitations)
- [Code Filters](#code-filters)
- [`vip_governance__is_block_allowed_for_insertion`](#vip_governance__is_block_allowed_for_insertion)
- [`vip_governance__is_block_allowed_for_editing`](#vip_governance__is_block_allowed_for_editing)
Expand Down Expand Up @@ -83,12 +83,6 @@ To activate the installed plugin:

In order to start using this plugin, you'll need to create `governance-rules.json` in [your private folder][wpvip-private-dir].

### Your First Rule

Each ruleset must define your `default` rule. You can see an example definition in `governance-rules.json` in this repository. We recommend duplicating this file into your [private folder][wpvip-private-dir] as a start. In order to use the rules schema for in-editor support, also duplicate the `governance-schema.json` into your private folder.

This default rule represents the absolute minimum that will be available to website users. It is sensible to set your default rule to your most common settings and then override with role specific rules.

### Schema Basics

You can find the schema definition that's used for the rules [here][repo-schema-location]. Including a schema entry in your rules will provide for code completion in most editors.
Expand All @@ -102,36 +96,29 @@ Rule's of the type `role` require an array of `roles` that will use this particu
Each rule can have any one of the following properties.

- `allowedFeatures`: This is an array of the features that are allowed in the block editor. This list will expand with time, but we currently support two values: `codeEditor` and `lockBlocks`. If you do not want to enable these features, simply omit them from the array.
- `blockSettings`: These are specific settings related to the styling available for a block. They match the settings availble in theme.json [as defined here][gutenberg-block-settings]. Unlike theme.json, you can nest these rules to apply different settings depending on the parent of a particular block. Additionaly you can set `allowedChildren` to restrict nested blocks.
- `blockSettings`: These are specific settings related to the styling available for a block. They match the settings availble in theme.json under the key `blocks`. The definition for that, can be [found here][gutenberg-block-settings]. Unlike theme.json, you can nest these rules to apply different settings depending on the parent of a particular block. Additionaly you can set `allowedBlocks` to restrict nested blocks.
- `allowedBlocks`: These are the blocks that are allowed to be inserted into the block editor.

The role specific rule will be merged with the default rule. This is done intentionally to avoid needless repetition of your default properties.

#### Limitations

- We highly recommend including `core/paragraph` in `allowedBlocks` for the `default` rule so that all users have access to use paragraph blocks. There are some limitations with the editor that make this necessary:

- The Gutenberg editor uses `core/paragraph` blocks as an insertion primitive. If a user is unable to insert paragraph blocks, then they will also be unable to insert any other block in the same place.
- Some `core` blocks automatically insert `core/paragraph` blocks that can not be blocked by plugin code. For example, the `core/quote` block has a child `core/paragraph` block built-in to block output. Even if a user has `core/paragraph` blocks disabled, they may still be able to access built-in child blocks.

It is possible to disable `core/paragraph` blocks for a role if it makes sense for your workflow, but keep in mind these limitations when doing so.
### Your First Rule

- Currently, this plugin does not support disabling child blocks nested inside a parent. The plugin will prevent you from inserting additional blocks, but existing blocks in existing content will not be removed or restricted.
Each ruleset must define your `default` rule. You can see an example definition in `governance-rules.json` in this repository. We recommend duplicating this file into your [private folder][wpvip-private-dir] as a start. In order to use the rules schema for in-editor support, also duplicate the `governance-schema.json` into your private folder.

- Support for `duotone` and `typography` has not been implemented yet.
This default rule represents the absolute minimum that will be available to website users. It is sensible to set your default rule to your most common settings and then override with role specific rules.

### Sample Rules
### Examples

Below are some examples of some rules that you can use to build your `governance-rules.json`.
Below are some examples of some rule sets that you can use to build your `governance-rules.json`.

#### Default
#### Default Rule Set

This is the default rule set used by the plugin.

```json
{
"$schema": "./governance-schema.json",
"version": "0.1.0",
"version": "0.2.0",
"rules": [
{
"type": "default",
Expand All @@ -149,14 +136,106 @@ With this rule set, the following rules will apply:
- The code editor is accessible for everyone.
- Blocks can be locked and unlocked.

#### Restrictions
#### Restrictive Rule Sets

There are 2 restrictive rule sets below, that will allow restrictions to be placed features available in the block editor, the blocks available, and what style controls are available.

##### Default Restriction Example

This example focuses on restricting for all users, regardless of their role.

```json
{
"$schema": "./governance-schema.json",
"version": "0.2.0",
"rules": [
{
"type": "default",
"allowedFeatures": [ "codeEditor", "lockBlocks" ],
"allowedBlocks": [ "*" ],
"blockSettings": {
"core/group": {
"spacing": {
"spacingSizes": [
{
"size": "clamp(2.5rem, 6vw, 3rem)",
"slug": "300",
"name": "12"
}
],
},
},
"core/heading": {
"color": {
"palette": [
{
"color": "#ff0000",
"name": "Custom red",
"slug": "custom-red"
},
{
"color": "#00FF00",
"name": "Custom green",
"slug": "custom-green"
},
{
"color": "#FFFF00",
"name": "Custom yellow",
"slug": "custom-yellow"
}
],
"gradients": [
{
"slug": "vertical-red-to-green",
"gradient": "linear-gradient(to bottom,var(--wp--preset--color--custom-red) 0%,var(--wp--preset--color--custom-green) 100%)",
"name": "Vertical red to green"
}
]
},
"typography": {
"fontFamilies": [
{
"fontFamily": "Consolas, Fira Code, monospace",
"slug": "code-font",
"name": "Code Font"
}
],
"fontSizes": [
{
"name": "Large",
"size": "2.75rem",
"slug": "large"
},
{
"name": "X-Large",
"size": "3.75rem",
"slug": "x-large"
}
]
}
}
}
}
]
}
```

With this rule set, the following rules will apply:

This is an example in which we want to apply different restrictions based on user role. This will include restrictions on features available in the block editor, the blocks available, and what style controls are available.
- Default: Rules that apply to everyone as a baseline:
- All blocks are allowed.
- The code editor is accessible, and blocks can be locked/unlocked or moved.
- For a heading at the root level, there are 3 custom colours as well as a custom gradient that will show up in the color palette. In addition, a custom font called Code Font as well as 2 custom font sizes will show up in the typography panel.
- For a group block, there will be a only one option for a spacing size available in padding/margin and block spacing.

##### User Role Restriction Example

This example focuses on restricting based on the user role.

```json
{
"$schema": "./governance-schema.json",
"version": "0.1.0",
"version": "0.2.0",
"rules": [
{
"type": "role",
Expand All @@ -165,7 +244,7 @@ This is an example in which we want to apply different restrictions based on use
"allowedBlocks": [ "core/quote", "core/media-text", "core/image" ],
"blockSettings": {
"core/media-text": {
"allowedChildren": [ "core/paragraph", "core/heading", "core/image" ],
"allowedBlocks": [ "core/paragraph", "core/heading", "core/image" ],
"core/heading": {
"color": {
"text": true,
Expand All @@ -180,7 +259,7 @@ This is an example in which we want to apply different restrictions based on use
}
},
"core/quote": {
"allowedChildren": [ "core/paragraph", "core/heading" ],
"allowedBlocks": [ "core/paragraph", "core/heading" ],
"core/paragraph": {
"color": {
"text": true,
Expand Down Expand Up @@ -234,6 +313,19 @@ With this rule set, the following rules will apply:
- The code editor is accessible.
- Blocks can be locked, unlocked and moved.

### Limitations

- We highly recommend including `core/paragraph` in `allowedBlocks` for the `default` rule so that all users have access to use paragraph blocks. There are some limitations with the editor that make this necessary:

- The Gutenberg editor uses `core/paragraph` blocks as an insertion primitive. If a user is unable to insert paragraph blocks, then they will also be unable to insert any other block in the same place.
- Some `core` blocks automatically insert `core/paragraph` blocks that can not be blocked by plugin code. For example, the `core/quote` block has a child `core/paragraph` block built-in to block output. Even if a user has `core/paragraph` blocks disabled, they may still be able to access built-in child blocks.

It is possible to disable `core/paragraph` blocks for a role if it makes sense for your workflow, but keep in mind these limitations when doing so.

- Currently, this plugin does not support disabling child blocks nested inside a parent. The plugin will prevent you from inserting additional blocks, but existing blocks in existing content will not be removed or restricted.

- Support for `color.duotone` has not been implemented.

## Code Filters

There are filters in place, that can be applied to change the behaviour for what's allowed and what's not allowed.
Expand Down Expand Up @@ -385,14 +477,26 @@ composer install --no-dev

### Tests

We currently have unit tests covering php side of the plugin. Run these tests locally with [`wp-env`][wp-env] and Docker:
We currently have unit, and e2e test to ensure thorough code coverage of the plugin. These tests can be run locally with [`wp-env`][wp-env] and Docker.

For the unit tests:

```
wp-env start
composer install
composer run test
```

For the e2e tests:

```
wp-env start
composer install
npm install
npx playwright install chromium --with-deps
npx playwright test
```

<!-- Links -->

[settings-panel-example-gif]: https://github.com/wpcomvip/vip-governance-plugin/blob/media/vip-governance-admin-settings-animation.gif
Expand Down
2 changes: 1 addition & 1 deletion build/index.asset.php
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
<?php return array('dependencies' => array('lodash', 'wp-block-editor', 'wp-components', 'wp-compose', 'wp-data', 'wp-element', 'wp-hooks', 'wp-i18n', 'wp-notices'), 'version' => '4082dc555654426ed71a');
<?php return array('dependencies' => array('lodash', 'wp-block-editor', 'wp-components', 'wp-compose', 'wp-data', 'wp-element', 'wp-hooks', 'wp-i18n', 'wp-notices'), 'version' => 'f535de631ce7052a87cc');
2 changes: 1 addition & 1 deletion build/index.js
View file

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading

0 comments on commit e74944e

Please sign in to comment.