This page describes the public API related to custom field groups and fields in Toolset.

The following functions and interfaces are available in all Toolset plugins since the Toolset Types 3.3.5 release. You must have the Types plugin active for them to work properly.

Introduction

We are using several terms which deserve proper definition:

  • Element – A generalizing name for a post, a user, or a term.
  • Domain – Describes what type of an element we’re dealing with (posts, users, terms).
  • Custom field group – A collection of field definitions that also contains rules about where it should be displayed.
  • Custom field definition – Describes a field that can be displayed with certain elements, according to its field group display rules and conditions. This involves field type, slug, title, etc.
  • Custom field instance – A field definition applied on a particular element (of a matching domain), that can hold a specific field value.

An example:

  • We can have a custom field group Book info for the domain posts, attached to the post type book.
  • In the Book info group, we have a field definition of a text field ISBN.
  • When we create a post of the book type, for example, Brave New World, the instance of the ISBN field for this post can hold the value 978-0060850524.

Interfaces

Some functions in this API return objects that represent custom field groups, definitions, and instances. For these objects, we are exposing PHP interfaces as part of the public API.

Always rely only on methods defined in the interface, never on other methods that the object may have, or on the fact that the object is an instance of a particular class. Those circumstances are internal to Toolset and may change at any time without a warning.

All interfaces mentioned here belong to the \OTGS\Toolset\Common\PublicAPI PHP namespace. To keep things short and readable we omitted the namespace from their names in this document.

CustomFieldGroup

This interface represents a single field group and offers only basic information about it.

Methods

get_slug()

Returns: string The slug of the field group (unique within the domain).

get_display_name()

Returns: string Display name (title) of the field group.

get_field_definitions()

Returns: CustomFieldDefinition[] An array of custom field definitions that belong to this group.

get_field_definition()

For a given field slug, return its definition, if it exists within the group.

Parameters:

  1. string $field_slug The slug of the custom field.

Returns: CustomFieldDefinition|null The custom field definition or null if the field is not part of the group.

CustomFieldDefinition

Represents a custom field definition.

Methods

get_slug()

Returns: string The slug of the custom field (unique within the domain).

get_name()

Returns: string Display name (title) of the custom field.

get_type_slug()

Returns: string The slug of the field type (e.g. 'audio', 'skype', 'checkbox', etc.)

get_type()

Returns: CustomFieldTypeDefinition An object representing the field type.

is_repeatable()

Is the field repeatable – can it have multiple values? Do not confuse with repeatable field groups.

Returns: bool

instantiate()

Provide an instance of a field for a given element.

Parameters:

  1. int $element_id The ID of an existing element (of a matching domain).

Throws:

  • \InvalidArgumentException if an invalid argument is provided (for example, if the element with the given ID does not exist).

Returns: CustomFieldInstance An instance of the field.

CustomFieldTypeDefinition

Represents a field type and exposes some additional information about it.

get_slug()

Returns: string The slug of the field type (same value as CustomFieldDefinition::get_type_slug() would return).

get_display_name()

Returns: string Display name of the field type (e.g. for the field type with slug image, the result would be 'Image', but also translated to the current language).

get_description()

Returns: string Description of the field type.

can_be_repeating()

Checks if fields of this type can be repeating (if they can have multiple values). For a particular field definition, you would use CustomFieldDefinition::is_repeatable() to check this.

Returns: bool

get_icon_classes()

Retrieves CSS classes for a field type icon. To be placed in the i tag. Additional assets may be needed for this to work properly.

Returns: string

CustomFieldInstance

Represents a single field instance. Field instance means this is a particular field for a particular element (post, term or user), and it is possible to access the field value.

get_definition()

Get the custom field definition.

Returns: CustomFieldDefinition

get_value()

Get the raw custom field value.

The result is not sanitized and the data structure depends on the field type and other properties. It is recommended to use the render() method instead.

Returns: mixed Raw field value, depending on the field type and other aspects. No guarantees are provided regarding the returned type.

render()

Render the field value for a given purpose.

Parameters:

  1. string $purpose One of the purposes as defined in CustomFieldRenderPurpose (see the Constants chapter).

Returns: mixed Field value. The return type depends on the field type and selected purpose.

Constants

Apart from interfaces, we also define several constants used within this API.

Each set of constants has its own sub-namespace under \\OTGS\\Toolset\\Common\\PublicAPI.

CustomFieldRenderPurpose

