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 within the config-schema.json included within this project, and example-config.json 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.

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 (post meta and taxonomies) independently from a regular post save. You can specify any meta or taxonomy key/values to save, even ones not normally exposed via the REST API.

Parameters

Name	Type	Description
options	Object	Options object
options.meta	Object	Key/values of metadata to be saved. Can be any meta key.
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

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 });
}

Selectors

getIsSavingMetadata

Returns true if currently saving metadata.