Skip to content
WP EngineDocumentation

Editorial AI

Editorial AI lets you register AI-powered actions that appear inside the Gutenberg editor — in toolbars and alongside MediaPress Fields fields. Each action declares where it renders, which WordPress Ability it calls, and how it gathers input, presents results, and applies the accepted output.

For domain vocabulary (Action, Extension Point, Ability, etc.) see CONTEXT.md.

An extension point is the location in the editor where an action renders. Use select( 'mediapress/editorial-ai' ).getExtensionPoints() to retrieve the EXTENSION_POINTS constants when registering actions.

Constant Value Where it renders Context extras
EXTENSION_POINTS.TOOLBAR_TOP 'toolbarTop' Top editor toolbar (post-level, next to Publish/Save) —
EXTENSION_POINTS.BLOCK_TOOLBAR 'blockToolbar' Per-block toolbar blockClientId — use to call updateBlockAttributes in applyEffect
EXTENSION_POINTS.FORMAT_TOOLBAR 'formatToolbar' Rich-text selection toolbar —
EXTENSION_POINTS.FIELD_COMPONENT 'fieldComponent' Alongside a MediaPress Fields field fieldName, fieldMetaKey — use in applyEffect to write to the field

Registers an action. Call it inside wp.domReady() — see Registering with the WordPress data store for why, and for the optional chaining this snippet omits for brevity.

const { dispatch, select } = wp.data;
const STORE_NAME = 'mediapress/editorial-ai';
const EXTENSION_POINTS = select(STORE_NAME).getExtensionPoints();
dispatch(STORE_NAME).registerAction({
id: 'my-plugin/my-action',
label: 'My Action',
extensionPoint: EXTENSION_POINTS.TOOLBAR_TOP,
abilityName: 'my-plugin/my-ability',
gatherInput,
presentOutput,
applyEffect,
});
Property Type Required Description
id string Yes Unique identifier. Use 'namespace/slug' to avoid collisions.
label string Yes Text shown in the dropdown.
extensionPoint string Yes One of the EXTENSION_POINTS values.
abilityName string Yes The WordPress Ability to call, in 'namespace/slug' form.
gatherInput function Yes Collects the payload sent to the ability. See gatherInput.
presentOutput function Yes Formats the raw ability response for the approval UI. See presentOutput.
applyEffect function Yes Runs when the editor accepts the response. See applyEffect.
blockNames string[] No Limits this action to specific block types (e.g. ['core/paragraph']). Empty array (default) matches all blocks.
condition function No Extra visibility check beyond block-name matching. See condition.
icon string|Element No WordPress Dashicon name (e.g. 'edit') or a React element.
group string No Group slug registered via registerGroup(). Actions without a group render first.
shouldRunAbility function No Pre-flight guard called before gatherInput. See shouldRunAbility.

Called just before the ability request to build the payload. Return a plain object or a Promise resolving to one — the resolved value is sent to the ability as the request body.

Parameters

Name Type Description
context object See below.

Context shape

Property Type Extension points Description
blockName string BLOCK_TOOLBAR, FORMAT_TOOLBAR The selected block type, e.g. 'core/paragraph'. Empty string on non-block surfaces.
blockAttributes object BLOCK_TOOLBAR, FORMAT_TOOLBAR Attributes of the selected block. Empty object on non-block surfaces.
extensionPoint string All The extension point being rendered.
blockClientId string BLOCK_TOOLBAR Gutenberg block client ID.
richTextValue object FORMAT_TOOLBAR The current WP RichText value (.text, .start, .end).
onRichTextChange function FORMAT_TOOLBAR Callback to write back a modified rich-text value.
fieldName string FIELD_COMPONENT The MediaPress field name.
fieldMetaKey string FIELD_COMPONENT The post meta key backing the field.
targetKey string Regeneration only See below.

targetKey — single-suggestion regeneration

When your action returns a suggestions shape from presentOutput, the approval UI lets the user regenerate individual rows. On those re-runs the framework injects context.targetKey — the SuggestionItem.key for the row being regenerated.

[!NOTE] targetKey is not present on the initial run or on regenerate-all. Use it to narrow the ability call to only the item being regenerated.

gatherInput( context ) {
const input = { postId: wp.data.select( 'core/editor' ).getCurrentPostId() };
// Narrow to one field when regenerating a single suggestion.
if ( context.targetKey ) {
input.fields = [ context.targetKey ];
}
return input;
},

