Fieldmanager_Context_Term

class Fieldmanager_Context_Term extends Fieldmanager_Context_Storable (View source)

Use fieldmanager to create meta boxes on the new/edit term screens and save data primarily to term meta.

Properties

Fieldmanager_Field $fm

Base field
string $uniqid

Unique ID of the form. Used for forms that are not built into WordPress.

 from  Fieldmanager_Context
array $save_keys

Store the meta keys this field saves to, to catch naming conflicts.

 from  Fieldmanager_Context
array $taxonomies_to_save

Taxonomies to save to.

 from  Fieldmanager_Context_Storable
string $title

Title of field to display in standard term form field location.
array $taxonomies

What taxonomies to render these fields.
bool $show_on_add

Whether or not to show the fields on the term add form.
bool $show_on_edit

Whether or not to show the fields on the term edit form.
int $parent

Only show this field on child terms of this parent.
array $reserved_fields

Field names reserved for WordPress on the term add/edit forms.
bool $use_fm_meta

Use FM term meta or WordPress core term meta. The default is a bit confusing: technically, it's to use core's term meta, but if the class is instantiated using the now-deprecated separated arguments, this gets set to true for backwards-compatibility purposes.
protected array|null $inserting_term_data

Store data for inserted terms to ensure, as much as possible, that FM only stores data to the term being created and not any other term created as a side effect.

Methods

__construct(array|string $args, string|array $taxonomies = array(), bool $show_on_add = true, bool $show_on_edit = true, string $parent = '', Fieldmanager_Field $fm = null)

Instantiate this context. You can either pass an array of all args (preferred), or pass them individually (deprecated).

string
nonce_key()

Get the nonce key for this field.

from  Fieldmanager_Context
array
refresh_nonce(array $response)

Include a fresh nonce for this field in a response with refreshed nonces.

from  Fieldmanager_Context
bool
is_valid_nonce()

Check if the nonce is valid. Returns false if the nonce is missing and throws an exception if it's invalid. If all goes well, returns true.

from  Fieldmanager_Context
mixed
prepare_data(mixed $old_value = null, mixed $new_value = null, object $fm = null)

Prepare the data for saving.

from  Fieldmanager_Context
string
render_field(array $args = array())

Render the field.

from  Fieldmanager_Context_Storable
save(mixed $data = null)

Handle saving data for any context.

from  Fieldmanager_Context_Storable
save_field(object $field, mixed $data)

Save a single field.

from  Fieldmanager_Context_Storable
save_walk_children(object $field, mixed $data)

Walk group children to save when serialize_data => false.

from  Fieldmanager_Context_Storable
mixed
load()

Handle loading data for any context.

from  Fieldmanager_Context_Storable
mixed
load_field(object $field)

Load a single field.

from  Fieldmanager_Context_Storable
mixed
load_walk_children(object $field)

Walk group children to load when serialize_data => false.

from  Fieldmanager_Context_Storable
static string|array
sanitize_scalar_value(mixed $value)

Meta and options are always stored as strings, so it's best to ensure that scalar values get cast as strings to ensure that update_metadata() and update_option() are able to correctly compare the current value against the previous value.

from  Fieldmanager_Context_Storable
string|array
get_data(int $term_id, string $meta_key, bool $single = false)

Callback to get term meta for the given term ID and current taxonomy.

bool|int
add_data(int $term_id, string $meta_key, string $meta_value, bool $unique = false)

Callback to add term meta for the given term ID and current taxonomy.

mixed
update_data(int $term_id, string $meta_key, string $meta_value, bool $meta_prev_value = '')

Callback to update term meta for the given term ID and current taxonomy.

bool
delete_data(int $term_id, string $meta_key, string $meta_value = '')

Callback to delete term meta for the given term ID and current taxonomy.

add_term_fields(string $taxonomy)

Creates the HTML template for wrapping fields on the add term form and prints the field.

edit_term_fields(WP_Term $term, string $taxonomy)

Creates the HTML template for wrapping fields on the edit term form and prints the field.

string
term_fields(string $html_template, string $taxonomy, WP_Term $term = null)

Generates HTML for the term field.

save_term_fields(int $term_id, int $tt_id, string $taxonomy)

Saves custom term fields.

array
verify_term_data_on_insert(array $data, string $taxonomy, array $args)

Verify that the term being inserted is the term that Fieldmanager data should be added to.

save_to_term_meta(int $term_id, string $taxonomy, array $data = null)

Helper to save an array of data to term meta.

delete_term_fields(int $term_id, int $tt_id, string $taxonomy, WP_term $deleted_term) deprecated

Saves custom fields for the sport taxonomy.

