admin-page.php
Settings screen
A matrix of every known block against every editable role, rendered under Appearance. Read-only in the markup it emits: submitting the form is handled by the admin-post.php callback registered elsewhere.
Tags
Table of Contents
Functions
- jpkcom_allow_blocks_menu_slug() : string
- Slug of the settings page.
- jpkcom_allow_blocks_editable_roles() : array<string, string>
- Roles that can be restricted from the settings screen.
- jpkcom_allow_blocks_block_rows() : array<int, array{name: string, title: string, category: string, registered: bool}>
- Rows for the block matrix.
- jpkcom_allow_blocks_render_import_preview() : void
- Render the pending import preview, if a valid one exists.
- jpkcom_allow_blocks_import_error_message() : string
- Translated message for a known import error code.
- jpkcom_allow_blocks_render_page() : void
- Render the settings screen.
- jpkcom_allow_blocks_apply_form() : array<string|int, mixed>
- Compute new settings from a settings-screen submission.
Functions
jpkcom_allow_blocks_menu_slug()
Slug of the settings page.
jpkcom_allow_blocks_menu_slug() : string
Tags
Return values
string —Menu slug.
jpkcom_allow_blocks_editable_roles()
Roles that can be restricted from the settings screen.
jpkcom_allow_blocks_editable_roles([bool $include_non_editing = false ]) : array<string, string>
Administrators are never offered: they always bypass the filter, so a
checkbox for them would be a lie. Roles without edit_posts never see
the block editor, so they are hidden by default and only surfaced when
explicitly asked for. A slug the store would refuse (anything
sanitize_key() would change, e.g. a custom role registered with
upper case or spaces) is never offered either: the UI must not put a
column on screen whose ticks jpkcom_allow_blocks_sanitize_settings()
would silently discard on save.
Parameters
- $include_non_editing : bool = false
-
Whether to also include roles that cannot edit posts.
Tags
Return values
array<string, string> —Role slug to display name.
jpkcom_allow_blocks_block_rows()
Rows for the block matrix.
jpkcom_allow_blocks_block_rows(array<string|int, mixed> $settings) : array<int, array{name: string, title: string, category: string, registered: bool}>
The union of the registered blocks and every block name mentioned in the settings, so a block from a deactivated plugin still shows up instead of silently vanishing from the screen that would otherwise unblock it.
Parameters
- $settings : array<string|int, mixed>
-
Validated settings.
Tags
Return values
array<int, array{name: string, title: string, category: string, registered: bool}> —Rows, sorted by category then title.
jpkcom_allow_blocks_render_import_preview()
Render the pending import preview, if a valid one exists.
jpkcom_allow_blocks_render_import_preview() : void
Reads the token the preview handler put in the jpkcom-ab-import query
argument, fetches the parsed settings it stashed in a transient under
that token, and renders a confirmation block inside the caller's
.wrap - never a standalone document, so the import flow never leaves
the admin chrome. A missing or expired transient renders an
explanatory notice instead and the normal screen still renders
underneath it.
Tags
jpkcom_allow_blocks_import_error_message()
Translated message for a known import error code.
jpkcom_allow_blocks_import_error_message(string $code) : string
The error travels through the query string as a short code rather than free text, so a crafted link cannot put arbitrary words in front of an administrator. A code this function does not recognise is ignored - the caller shows no notice at all rather than falling back to something generic.
Parameters
- $code : string
-
Error code produced by includes/import-export.php.
Tags
Return values
string —Translated message, or '' when the code is unknown.
jpkcom_allow_blocks_render_page()
Render the settings screen.
jpkcom_allow_blocks_render_page() : void
Emits the controls, the save form with its checkbox matrix, and the import/export section, in that order. A checkbox is checked when the block is not blocked for that role, i.e. it reflects the allow list rather than the stored deny list.
Tags
jpkcom_allow_blocks_apply_form()
Compute new settings from a settings-screen submission.
jpkcom_allow_blocks_apply_form(array<string|int, mixed> $settings, array<string|int, string> $rendered, array<string, array<string, mixed>> $allowed[, array<string, mixed> $forget = array() ][, array<string|int, string>|null $roles = null ]) : array<string|int, mixed>
The difference is taken over the rendered rows only: names the form did not show keep whatever they had. A save while the table is filtered must not wipe the rows that were scrolled out of view.
An unregistered row can be dropped for good in two ways: ticking
forget[<name>] removes it from every role the stored settings
currently know about and from labels unconditionally, regardless
of the per-role checkboxes on the same row and regardless of whether
a given role was even rendered this save (see below); and, even
without ticking it, a row that ends up blocked by no role at all
after this save has its label dropped automatically once the block
is not registered - a name nobody blocks and nothing registers has
no reason to persist. A registered block's label is always refreshed
from its current title, never from the block name: a block without a
real title in its registration is not given one here either.
Forget deliberately purges more broadly than the checkbox diff does.
The checkbox diff below is scoped to $roles because that has to
match exactly what was rendered - see the parameter doc. But "forget
this block" is a stronger promise than "uncheck every box I can see":
a role hidden by the "show roles without edit_posts" toggle can still
block the same name, and if forget only cleared the rendered roles,
the name would keep blocking silently in the hidden role while
disappearing from labels - unregistered, unreachable, and still
growing the option, the exact failure this mechanism exists to close.
$rendered is only deduplicated here, not validated: an invalid name
moving through this function does no harm because
jpkcom_allow_blocks_sanitize_settings() always filters the role
lists and labels it returns against the block-name grammar, so a
second filter pass here would be provably redundant rather than a
second line of defence.
Parameters
- $settings : array<string|int, mixed>
-
Current validated settings.
- $rendered : array<string|int, string>
-
Block names the form rendered.
- $allowed : array<string, array<string, mixed>>
-
Ticked boxes, keyed role then block name.
- $forget : array<string, mixed> = array()
-
Rows whose "forget this block" box was ticked, keyed by block name.
- $roles : array<string|int, string>|null = null
-
Role slugs the checkbox diff processes, matching what was rendered. Defaults to every editable role, including ones that cannot edit posts. Does not limit the forget purge, which always reaches every role already present in
$settings['roles']in addition to these.
Tags
Return values
array<string|int, mixed> —New settings, not yet stored.