Fields

MediaPress Fields provides a block-editor integrated approach for managing custom fields, including registration of post meta and custom taxonomies.

Fields are registered via a JSON file which can be used to configure both fields and field groups. They can then be accessed in a dedicated view within the block editor on supported post types.

The fields view can be opened by navigating to the Options menu in the top right of the block editor and selecting “MediaPress Fields” in the dropdown.

The following field types are supported:

• Attributes/Meta
  • text
  • textarea
  • toggle
  • select
  • multi_select
  • checkbox
  • tag
  • image
  • number
  • radio
• Taxonomies
  • checkbox
  • select
  • multi_select
  • tag
  • radio

Additional Configuration

Fields must be activated via the “MediaPress” settings page.

Out of the box, it contains a sample config for testing purposes. You should replace this with your own JSON config file, and point to this file using the appropriate filter.

The exact format of the config file is documented in the plugin at /wp-content/plugins/mediapress-core/packages/fields/config-schema.json and may be accessed from the filesystem or web browser. example-config.json in the same directory shows how this can be implemented.

Registering a field via config

A field is a piece of UI which can be linked to a particular data source to display and edit values.

The data source could be an existing value, or you can configure the field to register a new value.

{
  "fields": [
    {
      "name": "attribute_text_field", // the name of the field, should be unique
      "type": "text", // the type of field to render
      "label": "Attribute Text Field", // the user-friendly name of the field
      "description": "A text field linked to a post attribute", // an optional description for the field
      "source": {
        // the data source that the field is linked to
        "type": "attribute", // supported source types are 'postMeta', 'taxonomy', 'attribute' and 'setting'
        "key": "post_title", // the name of the meta/taxonomy/setting
        "registerFor": ["post", "page"] // (optional) whether to register the source if it doesn't exist.
        // if source.key is 'attribute' - this is not applicable
        // if source.key is 'postMeta' - the name of the post types to register the meta for
        // if source.key is 'taxonomy' - the name of the post type(s) to register the taxonomies for
        // if source.key is 'setting' - the name of the settings group to register the setting for
      },
      "options": [] // (optional) used for certain field-types to define a list of options to choose from, or can be set to either "user" or "taxonomy-{slug}" to enable user or term autocomplete
    }
  ]
}

Registering a field group via config

A field group is a representation of one or more fields to be rendered in a specific location, for example in post block editor or on a settings page.

Fields can be assigned to multiple field groups, and multiple field groups can be rendered in a single location.

Note

If a field type uses a source which is not available in the context it is being rendered, it will not be displayed. For example, if a field uses postMeta, you cannot render this on a settings page.

{
  "fieldGroups": [
    {
      "name": "attributes", // the name of the field group, should be unique
      "label": "Attributes", // the user-friendly name of the field group
      "fields": ["attribute_text_field", "attribute_text_area"], // which fields to include in the field group
      "context": {
        // the location that the field group will be rendered
        "type": "postType", // supported types are 'postType' and 'settingsPage'
        "key": "post" // the specific instance of the postType or settingsPage where the field group will be rendered.
        // if context.type is 'postType' - the name of the post type, the field group will display in the fields panel within the block editor
        // if context.type is 'settingsPage' - the name of the settings page, which must be a MediaPress settings page registered by this config
        // key can support either a string, or an array of strings, in order to render a field group in multiple contexts
        // omitting the key will render the field group in all contexts (all postTypes or all settingsPages)
      }
    }
  ]
}

Registering a settings page via config

A settings page is a page in the WordPress admin area that renders using our Gutenberg-based fields UI.

Settings pages can be top-level, or have a parent, which will cause them to render as sub-menu pages.

Caution

If configuring a sub-menu page, you must ensure the parent comes before it in the config.

{
  "settingsPages": [
    {
      "name": "site-settings", // the name of the settings page, used to register the page, and also within field group contexts
      "label": "Site Settings" // the user-friendly name of the settings page
    },
    {
      "name": "more-settings",
      "label": "More Settings",
      "parent": "site-settings" // (optional) the name of the parent settings page, which will cause this page to render as a sub-menu page
    }
  ]
}

Filters/Actions

JavaScript

Slotfills

Slotfills allow you to render custom content in various locations within the plugin, for example:

import { Fill } from '@wordpress/components';
import domReady from '@wordpress/dom-ready';
import { registerPlugin } from '@wordpress/plugins';

domReady(() => {
  registerPlugin('my-plugin-slotfills', {
    render: () => (
      <Fill name="mediapress_fields_fieldgroup_taxonomies_before">
        <div>
          This will render before the fields in the taxonomies field group
        </div>
      </Fill>
    ),
  });
});

mediapress_fields_fieldgroup_{name}_before

Allows rendering of content in the fields panel before a specific field group, using the group name defined in the config.

mediapress_fields_fieldgroup_{name}_after

Allows rendering of content in the fields panel after a specific field group, using the group name defined in the config.

Filters

mediaPress.fields.editedMetadata