Transforms the raw ability response into something the approval UI can display. The return shape determines which UI the editor sees.

Parameters

Name Type Description
response object Raw JSON response from the ability.

Return shapes

The simplest shape — the approval UI shows the string and lets the editor accept or discard it.

presentOutput( response ) {
return response.summary;
},

Shows the text and a collapsible reasoning section.

presentOutput( response ) {
return {
text: response.summary,
reasoning: response.reasoning,
};
},

The editor picks one option from a list; the chosen string is passed to applyEffect as selectedOption.

presentOutput( response ) {
return {
options: response.title_suggestions,
reasoning: response.reasoning,
};
},

Shows a table of suggestions, each with its own accept and regenerate controls. Use this when the ability returns results for several distinct targets (e.g. multiple SEO fields or multiple blocks).

presentOutput( response ) {
return {
suggestions: [
{ key: 'seo_title', title: 'SEO Title', suggestion: response.seo_title },
{ key: 'seo_description', title: 'SEO Description', suggestion: response.seo_description },
],
reasoning: response.reasoning,
};
},

SuggestionItem shape

Property Type Description
key string Stable identifier for this suggestion. Serves two roles: (1) passed back as context.targetKey when the user regenerates this row; (2) passed to applyEffect as selectedOption when the user accepts this row. Choose a value meaningful in both contexts — a meta field name, a block clientId, etc.
title string Label shown in the suggestions UI.
suggestion string The AI-generated text.
emptyMessage string Optional. Message shown in the row when suggestion is empty or absent.

applyEffect( response, context, selectedOption? )

Section titled “applyEffect( response, context, selectedOption? )”

Runs when the editor accepts the AI response. Write the result to the block editor, post meta, or a MediaPress field here.

Parameters

Name Type Description
response object Raw ability response (same object passed to presentOutput).
context object The same context object passed to gatherInput.
selectedOption string|undefined The value the editor chose. Present only for options and suggestions shapes; the accepted string or SuggestionItem.key respectively.
// Plain text — replace a block attribute.
applyEffect( response, context ) {
wp.data.dispatch( 'core/block-editor' ).updateBlockAttributes(
context.blockClientId,
{ content: response.summary },
);
},
// Options — user picked one title.
applyEffect( response, context, selectedOption ) {
wp.data.dispatch( 'core/editor' ).editPost( { title: selectedOption } );
},
// Suggestions — user accepted one meta field row.
applyEffect( response, context, selectedOption ) {
const meta = {};
meta[ selectedOption ] = response[ selectedOption ];
wp.data.dispatch( 'core/editor' ).editPost( { meta } );
},

An optional pre-flight guard called before gatherInput. Use it to block the ability call when the editor is in a state that would make the request pointless or harmful — for example, when required post meta is missing.

Parameters

Name Type Description
context object Same context object as gatherInput.

Return values

Return value Effect
null / undefined / true Allow — proceed to gatherInput and the ability call.
false Block silently — no notice shown.
ActionNotice with status: 'error' Block and display the notice in the approval UI.

ActionNotice shape

Property Type Description
status 'error'|'warning'|'info'|'success' Notice severity.
children string|ReactNode Notice message content.
isDismissible boolean Defaults to false.
shouldRunAbility( context ) {
const title = wp.data.select( 'core/editor' ).getEditedPostAttribute( 'title' );
if ( ! title ) {
return {
status: 'error',
children: 'Add a post title before running this action.',
};
}
},

An optional visibility check evaluated at render time, after extension-point and block-name matching. Return false to hide the action. Errors in condition are caught and treated as false — they will not propagate.

condition( context ) {
// Only show for posts with a featured image.
return !! wp.data.select( 'core/editor' ).getEditedPostAttribute( 'featured_media' );
},

The editor always calls the ability with POST and the input as a JSON body. It does not read the ability’s annotations, so the ability must not be registered as readonly: core only allows GET for readonly abilities and reads GET input from the query string only, so a POST returns a 405. Register the ability with readonly set to false.


Groups let you organise related actions under a labelled section in the dropdown. Actions without a group always render first, before any grouped section. As with registerAction(), call it inside wp.domReady().

Properties

