Skip to content

Commit

Permalink
Added Docs for Editor Tools
Browse files Browse the repository at this point in the history
  • Loading branch information
jdamner committed Jun 19, 2024
1 parent 110fefb commit cf6f8fc
Show file tree
Hide file tree
Showing 13 changed files with 128 additions and 134 deletions.
15 changes: 0 additions & 15 deletions docs/editor-tools/BlockLoader.md

This file was deleted.

14 changes: 0 additions & 14 deletions docs/editor-tools/Comments.md

This file was deleted.

43 changes: 0 additions & 43 deletions docs/editor-tools/Security.md

This file was deleted.

33 changes: 0 additions & 33 deletions docs/editor-tools/index.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# WP Packages

Contents:
- [Editor Tools](./editor-tools/index.md)
- [Editor Tools](../packages/editor-tools/README.md)
- [Iconography](./iconography/index.md)
46 changes: 46 additions & 0 deletions packages/editor-tools/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,53 @@
# Box WordPress Editor Tools

A collection of tools for modifying the WordPress Editor.

## Quick Start!

All the tools load automatically if you've installed this as a plugin to your WordPress site. If not, you can use each class as needed.

There's more options for each tool, so checkout the links below:

## Features

- [Asset Loader](./docs/AssetLoader.md) - help load assets generated by [wp-scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/).
- [Block Loader](./docs/BlockLoader.md) - auto-loads blocks to the editor.
- [Comment Disablement](./docs/Comments.md) - disables comments.
- [Editor Cleanup](./docs/EditorCleanup.md) - removes some unnecessary bits from the block editor.
- [Post Type Registrations](./docs/PostTypes.md) - speeds up post-type registration with a single JSON file.
- [Template Persistence](./docs/TemplatePersistence.md) - speeds up template modifications by saving to disk instead of the database.
- [Security](./docs/Security.md) - Adds security hardening.

## Contributing

# Box WordPress Editor Tools

A collection of tools for modifying the WordPress Editor.

## Quick Start!

All the tools load automatically if you include this plugin in your WP installation, or you can access the classes independently if you don't want to use this library as a plugin.

There's more options too, so checkout the links below:

## Features

- [Asset Loader](./AssetLoader.md) - help load assets generated by [wp-scripts](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/).
- [Block Loader](./BlockLoader.md) - auto-loads blocks to the editor.
- [Comment Disablement](./Comments.md) - disables comments.
- [Editor Cleanup](./EditorCleanup.md) - removes some unnecessary bits from the block editor.
- [Post Type Registrations](./PostTypes.md) - speeds up post-type registration with a single JSON file.
- [Template Persistence](./TemplatePersistence.md) - speeds up template modifications by saving to disk instead of the database.
- [Security](./Security.md) - Adds security hardening.

## Contributing

Please do not submit any Pull Requests here. They will be closed.
---

Please submit your PR here instead: https://github.com/boxuk/wp-packages

This repository is what we call a "subtree split": a read-only subset of that main repository.
We're looking forward to your PR there!


File renamed without changes.
16 changes: 16 additions & 0 deletions packages/editor-tools/docs/BlockLoader.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Block Loader