Details

at line 126
__construct(array|string $args, string|array $taxonomies = array(), bool $show_on_add = true, bool $show_on_edit = true, string $parent = '', Fieldmanager_Field $fm = null)

Instantiate this context. You can either pass an array of all args (preferred), or pass them individually (deprecated).

Parameters

array|string $args

{ Array of arguments.

If a string (deprecated), this will be used as the $title.

@type string $title The context/meta box title.
@type string|array $taxonomies The taxonomy/taxonomies to which to
                               add this field.
@type bool $show_on_add Optional. Should this field show on the "Add
                        Term" screen? Defaults to yes (true).
@type bool $show_on_edit Optional. Should this field show on the
                         "Edit Term" screen? Defaults to yes (true).
@type int $parent Optional. Should this field only show if its parent
                  matches this term ID?
@type bool $use_fm_meta Optional. Should this context store its data
                        using FM term meta (true, deprecated) or
                        WordPress core term meta (false). Defaults to
                        false.
@type Fieldmanager_Field $field Optional. The field to which to
                                attach this context.

}
string|array $taxonomies

Optional. Deprecated. Required if $args is a string.
bool $show_on_add

Optional. Deprecated.
bool $show_on_edit

Optional. Deprecated.
string $parent

Optional. Deprecated.
Fieldmanager_Field $fm

Optional. Deprecated.

Exceptions

FM_Developer_Exception

in Fieldmanager_Context at line 50
protected string nonce_key()

Get the nonce key for this field.

Return Value

string

in Fieldmanager_Context at line 62
array refresh_nonce(array $response)

Since: 1.3.0

Include a fresh nonce for this field in a response with refreshed nonces.

Parameters

array $response

Response data.

Return Value

array

Updated response data.

in Fieldmanager_Context at line 74
protected bool is_valid_nonce()

Check if the nonce is valid. Returns false if the nonce is missing and throws an exception if it's invalid. If all goes well, returns true.

Return Value

bool

in Fieldmanager_Context at line 95
protected mixed prepare_data(mixed $old_value = null, mixed $new_value = null, object $fm = null)

Prepare the data for saving.

Parameters

mixed $old_value

Optional. The previous value.
mixed $new_value

Optional. The new value for the field.
object $fm

Optional. The Fieldmanager_Field to prepare.

Return Value

mixed

The filtered and sanitized value, safe to save.

in Fieldmanager_Context_Storable at line 33
protected string render_field(array $args = array())

Render the field.

Parameters

array $args

{ Optional. Arguments to adjust the rendering behavior.

@type mixed $data The existing data to display with the field. If
                  absent, data will be loaded using
                  Fieldmanager_Context::_load().
@type boolean $echo Output if true, return if false. Default is true.

}

Return Value

string

if $args['echo'] == false.

in Fieldmanager_Context_Storable at line 46
protected save(mixed $data = null)

Handle saving data for any context.

Parameters

mixed $data

Data to save. Should be raw, e.g. POST data.

in Fieldmanager_Context_Storable at line 109
protected save_field(object $field, mixed $data)

Save a single field.

Parameters

object $field

Fieldmanager field.
mixed $data

Data to save.

Exceptions

FM_Developer_Exception

in Fieldmanager_Context_Storable at line 140
protected save_walk_children(object $field, mixed $data)

Walk group children to save when serialize_data => false.

Parameters

object $field

Fieldmanager field.
mixed $data

Data to save.

in Fieldmanager_Context_Storable at line 158
protected mixed load()

Handle loading data for any context.

Return Value

mixed

The loaded data.

in Fieldmanager_Context_Storable at line 172
protected mixed load_field(object $field)

Load a single field.

Parameters

object $field

The Fieldmanager field for which to load data.

Return Value

mixed

Data stored for that field in this context.

in Fieldmanager_Context_Storable at line 188
protected mixed load_walk_children(object $field)

Walk group children to load when serialize_data => false.

Parameters

object $field

Fieldmanager field for which to load data.

Return Value

mixed

Data stored for a singular field with serialized data, or array of data for a groups's children.

in Fieldmanager_Context_Storable at line 212
static string|array sanitize_scalar_value(mixed $value)

Since: 1.2.0

Meta and options are always stored as strings, so it's best to ensure that scalar values get cast as strings to ensure that update_metadata() and update_option() are able to correctly compare the current value against the previous value.

Parameters

mixed $value

Value being stored.

Return Value

string|array

If $value is scalar, a string is returned. Otherwise, $value returns untouched.

at line 439
protected string|array get_data(int $term_id, string $meta_key, bool $single = false)

Callback to get term meta for the given term ID and current taxonomy.