Constants used for specifying the rendering purpose in CustomFieldInstance::render().

  • PREVIEW: Field preview (used in the admin, for example in term listings). This will produce HTML code with a preview of the field value. Depending on the type, it may be a small thumbnail, an excerpt of the value, the first few values of a repeating field, etc. It is probable that it will not show the complete information.
  • REST: Probably the most usable format. Field value in an associative array of the same format that is provided via REST API.
  • RAW: Obtain a raw value of the field. This is equivalent of using the get_value() method of the field instance.

ElementDomain

Constants for element domains (as defined in the introduction chapter).

  • POSTS
  • USERS
  • TERMS

Functions

Finally, these are the public functions (in the global namespace) that can be used to work with custom field groups, definitions, and instances.

toolset_get_field_groups()

Get field groups based on query arguments.

Parameters

  1. array $args An associative array with query arguments as follows:
    • string 'domain': The only mandatory argument, must be one of the ElementDomain constants.
    • string 'types_search': String for extended search of the field group (searches in slug, name, title, description).
    • bool 'is_active': If defined, only active/inactive field groups will be returned.
    • string 'assigned_to_post_type': For post field groups only, filter results by being assigned to a particular post type.
    • string 'purpose': See Toolset_Field_Group::get_purpose() inline documentation for information about this argument. The default is Toolset_Field_Group::PURPOSE_GENERIC. Special value '*' will return groups of all purposes.

Throws

  • \InvalidArgumentException On invalid input.

Returns: CustomFieldGroup[] An array of custom field groups.

toolset_get_field_group()

Retrieve a particular field group by its slug.

Parameters

  1. string $group_slug The slug of the field group.
  2. string $domain Domain of the field group, must be one of the ElementDomain constants.

Throws

  • \InvalidArgumentException On invalid input.

Returns: CustomFieldGroup|null Field group if it exists, null otherwise.

toolset_get_groups_for_element()

For a given element, query field groups that should be displayed for it.

Note: At the moment, only the post domain is supported. File a feature request if you need to use this for users or terms.

Note: This involves evaluating field group display conditions and may be performance-intensive. Make sure that your code scales well and that, for example, you are not looping over all posts and calling this method.

Parameters

  1. int|WP_Post|WP_User|WP_Term $element_source The element whose field groups need to be returned, or its ID.
  2. string $domain One of the ElementDomain constants.

Throws

  • \InvalidArgumentException if obviously invalid arguments are provided.
  • \RuntimeException if an unsupported domain is used.

Returns: CustomFieldGroup[]|null Array of custom field groups or null if Types is not active or the element does not exist.

toolset_get_fields_for_element()

For the given element, retrieve the array of custom field definitions that should be displayed with it.

Note: At the moment, only the post domain is supported. File a feature request if you need to use this for users or terms.

Internally uses toolset_get_groups_for_element(), make sure you read its description before using this function.

Parameters

  1. int|WP_Post|WP_User|WP_Term $element_source The element whose field definitions need to be returned, or its ID.
  2. string $domain One of the ElementDomain constants.

Throws

  • \InvalidArgumentException if obviously invalid arguments are provided.
  • \RuntimeException if an unsupported domain is used.

Returns: CustomFieldDefinition[]|null Array of custom field definitions or null if Types is not active or the element doesn’t exist.

toolset_get_field_instances()

For the given element, provide instances of its custom fields. This is the way of getting access to all field values of an element.

Note: At the moment, only the post domain is supported. File a feature request if you need to use this for users or terms.

Internally uses toolset_get_fields_for_element(), make sure you read its description before using this function.

Parameters

  1. int|WP_Post|WP_User|WP_Term $element_source The element whose field instances need to be returned, or its ID.
  2. string $domain One of the ElementDomain constants.

Throws

  • \InvalidArgumentException if obviously invalid arguments are provided.
  • \RuntimeException if an unsupported domain is used.

Returns: CustomFieldInstance[]|null An array of custom field instances or null if Types is not active or the element doesn’t exist.

toolset_get_field_instance()

Get a specific field instance. Use this to access one custom field value from a specific element.

Note: At the moment, supports only the post domain. File a feature request if you need to use this for users or terms.

Parameters

  1. int|WP_Post|WP_User|WP_Term $element_source The element whose field instances need to be returned, or its ID.
  2. string $domain One of the ElementDomain constants.
  3. string $field_slug Slug (not meta_key) of the custom field.

Throws

  • \InvalidArgumentException if obviously invalid arguments are provided.
  • \RuntimeException if an unsupported domain is used.

Returns: CustomFieldInstance|null Field instance or null if Types is not active, the element does not exist or the element does not have the requested field.