The Block Loader will automatically load all blocks by looking for `block.json` files in a given path. These are loaded with `register_block_type`, see [WordPress Docs](https://developer.wordpress.org/reference/functions/register_block_type/) for more context.

## Usage
Block loader is included automatically, and defaults to loading from your `wp-content/theme/THEME_NAME/build` folder.
You can change this value using the `boxuk_block_loader_base_path` filter.

```php
add_filter(
'boxuk_block_loader_base_path',
function ( string $default_path ): string {
return __DIR__ . '/my-special-path';
}
);
```
11 changes: 11 additions & 0 deletions packages/editor-tools/docs/Comments.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Comment Disablement

This will remove the ability for comments from your WP installation.

## Usage

Comments are disbaled by default, but can be enabled by modifing the `boxuk_disable_comments` filter:

```php
add_filter( 'boxuk_disable_comments', '__return_false' );
```
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,4 @@ This will hide some additional features added to the block editor:
- **WordPress VIP Featured Plugins**: WordPress VIP adds a banner to highlight featured plugins for their platform. Plugins are managed by the developer so this should be hidden.

## Usage
The `init` method should be hooked early in the WordPress Lifecycle
```php
add_action(
'plugins_loaded',
function () {
( new Boxuk\BoxWpEditorTools\EditorCleanup() )->init();
}
);
```
The editor cleanup is enabled automatically and does not have any configurable options.
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,12 @@ A shorthand for registering post types via a JSON file instead of a
whole bunch of PHP to make life just a little bit easier.

## Usage

You need to initialise the class as early as possible.
```php
add_ation(
'plugins_loaded',
function() {
( new Boxuk\BoxWpEditorTools\PostTypes() )->init();
}
);
```
This feature is enabled automatically with the plugin.

You will also need to define a JSON file which configures your post-types. This should be caleld `post-types.json` and live in the root of your theme (`wp-content/themes/{theme_name}/post-types.json`).
```json
{
"$schema": "https://github.com/boxuk/box-wp-editor-tools/post-type.schema.json",
"$schema": "https://raw.githubusercontent.com/boxuk/wp-packages/main/schema/post-type.schema.json",
"post_types": {
"project": {
"has_archive": true,
Expand All @@ -40,6 +31,16 @@ You will also need to define a JSON file which configures your post-types. This
}
```

You can modify the path of this file using the `boxuk_post_types_json_file_path` filter.
```php
add_filter(
'boxuk_post_types_json_file_path',
function ( string $default_path ): string {
return __DIR__ . '/my-path-to/post-types.json';
}
);
```

The schema file will help your IDE populate any fields you think you need. After parsing, the file is passed to `register_post_type()` so the [WordPress documentation](https://developer.wordpress.org/reference/functions/register_post_type/) should be useful!


Expand Down
29 changes: 29 additions & 0 deletions packages/editor-tools/docs/Security.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# Security

Some security hardening features are available for you to use.

## Usage
The security hardening features will load automatically with sensible defaults, but there's a number of filters you can use to configure.

## Filters

| Filter Name | Description | Default Value |
| ----------- | ----------- | ------------- |
| `boxuk_prevent_author_enum` | Prevents access to the author-archive pages | `true` |
| `boxuk_prevent_author_rest_endpoint` | Prevents access to the author API endpoint | `true` |
| `boxuk_send_no_sniff_headers` | Sends `nosniff` and `frame_options` headers | `true` |
| `boxuk_remove_vip_headers` | Removes `X-Hacker` and `X-Powered-By` headers | `true` |
| `boxuk_validate_password` | Enforces strong password validations | `true` |
| `boxuk_restrict_http_request_methods` | Restricts HTTP methods to the known list | `true` |
| `boxuk_disable_rss` | Disables the RSS functionality | `true` |
| `boxuk_modify_session_timeout` | Modifies the default session period to 10 hours | `true` |
| `boxuk_restrict_user_creation` | Restricts creating users in the admin interface | `false` |
| `boxuk_restrict_login_by_username` | Restricts logging in by username (allows by email only) | `true` |


Filters should be added at the earliest possible point, so avoid adding via a hook (ie don't add to `init` you might be too late). WordPress includes helpful return true/false methods to make it super easy to configure.

```php
add_filter( 'example_filter', '__return_true' );
add_filter( 'example_filter', '__return_false' );
```
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,19 @@ One of the biggest annoyances about developing block-based themes is that if you
This change saves your edits to templates to their respective `.html` file. This applies to all `wp_template`, so anything accessed via **Templates** in the site-editor.

## Usage
You need to enable usage of Template Persistence. It's likely you only want to load this on local developer environments.
Template persistence is enabled automatically, but can be disabled by passing a value to the `boxuk_disable_template_persistence` filter:

```php
add_action(
'plugins_loaded',
function () {
if ( 'local' === wp_get_environment_type() ) {
( new Boxuk\BoxWpEditorTools\TemplatePersistence() )->init();
}
add_filter( 'boxuk_disable_template_persistence', '__return_true' );
```

Since local environments can vary so much, we have not included any checks in the template persistence class to validate which environment is used. See [docs for `wp_get_environment_type()`](https://developer.wordpress.org/reference/functions/wp_get_environment_type/) for the above example code.

```php
add_filter(
'boxuk_disable_template_persistence'
function ( bool $default ): bool {
return wp_get_environment_type() === 'local';
}
);
```
Since local environments can vary so much, we have not included any checks in the template persistence class to validate which environment is used. See [docs for `wp_get_environment_type()`](https://developer.wordpress.org/reference/functions/wp_get_environment_type/) for the above example code.

0 comments on commit cf6f8fc

Please sign in to comment.