Parameters

int $term_id

The term ID.
string $meta_key

The meta key.
bool $single

Optional. If true, only returns the first value found for the given data_key. This won't apply to every context. Default is false.

Return Value

string|array

The stored data. If no data is found, should return an empty string (""). {\get_post_meta()}.

See also

get_term_meta().
Fieldmanager_Util_Term_Meta::get_term_meta (Deprecated).

at line 458
protected bool|int add_data(int $term_id, string $meta_key, string $meta_value, bool $unique = false)

Callback to add term meta for the given term ID and current taxonomy.

Parameters

int $term_id

The term ID.
string $meta_key

The meta key.
string $meta_value

The meta value.
bool $unique

Optional. If true, data will only be added if the object with the given $data_id doesn't already contain data for the given $data_key. This may not apply to every context. Default is false.

Return Value

bool|int

On success, should return the ID of the stored data (an integer, which will evaluate as true). If the $unique argument is set to true and data with the given key already exists, this should return false. {\add_post_meta()}.

See also

add_term_meta().
Fieldmanager_Util_Term_Meta::add_term_meta (Deprecated).

at line 477
protected mixed update_data(int $term_id, string $meta_key, string $meta_value, bool $meta_prev_value = '')

Callback to update term meta for the given term ID and current taxonomy.

Parameters

int $term_id

The term ID.
string $meta_key

The meta key.
string $meta_value

The meta value.
bool $meta_prev_value

The previous meta value.

Return Value

mixed

Should return data id if the data doesn't exist, otherwise should return true on success and false on failure. If the value passed to this method is the same as the stored value, this method should return false. {\update_post_meta()}.

See also

update_term_meta().
Fieldmanager_Util_Term_Meta::update_term_meta (Deprecated).

at line 496
protected bool delete_data(int $term_id, string $meta_key, string $meta_value = '')

Callback to delete term meta for the given term ID and current taxonomy.

Parameters

int $term_id

The term ID.
string $meta_key

The meta key.
string $meta_value

The meta value.

Return Value

bool

False for failure. True for success. {\delete_post_meta()}.

See also

delete_term_meta().
Fieldmanager_Util_Term_Meta::delete_term_meta (Deprecated).

at line 198
add_term_fields(string $taxonomy)

Creates the HTML template for wrapping fields on the add term form and prints the field.

Parameters

string $taxonomy

The taxonomy.

at line 224
edit_term_fields(WP_Term $term, string $taxonomy)

Creates the HTML template for wrapping fields on the edit term form and prints the field.

Parameters

WP_Term $term

The term to edit.
string $taxonomy

The taxonomy of the term.

at line 253
string term_fields(string $html_template, string $taxonomy, WP_Term $term = null)

Generates HTML for the term field.

Parameters

string $html_template

The HTML used to wrap the field.
string $taxonomy

The term taxonomy.
WP_Term $term

The term.

Return Value

string

The element markup

at line 300
save_term_fields(int $term_id, int $tt_id, string $taxonomy)

Saves custom term fields.

Parameters

int $term_id

The term ID.
int $tt_id

The term taxonomy ID.
string $taxonomy

The term taxonomy.

at line 378
array verify_term_data_on_insert(array $data, string $taxonomy, array $args)

Verify that the term being inserted is the term that Fieldmanager data should be added to.

This method serves to protect against a plugin or theme creating one or more additional terms as a side effect of a term created from the form. In order to protect against that, it's necessary to check the inserting term's [name, taxonomy, parent], as WordPress requires the combination of these fields to be unique. In order to guard against a plugin or theme changing this data, it is recorded immediately prior to the term being insert, and then checked in save_term_fields().

Parameters

array $data

{ Term data to be inserted.

@type string $name       Term name.
@type string $slug       Term slug.
@type int    $term_group Term group.

}
string $taxonomy

Taxonomy slug.
array $args

Arguments passed to wp_insert_term(), which is raw $_POST data.

Return Value

array

Unmodified $data.

at line 399
save_to_term_meta(int $term_id, string $taxonomy, array $data = null)

Helper to save an array of data to term meta.

Parameters

int $term_id

The term ID.
string $taxonomy

The term taxonomy.
array $data

The data to save.

at line 421
delete_term_fields(int $term_id, int $tt_id, string $taxonomy, WP_term $deleted_term) deprecated

deprecated Fieldmanager-1.0.0-beta.3 This is not necessary if you're using core's term meta.

Saves custom fields for the sport taxonomy.

Parameters

int $term_id

The term ID.
int $tt_id

The term taxonomy ID.
string $taxonomy

The term taxonomy.
WP_term $deleted_term

The deleted term.