JPKCom DB
View on GitHub (opens in a new tab)

JPKCom Allow Block Types — Guide & Tips

Allow or block Gutenberg block types per role — settings screen, export/import and practical tips for JPKCom Allow Block Types.

JPKCom Allow Block Types controls, per WordPress role, which block types the block editor offers. Handy for keeping editorial teams on a curated set of blocks and the layout consistent. Administrators always see every block and are never affected.

Guide

Requirements

  • WordPress 7.0 or newer (tested up to WordPress 7.1)
  • PHP 8.3 or newer

Installation

  1. In your admin panel, go to Plugins → Add New and click Upload Plugin.
  2. Choose the plugin's ZIP file and click Install Now.
  3. Click Activate.

The settings screen

Under Appearance → Block permissions you get a matrix: every block type known to the site as a row, every non-administrator role as a column. Unticking a box blocks that block for that role. A freshly installed site starts with nothing blocked — every block stays available until you switch it off deliberately.

Blocks are grouped by their block category. A block belonging to a currently deactivated plugin is not dropped but listed under an "Unregistered" group with a warning marker, so a permission set up earlier is never silently lost and can be removed deliberately once the block is really gone. Roles that cannot use the block editor at all (no edit_posts capability, e.g. Subscriber) are hidden by default; a toggle above the table brings them back for sites with custom roles.

A search box, a category filter and per-role column toggles narrow the table down without a page reload — useful once the list runs into the hundreds of rows on a site with many block plugins.

For the full list of available core blocks, see the WordPress core blocks reference (opens in a new tab).

Export and import

Export downloads the current settings as a JSON file, so a permission matrix built on one site can be moved to another.

Import writes nothing on upload alone: choosing a file first shows a preview — how many roles would change, how many block entries that touches, and any role or block name in the file that this site does not currently know about — and only writes once you confirm. Importing merges per role: for every role present in the file, that role's whole list of blocked blocks replaces what was stored; any role the file does not mention is left exactly as it was.

Asking which blocks are allowed: the Abilities API

Since version 3.1.0 the plugin registers one read-only ability, jpkcom-allow-blocks/list-allowed-blocks. The Abilities API is a WordPress core registry of machine-readable capabilities — an AI assistant, an MCP client or REST automation can use it to ask up front which blocks it may actually insert, instead of writing content the editor then refuses.

The answer is produced by the same filter the editor is handed, so it cannot disagree with what the editor accepts.

Two clearly separated things come back:

  1. the effective answer for the calling user, and
  2. how the restriction is configured per role.

Those are two different questions, and keeping them apart matters: a user holding several roles is blocked only from what all of their roles block, and an exempt user gets everything regardless of what any role lists. Exempt by default is anyone with manage_options — itself filterable through jpkcom_allow_blocks_is_exempt.

The ability requires the edit_posts capability; the answer is only meaningful to someone who edits content. To switch it off entirely, in wp-config.php:

define( 'JPKCOM_ALLOW_BLOCKS_ABILITIES', false );

The filter jpkcom_allow_blocks_ability_capability narrows it further; jpkcom_allow_blocks_ability_meta controls how the ability is exposed (REST route, MCP visibility, annotations).

Tips & Tricks

  • Upgrading from 2.x: Up to version 2.x the plugin carried a hard-coded list of 17 blocks and had no settings screen. That list is gone in 3.0.0. More importantly, the old restriction never actually took effect — it was registered inside if ( ! is_admin() ), but the block editor is part of wp-admin. So if you are coming from 2.x, walk through the matrix once after updating: before, everything was effectively allowed; afterwards it is whatever you set there.
  • Breaking change for custom code: jpkcom_allowed_block_types() has been removed with no deprecated shim. It always returned the same hard-coded array, so a shim could only have handed back stale data. If your own code calls it directly, it will fatal from 3.0.0 on.
  • Role logic: The restriction targets non-admins — anyone with manage_options still sees every block. Test the block selection with an account in a lower role (e.g. editor/author). Use the jpkcom_allow_blocks_is_exempt filter to change who is exempt.
  • Blocks registered only in JavaScript: Some blocks are invisible to the PHP-side registry and therefore never show up in the table. Add those names via the jpkcom_allow_blocks_extra_block_names filter.
  • Not a security boundary: The restriction affects the block editor's inserter. It is not a security or content-validation boundary — blocks already present in the content stay, and anything writing content by another route is unaffected.
  • German translation: Since 3.0.0 the plugin ships translations for de_DE and de_DE_formal.
  • Reproducible updates: Since version 2.0.3 the plugin uses secure self-hosted updates via GitHub with SHA256 checksums and runs with declare(strict_types=1).

Further reading