Property Type Description
name string Slug used as the group value on actions.
label string Human-readable section heading shown in the dropdown.
const { dispatch, select } = wp.data;
const STORE_NAME = 'mediapress/editorial-ai';
const EXTENSION_POINTS = select(STORE_NAME).getExtensionPoints();
dispatch(STORE_NAME).registerGroup({
name: 'content-suggestions',
label: 'Content Suggestions',
});
dispatch(STORE_NAME).registerAction({
// ...
group: 'content-suggestions',
});

Actions are registered in the 'mediapress/editorial-ai' @wordpress/data store. External packages register actions and groups via wp.data.dispatch, and retrieve the EXTENSION_POINTS constants via wp.data.select.

Register inside domReady, and use optional chaining on both select and dispatch:

const { dispatch, select } = wp.data;
const STORE_NAME = 'mediapress/editorial-ai';
wp.domReady(() => {
const EXTENSION_POINTS = select(STORE_NAME)?.getExtensionPoints() ?? {};
dispatch(STORE_NAME)?.registerGroup({
name: 'my-plugin',
label: 'My Plugin',
});
dispatch(STORE_NAME)?.registerAction({
/* ... */
});
});

domReady runs after every enqueued editor script has evaluated, so the editorial-ai store is registered by the time your callback fires — whatever order the scripts happen to load in. Registering later than the UI is safe: the toolbar reads actions and groups reactively, so a late registration simply re-renders.

Do not declare mediapress-editorial-ai as a wp_enqueue_script dependency. WordPress drops a script entirely when a declared dependency is not registered, so doing that would make your whole editor bundle disappear whenever Editorial AI is disabled — taking your unrelated features with it. The optional chaining above is what handles that case: when Editorial AI is off, the registration is a silent no-op and the rest of your script still runs.

wp_enqueue_script(
'my-plugin-editorial-ai-actions',
plugins_url( 'build/actions.js', __FILE__ ),
$asset_file['dependencies'],
'1.0.0',
true,
);

A complete action that suggests values for all fields in the “Titles” fields group, uses targetKey to scope regeneration per-row, and writes accepted values to the correct target — post attributes for headline and excerpt, post meta for short_headline and standfirst.

const { dispatch, select } = wp.data;
const STORE_NAME = 'mediapress/editorial-ai';
// headline → post_title attribute, excerpt → post_excerpt attribute (not meta).
const ATTRIBUTE_FIELDS = { headline: 'title', excerpt: 'excerpt' };
const suggestTitlesAction = {
id: 'my-plugin/suggest-titles',
label: 'Suggest titles',
// WordPress ability which is registered in php that exposes a REST endpoint we can call.
abilityName: 'my-plugin/suggest-titles',
group: 'my-plugin',
gatherInput(context) {
const post = wp.data.select('core/editor').getCurrentPost();
const input = {
post_id: post.id,
content: wp.blocks.serialize(
wp.data.select('core/block-editor').getBlocks(),
),
fields: ['headline', 'short_headline', 'standfirst', 'excerpt'],
};
// On single-row regeneration, narrow to just that field.
if (context.targetKey) {
input.fields = [context.targetKey];
}
return input;
},
presentOutput(response) {
return {
suggestions: [
{ key: 'headline', title: 'Headline', suggestion: response.headline },
{
key: 'short_headline',
title: 'Short Headline',
suggestion: response.short_headline,
},
{
key: 'standfirst',
title: 'Standfirst',
suggestion: response.standfirst,
},
{ key: 'excerpt', title: 'Excerpt', suggestion: response.excerpt },
],
reasoning: response.reasoning,
};
},
// Called once per accepted row; selectedOption is the SuggestionItem.key for that row.
// headline and excerpt are post attributes, not meta — they use different editPost keys.
applyEffect(response, _context, selectedOption) {
const value = response[selectedOption];
if (ATTRIBUTE_FIELDS[selectedOption]) {
wp.data
.dispatch('core/editor')
.editPost({ [ATTRIBUTE_FIELDS[selectedOption]]: value });
} else {
wp.data
.dispatch('core/editor')
.editPost({ meta: { [selectedOption]: value } });
}
},
};
wp.domReady(() => {
const EXTENSION_POINTS = select(STORE_NAME)?.getExtensionPoints() ?? {};
dispatch(STORE_NAME)?.registerGroup({
name: 'my-plugin',
label: 'My Plugin',
});
dispatch(STORE_NAME)?.registerAction({
...suggestTitlesAction,
extensionPoint: EXTENSION_POINTS.TOOLBAR_TOP,
});
});

Last updated: