Meta field groups, boxes & fields

Field group, meta box, and meta field definition abilities

Category: acpt-content-model · Default capability: manage_options

ACPT's field system has three nested levels — a field group contains meta boxes, and each box contains meta fields — mirroring the Field groups and The meta fields manager UI. Each level has its own set of abilities.

These abilities manage field definitions — the schema of what fields exist and their settings. To read or write the values stored on a specific post/term/user/option page, see Field values.

Field groups

Ability	What it does
acpt/list-meta-groups	Returns field groups, optionally filtered by name
acpt/get-meta-group	Returns a single field group by name, including its boxes and fields
acpt/save-meta-group	Creates a field group, or updates it if the name already exists
acpt/delete-meta-group	Deletes a field group and everything it contains

acpt/list-meta-groups

Input (all optional)

Property	Type	Description
groupName	string	Filter by group name

$result = wp_get_ability('acpt/list-meta-groups')->execute();

acpt/get-meta-group

Input

Property	Type	Required
name	string	Yes

$result = wp_get_ability('acpt/get-meta-group')->execute([
    'name' => 'movie-details',
]);

{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    "id": "b1e2c3d4-5678-4abc-9def-0123456789ab",
    "name": "movie-details",
    "label": "Movie Details",
    "belongs": [
      { "belongsTo": "POST_ID", "operator": "=", "find": "12", "logic": "AND" }
    ],
    "boxes": [ ]
  }
}

belongs describes the group's location rules — where the group is attached. find and operator scope it further (e.g. to a specific post type or term).

acpt/save-meta-group

Input

Property	Type	Required	Notes
name	string	Yes	If a group with this name already exists, it's updated instead of duplicated
label	string	No
belongs	array	No	Location rules, see above
boxes	array	No	Full nested boxes/fields definition — you can also manage boxes and fields one at a time with the abilities below instead of resending the whole tree

$result = wp_get_ability('acpt/save-meta-group')->execute([
    'name'  => 'movie-details',
    'label' => 'Movie Details',
    'belongs' => [
        ['belongsTo' => 'POST_ID', 'find' => 'movie'],
    ],
]);

acpt/delete-meta-group

Input

Property	Type	Required
name	string	Yes

$result = wp_get_ability('acpt/delete-meta-group')->execute([
    'name' => 'movie-details',
]);

Meta boxes

Ability	What it does
acpt/list-meta-boxes	Returns the boxes in a given field group
acpt/get-meta-box	Returns a single box by name, including its fields
acpt/save-meta-box	Creates a box inside a group, or updates it if the name already exists in that group
acpt/delete-meta-box	Deletes a box (and its fields) from a group

There's no ungrouped/global box listing — acpt/list-meta-boxes always requires a group_name.

acpt/list-meta-boxes

Input

Property	Type	Required
group_name	string	Yes

$result = wp_get_ability('acpt/list-meta-boxes')->execute([
    'group_name' => 'movie-details',
]);

acpt/get-meta-box

Input

Property	Type	Required
name	string	Yes

$result = wp_get_ability('acpt/get-meta-box')->execute([
    'name' => 'info',
]);

acpt/save-meta-box

Input

Property	Type	Required	Notes
groupName	string	Yes	The field group this box belongs to
name	string	Yes	If a box with this name already exists in that group, it's updated instead of duplicated
new_name	string	No	Renames the box
label	string	No
fields	array	No	Meta field definitions, see Meta fields below

$result = wp_get_ability('acpt/save-meta-box')->execute([
    'groupName' => 'movie-details',
    'name'      => 'info',
    'label'     => 'Info',
]);

acpt/delete-meta-box

Input

Property	Type	Required
group_name	string	Yes
name	string	Yes

$result = wp_get_ability('acpt/delete-meta-box')->execute([
    'group_name' => 'movie-details',
    'name'       => 'info',
]);

Meta fields

Ability	What it does
acpt/list-meta-fields	Returns the field definitions attached to a given location
acpt/get-meta-field	Returns a single field definition by box name and field name
acpt/save-meta-field	Creates a field inside a box, or updates it if the name already exists in that box
acpt/delete-meta-field	Deletes a field definition from a box

acpt/list-meta-fields

Unlike the other list abilities, this one is scoped by location rather than returning everything — it mirrors get_acpt_meta_field_objects().

Input

Property	Type	Required	Description
belongsTo	string	Yes	The location type these fields belong to (e.g. a custom post type, taxonomy, user, or option page identifier)
find	string	No	Restrict to a specific location slug/id within belongsTo
clonedFields	boolean	No

$result = wp_get_ability('acpt/list-meta-fields')->execute([
    'belongsTo' => 'customPostType',
    'find'      => 'movie',
]);

acpt/get-meta-field

Input

Property	Type	Required
box_name	string	Yes
field_name	string	Yes

$result = wp_get_ability('acpt/get-meta-field')->execute([
    'box_name'   => 'info',
    'field_name' => 'release_date',
]);

{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    "id": "c2d3e4f5-6789-4abc-9def-0123456789ab",
    "name": "release_date",
    "type": "Date",
    "defaultValue": null,
    "description": "The movie's theatrical release date",
    "isRequired": true,
    "showInArchive": false,
    "options": [],
    "visibilityConditions": [],
    "advancedOptions": [],
    "relations": [],
    "validationRules": [],
    "hasChildren": false
  }
}

acpt/save-meta-field

Input

Property	Type	Required	Notes
groupName	string	Yes	The field group this field belongs to
boxName	string	Yes	The meta box this field belongs to
name	string	Yes	If a field with this name already exists in that box, it's updated instead of duplicated
type	string	Yes	One of ACPT's field types, written exactly as ACPT names it (case-sensitive): Text, Textarea, Number, Date, Image, Select, Repeater, FlexibleContent, Post (relational), …
label	string	No	The field's label
new_name	string	No	Renames the field
parentName	string	No	Nests this field as a child of an existing Repeater/List field
defaultValue	string|null	No
description	string	No
isRequired	boolean	No
showInArchive	boolean	No
options	array	No	For Select/Radio/Checkbox fields — see Select, checkbox, and radio
visibilityConditions	array	No	See Conditional rendering
advancedOptions	array	No	See Advanced options
relations	array	No	For Relational fields — see Relational field
validationRules	array	No	See Validation rules
children	array	No	Nested field definitions, for Repeater/List fields
blocks	array	No	Nested block definitions, for Flexible Content fields

$result = wp_get_ability('acpt/save-meta-field')->execute([
    'groupName'   => 'movie-details',
    'boxName'     => 'info',
    'name'        => 'release_date',
    'type'        => 'Date',
    'description' => "The movie's theatrical release date",
    'isRequired'  => true,
]);

Updating an existing field only changes the properties you send: everything else (options, advanced options, validation rules, children, …) is kept, and the field keeps its position in the box. Before ACPT 2.1.1, an updated field was moved to the bottom of its box.

acpt/delete-meta-field

Input

Property	Type	Required
group_name	string	Yes
box_name	string	Yes
field_name	string	Yes

$result = wp_get_ability('acpt/delete-meta-field')->execute([
    'group_name' => 'movie-details',
    'box_name'   => 'info',
    'field_name' => 'release_date',
]);