Filters the metadata returned by the getEditedMetadata selector before it is used by the Save Metadata button.

This is useful when fields are linked to an external data store (e.g., Yoast SEO) whose changes are not tracked in the WordPress core-data entity store. The filter allows you to inject additional meta values so they are included in the save payload.

See saveMetadata for which keys the server accepts.

Parameters

Name	Type	Description
editedMetadata	Object	The metadata object containing meta, taxonomies, and attributes
fields	Array	The field definitions for the currently active field group

Return

Type	Description
Object	The (potentially augmented) edited metadata

Usage

import { select } from '@wordpress/data';
import { addFilter } from '@wordpress/hooks';

addFilter(
  'mediaPress.fields.editedMetadata',
  'my-plugin/add-yoast-meta',
  (editedMetadata, fields) => {
    const yoastStore = select('yoast-seo/editor');

    if (!yoastStore) {
      return editedMetadata;
    }

    const snippetData = yoastStore.getSnippetEditorData();

    return {
      ...editedMetadata,
      meta: {
        ...editedMetadata.meta,
        _yoast_wpseo_title: snippetData.title,
        _yoast_wpseo_metadesc: snippetData.description,
      },
    };
  },
);

mediaPress.fields.fieldComponent

Allows for augmentation or replacement of a rendered field component.

This is useful if you want to render additional content, customize any of the field props, perform side-effects or render an entirely custom component.

Parameters

Name	Type	Description
OriginalComponent	JSX.Element	The rendered component to be replaced
Object	args	Arguments for the filter
string	args.source	The field source from the schema, e.g: ‘postMeta’, ‘attribute’, ‘taxonomy’, ‘setting’
string	args.type	The field type from the schema, e.g: ‘text’, ‘select’
string	args.name	The field name from the schema

Usage

addFilter(
  'mediaPress.fields.fieldComponent',
  'my-plugin/wrap-field',
  (OriginalComponent, { name }) => {
    if ('my-field' !== name) {
      return OriginalComponent;
    }

    return <div className="wrapper">{OriginalComponent}</div>;
  },
);

PHP

Filters

mediapress_fields_config_path

Allows the adjustment of the fields config JSON file location

Parameters

Name	Type	Description
path	string	The path to the config.json file

Usage

add_filter( 'mediapress_fields_config_path', 'my_plugin_fields_config_path' );
function my_plugin_fields_config_path( string $path ): string {
  $path = __DIR__ . '/config/my-fields-config.json';
  return $path;
}

mediapress_fields_config

Filters the config immediately after the JSON file is parsed. The outcome of this value is used to register any meta/taxonomies/settings pages as well as defining fields and field groups.

Parameters

Name	Type	Description
config	Array	The parsed fields config

Usage

/**
 * Render an additional settings page with a text field within it
 */
add_filter( 'mediapress_fields_config', 'adjust_config', 10, 1 );
function adjust_config( $config ) {
  $config['fields'][] = [
    'name'   => 'my_api_key',
    'type'   => 'text',
    'label'  => __( 'My API Key', 'my-plugin' ),
    'source' => [
      'type'        => 'setting',
      'key'         => 'my_api_key',
      'registerFor' => 'my-settings',
    ],
  ];

  $config['fieldGroups'][] = [
    'name'    => 'api_keys',
    'label'   => __( 'API Keys', 'my-plugin' ),
    'fields'  => [
      'my_api_key',
    ],
    'context' => [
      'type' => 'settingsPage',
      'key'  => 'my-settings',
    ],
  ];

  $config['settingsPages'][] = [
    'name'  => 'my-settings',
    'label' => __('My Settings Page', 'my-plugin')
  ]


  return $config;
}

mediapress_fields_field_groups

Filters the field groups at the point where they are used to determine which groups/fields to show in a specific context - for example on a specific post type or settings page.

This allows you to customize which fields are rendered for a user, but doesn’t adjust which fields are registered as meta, taxonomies or settings.

Parameters

Name	Type	Description
field_groups_with_data	Array	The current field groups containing fields to be rendered
type	Array	The type of the current field group context, e.g: postType, settingsPage
key	Array	The key of the current field group context, i.e: the post type or settings page slug

Usage

/**
 * Avoid rendering a certain field unless the current user can edit options
 */
add_filter( 'mediapress_fields_field_groups', 'hide_fields', 10, 3 );
function hide_fields( $field_groups_with_data, $type, $key ) {
  if ( current_user_can( 'manage_options' ) ) {
    return $field_groups_with_data;
  }

  if ( 'postType' !== $type || 'post' !== $key ) {
    return $field_groups_with_data;
  }

  foreach ( $field_groups_with_data as $index => $field_group ) {
    if ( isset( $field_group['name'] ) && 'my_field' === $field_group['name'] ) {
      unset( $field_groups_with_data[ $index ] );
    }
  }

  return array_values( $field_groups_with_data );
}

Store

This package exposes a redux store named mediapress/fields with the following methods available:

Actions

saveMetadata

Used to trigger a save of post metadata (attributes, post meta and taxonomies) independently from a regular post save. The post that is saved is always the one in the request URL.

Attributes, taxonomies and REST-registered meta are saved by WordPress core’s REST posts controller for the post type, as the current user, so core decides what that user may change. For example, publishing needs the publish capability, changing the author needs edit_others_posts, and assigning terms needs the taxonomy’s assign_terms capability. A refusal from core is returned as it is.

• Attributes use wp_insert_post() column names: post_title, post_excerpt, post_name, post_status, post_date, post_date_gmt, post_password, post_author, post_parent, menu_order, comment_status and ping_status. They are translated to core’s REST field names. Any other post column is refused with a 400, for example ID, post_type and post_content. A key that is not a post column, such as the REST spelling excerpt, or meta_input and tax_input (use meta and taxonomies instead), is ignored and the rest of the group still saves: send post_excerpt, not excerpt. An attribute the post type does not support is refused with a 400.
• Taxonomies are keyed by taxonomy name. A taxonomy that is not exposed in REST for the post type, or whose rest_base is the name of another field such as meta or author, is refused with a 400.
• Meta keys registered with show_in_rest for the post type are written by core, including the key’s auth_callback and the edit_post_meta capability. To save your own meta key through this route, register it with show_in_rest for the post type, and note that the post type needs custom-fields support for core to expose meta at all. Any other key is refused with a 400. The route used to accept any meta key, so this is narrower than before, with one compatibility exception below.
  • Compatibility allowlist for three Yoast SEO keys. This is not general Yoast support. Existing integrations send Yoast values as raw keys in the generic meta payload, and these three keys are allowed so that keeps working: _yoast_wpseo_title, _yoast_wpseo_metadesc and _yoast_wpseo_focuskw. They can be saved on any post type, including pages and custom post types where Yoast does not register them with show_in_rest, but only while Yoast is active. Each value must be a string (an empty string is a valid value and clears the field), or the request is refused with a 400. Anyone who can edit the post can save them, the same as Yoast’s own rule for these keys. Every other Yoast key (for example canonical, robots or the social keys) is refused with a 400 like any other unregistered key, and there is no filter to add keys. This is a stopgap: Yoast and ACF as distinct field sources are planned to replace it.

Everything is checked before anything is saved, so a request with a refused key saves nothing. The values are saved in one update of the post, so after-save hooks such as save_post run once and see the new values, and the post gets one revision under core’s usual rules. A request with nothing to save (for example an empty meta) succeeds without changing the post. The response is core’s REST item for the post in the edit context, or empty when there was nothing to save.

Parameters

Name	Type	Description
options	Object	Options object
options.meta	Object	Key/values of metadata to be saved.
options.taxonomies	Object	Key/values of taxonomies to be saved. Keys should be the actual taxonomy name (not rest base). Values should be arrays of integers
options.attributes	Object	Key/values of post attributes to be saved, using wp_insert_post() column names.

Usage

function myPluginSaveMetadata() {
  const yoastData = select('yoast-seo/editor').getSnippetEditorData();

  const meta = {
    _yoast_wpseo_title: yoastData.title,
    _yoast_wpseo_metadesc: yoastData.description,
  };

  const postEdits = select('core/editor').getPostEdits();

  const taxonomies = {
    ...(postEdits?.categories && { category: postEdits.categories }),
    ...(postEdits?.tags && { post_tag: postEdits.tags }),
  };

  dispatch.saveMetadata({ meta, taxonomies });
}

openFieldGroup

Opens the fields sidebar panel in the block editor and optionally navigates to a specific field group by name.

If no groupName is provided, the sidebar opens at whichever group is currently active.

Parameters

Name	Type	Description
groupName	string	(Optional) The name of the field group to navigate to

Usage

import { dispatch } from '@wordpress/data';

// Open the fields sidebar and navigate directly to the 'seo' field group
dispatch('mediapress/fields').openFieldGroup('seo');

// Open the fields sidebar without changing the active group
dispatch('mediapress/fields').openFieldGroup();

Selectors

getIsSavingMetadata

Returns true if currently saving metadata.

getActiveFieldGroup

Returns the name of the currently active field group, or null if none is set.

Return

Type	Description
string|null	The active field group name, or null

Usage

import { select } from '@wordpress/data';

const activeFieldGroup = select('mediapress/fields').getActiveFieldGroup();

getEditedMetadata

Returns only the meta, taxonomy, and attribute values that have been edited (i.e. differ from the last saved values) for a given set of field definitions. Used internally by the Save Metadata button and by the mediaPress.fields.editedMetadata filter.

Parameters

Name	Type	Description
fields	Array	The field definitions to check for unsaved changes

Return

Type	Description
Object	Object with meta, taxonomies, and attributes keys containing only the changed values

Usage

import { select } from '@wordpress/data';

const { meta, taxonomies, attributes } =
  select('mediapress/fields').getEditedMetadata(fields);