PHP Class Fieldmanager_Field, vip-mu-plugins-public

Fields are UI elements that allow a person to interact with data.
ファイルを表示 Open project: Automattic/vip-mu-plugins-public Class Usage Examples

Public Properties

Property Type Description
$add_more_label string Text for add more button
$add_more_position string Where the new item should to added ( top/bottom ) of the stack. Used by Add Another button "top|bottom"
$attributes string | boolean[] Extra HTML attributes to apply to the form element. Use boolean true to apply a standalone attribute, e.g. 'required' => true
$data_id integer | null ID for $this->data_type, eg $post->ID, generally set internally
$data_type string | null Data type this element is used in, generally set internally
$datasource Fieldmanager_Datasource Optionally generate field from datasource. Used by Fieldmanager_Autocomplete and Fieldmanager_Options.
$debug boolean If true, throw exceptions for illegal behavior
$default_value Default value The default value for the field, if unset
$description string Description for the form element
$description_after_element boolean If true, the description will be displayed after the element.
$display_if array[] Field name and value on which to display element. Sample: $element->display_if = array( 'src' => 'display-if-src-element', 'value' => 'display-if-src-value' );
$escape array 'escape' => array( 'label' => 'wp_kses_post' )
$extra_elements integer How many empty fields to display if $limit != 1 when the total fields in the loaded data + $extra_elements > $minimum_count.
$field_class string CSS class for form element
$index boolean Save this field additionally to an index
$index_filter callable | null Function that parses an index value and returns an optionally modified value.
$inline_label boolean If true, the label and the element will display on the same line. Some elements may not support this.
$input_type string Input type, mainly to support HTML5 input types.
$is_attachment boolean Whether or not this field is present on the attachment edit screen
$label string Label to use for form element
$label_after_element boolean If true, the label will be displayed after the element.
$label_element string HTML element to use for label
$limit integer How many of these fields to display, 0 for no limit
$meta_boxes_to_remove array If $remove_default_meta_boxes is true, this array will be populated with the list of default meta boxes to remove
$minimum_count integer How many of these fields to display at a minimum, if $limit != 1. If $limit == $minimum_count, the "add another" button and the remove tool will be hidden.
$name string The name of the form element, As in 'foo' in
$one_label_per_item boolean Repeat the label for each element if $limit > 1
$remove_default_meta_boxes boolean If true, remove any default meta boxes that are overridden by Fieldmanager fields
$required boolean Makes the field required on WordPress context forms that already have built-in validation. This is necessary only for the fields used with the term add context.
$sanitize callback Function to use to sanitize input
$save_empty boolean If true, save empty elements to DB (if $this->limit != 1; single elements are always saved)
$serialize_data boolean Save the fields to their own keys (only works in some contexts). Default is true.
$skip_save boolean Do not save this field (useful for fields which handle saving their own data)
$sortable boolean Allow draggable sorting if $limit > 1
$starting_count integer DEPREATED: How many of these fields to display initially, if $limit != 1.
$template Template The path to the field template
$validate callback[] Functions to use to validate input
$validation_messages string | array jQuery validation messages used by the rule(s) defined for this field, entered as a string or associative array. These rules will be automatically converted to the appropriate Javascript format. Any messages without a corresponding rule will be ignored. For more information see http://jqueryvalidation.org/documentation/
$validation_rules string | array jQuery validation rule(s) used to validate this field, entered as a string or associative array. These rules will be automatically converted to the appropriate Javascript format. For more information see http://jqueryvalidation.org/documentation/

Protected Properties

Property Type Description
$is_proto boolean If $is_proto is true, we're rendering the prototype element for a field that can have infinite instances.
$is_tab boolean Render this element in a tab?
$parent Fieldmanager_Field Parent element, if applicable. Would be a Fieldmanager_Group unless third-party plugins support this.
$seq integer If $this->limit > 1, which element in sequence are we currently rendering?

Public Methods

Method Description
__construct ( string $label = '', array $options = [] ) Superclass constructor, just populates options and sanity-checks common elements.
_invalid_definition ( string $debug_message = '' ) : void Die violently. If self::$debug is true, throw an exception.
_unauthorized_access ( string $debug_message = '' ) : void Die violently. If self::$debug is true, throw an exception.
activate_submenu_page ( ) Activate this group in an already-added submenu page
add_another ( ) : string Generates HTML for the "Add Another" button.
add_meta_box ( string $title, $post_types, string $context = 'normal', string $priority = 'default' ) Add this field as a metabox to a post type
add_page_form ( string $uniqid ) Add a form on a frontend page
add_quickedit_box ( string $title, $post_types, callable $column_display_callback, string $column_title = '' ) Add this field to a post type's quick edit box.
add_submenu_page ( $parent_slug, $page_title, $menu_title = Null, $capability = 'manage_options', $menu_slug = Null ) Add this group to an options page
add_term_form ( string $title, string | array $taxonomies, boolean $show_on_add = true, boolean $show_on_edit = true, integer $parent = '' ) Add a form on a term add/edit page
add_term_meta_box ( string $title, string | array $taxonomies, boolean $show_on_add = true, boolean $show_on_edit = true, integer $parent = '' ) Add fields to the term add/edit page
add_user_form ( string $title = '' ) Add a form on user pages
element_markup ( array $values = [] ) : string Generates all markup needed for all form elements in this field.
escape ( string $field, string $default = 'esc_html' ) : string Escape a field based on the function in the escape argument.
form_element ( $value ) : string
get_collapse_handle ( ) : string Return HTML for the collapse handle (multi-tools); a separate function to override
get_element_attributes ( ) : string Generates an HTML attribute string based on the value of $this->attributes.
get_element_id ( ) : string Get the ID for the form element itself, uses $this->seq (e.g. which position is this element in).
get_element_key ( ) : string Get the storage key for the form element.
get_element_label ( array $classes = [] ) : string Get an HTML label for this element.
get_extra_element_classes ( ) : array Return extra element classes; overriden by some fields.
get_form_name ( $multiple = "" ) : string Get HTML form name (e.g. questions[answer]).
get_form_tree ( ) : array Recursively build path to this element (e.g. array(grandparent, parent, this) )
get_remove_handle ( ) : string Return HTML for the remove handle (multi-tools); a separate function to override
get_sort_handle ( ) : string Return HTML for the sort handle (multi-tools); a separate function to override
is_group ( ) : boolean Is the current field a group?
is_repeatable ( ) : boolean Is this element repeatable or does it have a repeatable ancestor?
preload_alter_values ( array $values ) Alter values before rendering
presave ( mixed $value, $current_value = [] ) : sanitized Presave function, which handles sanitization and validation
presave_all ( $values, $current_values ) : mixed[] Presaves all elements in what could be a set of them, dispatches to $this->presave()
set_options ( string $label, array $options ) Build options into properties and throw errors if developers add an unsupported opt.
single_element_markup ( mixed $value = Null, boolean $is_proto = False ) : string Generate wrappers and labels for one form element.
wrap_with_multi_tools ( string $html, $classes = [] ) : string Wrap a chunk of HTML with "remove" and "move" buttons if applicable.

Protected Methods

Method Description
_failed_validation ( $debug_message = '' ) : void Fail validation. If self::$debug is true, throw an exception.
add_meta_boxes_to_remove ( &$meta_boxes_to_remove ) : void Helper function to add to the list of meta boxes to remove. This will be defined in child classes that require this functionality.
get_seq ( ) : integer In a multiple element set, return the index of the current element we're rendering.
has_proto ( ) : boolean Are we in the middle of generating a prototype element for repeatable fields?
presave_alter_values ( array $values, $current_values = [] ) : array Hook to alter or respond to all the values of a particular element
process_index_value ( mixed $value ) : mixed Hook to alter handling of an individual index value, which may make sense to change per field type.
save_index ( array $values, $current_values ) : void Optionally save fields to a separate postmeta index for easy lookup with WP_Query Handles internal arrays (e.g. for fieldmanager-options).

Private Methods

Method Description
require_base ( )

Method Details

__construct() public method

It might also die, but only helpfully, to catch errors in development.
public __construct ( string $label = '', array $options = [] )
$label string title of form field
$options array with keys matching vars of the field in use.

_failed_validation() protected method

Fail validation. If self::$debug is true, throw an exception.
protected _failed_validation ( $debug_message = '' ) : void
return void

_invalid_definition() public method

Die violently. If self::$debug is true, throw an exception.
public _invalid_definition ( string $debug_message = '' ) : void
$debug_message string
return void e.g. return _you_ into a void.

_unauthorized_access() public method

Die violently. If self::$debug is true, throw an exception.
public _unauthorized_access ( string $debug_message = '' ) : void
$debug_message string
return void e.g. return _you_ into a void.

activate_submenu_page() public method

Activate this group in an already-added submenu page

add_another() public method

Generates HTML for the "Add Another" button.
public add_another ( ) : string
return string button HTML.

add_meta_box() public method

Add this field as a metabox to a post type
See also: Fieldmanager_Context_Post
public add_meta_box ( string $title, $post_types, string $context = 'normal', string $priority = 'default' )
$title string
$context string
$priority string

add_meta_boxes_to_remove() protected method

Helper function to add to the list of meta boxes to remove. This will be defined in child classes that require this functionality.
protected add_meta_boxes_to_remove ( &$meta_boxes_to_remove ) : void
return void

add_page_form() public method

Add a form on a frontend page
See also: Fieldmanager_Context_Form
public add_page_form ( string $uniqid )
$uniqid string a unique identifier for this form

add_quickedit_box() public method

Add this field to a post type's quick edit box.
See also: Fieldmanager_Context_Quickedit
public add_quickedit_box ( string $title, $post_types, callable $column_display_callback, string $column_title = '' )
$title string
$column_display_callback callable
$column_title string

add_submenu_page() public method

Add this group to an options page
public add_submenu_page ( $parent_slug, $page_title, $menu_title = Null, $capability = 'manage_options', $menu_slug = Null )

add_term_form() public method

Add a form on a term add/edit page
See also: Fieldmanager_Context_Term
Deprecation: 1.0.0-beta.3 Replaced by {@see \Fieldmanager_Field::add_term_meta_box()}.
public add_term_form ( string $title, string | array $taxonomies, boolean $show_on_add = true, boolean $show_on_edit = true, integer $parent = '' )
$title string
$taxonomies string | array The taxonomies on which to display this form
$show_on_add boolean Whether or not to show the fields on the add term form
$show_on_edit boolean Whether or not to show the fields on the edit term form
$parent integer Only show this field on child terms of this parent term ID

add_term_meta_box() public method

Add fields to the term add/edit page
See also: Fieldmanager_Context_Term
public add_term_meta_box ( string $title, string | array $taxonomies, boolean $show_on_add = true, boolean $show_on_edit = true, integer $parent = '' )
$title string
$taxonomies string | array The taxonomies on which to display this form
$show_on_add boolean Whether or not to show the fields on the add term form
$show_on_edit boolean Whether or not to show the fields on the edit term form
$parent integer Only show this field on child terms of this parent term ID

add_user_form() public method

Add a form on user pages
public add_user_form ( string $title = '' )
$title string

element_markup() public method

Could be called directly by a plugin or theme.
public element_markup ( array $values = [] ) : string
$values array the current values of this element, in a tree structure if the element has children.
return string HTML for all form elements.

escape() public method

Escape a field based on the function in the escape argument.
public escape ( string $field, string $default = 'esc_html' ) : string
$field string The field to escape.
$default string The default function to use to escape the field. Optional. Defaults to `esc_html()`
return string The escaped field.

form_element() public method

public form_element ( $value ) : string
return string HTML for the element. Generate HTML for the form element itself. Generally should be just one tag, no wrappers.

get_collapse_handle() public method

Return HTML for the collapse handle (multi-tools); a separate function to override
public get_collapse_handle ( ) : string
return string

get_element_attributes() public method

Generates an HTML attribute string based on the value of $this->attributes.
See also: Fieldmanager_Field::$attributes
public get_element_attributes ( ) : string
return string attributes ready to insert into an HTML tag.

get_element_id() public method

Relying on the element's ID for anything isn't a great idea since it can be rewritten in JS.
public get_element_id ( ) : string
return string ID for use in a form element.

get_element_key() public method

Get the storage key for the form element.
public get_element_key ( ) : string
return string

get_element_label() public method

Get an HTML label for this element.
public get_element_label ( array $classes = [] ) : string
$classes array extra CSS classes.
return string HTML label.

get_extra_element_classes() public method

Return extra element classes; overriden by some fields.
public get_extra_element_classes ( ) : array
return array

get_form_name() public method

Get HTML form name (e.g. questions[answer]).
public get_form_name ( $multiple = "" ) : string
return string form name

get_form_tree() public method

Recursively build path to this element (e.g. array(grandparent, parent, this) )
public get_form_tree ( ) : array
return array of parents

get_remove_handle() public method

Return HTML for the remove handle (multi-tools); a separate function to override
public get_remove_handle ( ) : string
return string

get_seq() protected method

In a multiple element set, return the index of the current element we're rendering.
protected get_seq ( ) : integer
return integer

get_sort_handle() public method

Return HTML for the sort handle (multi-tools); a separate function to override
public get_sort_handle ( ) : string
return string

has_proto() protected method

Are we in the middle of generating a prototype element for repeatable fields?
protected has_proto ( ) : boolean
return boolean

is_group() public method

Is the current field a group?
public is_group ( ) : boolean
return boolean True if yes, false if no.

is_repeatable() public method

Is this element repeatable or does it have a repeatable ancestor?
public is_repeatable ( ) : boolean
return boolean True if yes, false if no.

preload_alter_values() public method

Alter values before rendering
public preload_alter_values ( array $values )
$values array

presave() public method

Presave function, which handles sanitization and validation
public presave ( mixed $value, $current_value = [] ) : sanitized
$value mixed If a single field expects to manage an array, it must override presave()
return sanitized values.

presave_all() public method

Presaves all elements in what could be a set of them, dispatches to $this->presave()
public presave_all ( $values, $current_values ) : mixed[]
return mixed[] sanitized values

presave_alter_values() protected method

Hook to alter or respond to all the values of a particular element
protected presave_alter_values ( array $values, $current_values = [] ) : array
$values array
return array

process_index_value() protected method

Hook to alter handling of an individual index value, which may make sense to change per field type.
protected process_index_value ( mixed $value ) : mixed
$value mixed
return mixed

save_index() protected method

Is called multiple times for multi-fields (e.g. limit => 0)
protected save_index ( array $values, $current_values ) : void
$values array
return void

set_options() public method

Build options into properties and throw errors if developers add an unsupported opt.
public set_options ( string $label, array $options )
$label string title of form field
$options array with keys matching vars of the field in use.

single_element_markup() public method

Is called by element_markup(), calls form_element().
See also: Fieldmanager_Field::element_markup()
See also: Fieldmanager_Field::form_element()
public single_element_markup ( mixed $value = Null, boolean $is_proto = False ) : string
$value mixed the current value of this element.
$is_proto boolean true to generate a prototype element for Javascript.
return string HTML for a single form element.

wrap_with_multi_tools() public method

Wrap a chunk of HTML with "remove" and "move" buttons if applicable.
public wrap_with_multi_tools ( string $html, $classes = [] ) : string
$html string HTML to wrap.
return string wrapped HTML.

Property Details

$add_more_label public_oe property

Text for add more button
public string $add_more_label
return string

$add_more_position public_oe property

Where the new item should to added ( top/bottom ) of the stack. Used by Add Another button "top|bottom"
public string $add_more_position
return string

$attributes public_oe property

Extra HTML attributes to apply to the form element. Use boolean true to apply a standalone attribute, e.g. 'required' => true
public string|boolean[] $attributes
return string | boolean[]

$data_id public_oe property

ID for $this->data_type, eg $post->ID, generally set internally
public int|null $data_id
return integer | null

$data_type public_oe property

Data type this element is used in, generally set internally
public string|null $data_type
return string | null

$datasource public_oe property

Optionally generate field from datasource. Used by Fieldmanager_Autocomplete and Fieldmanager_Options.
public Fieldmanager_Datasource $datasource
return Fieldmanager_Datasource

$debug public_oe static_oe property

If true, throw exceptions for illegal behavior
public static bool $debug
return boolean

$default_value public_oe property

Default value The default value for the field, if unset
public $default_value

$description public_oe property

Description for the form element
public string $description
return string

$description_after_element public_oe property

If true, the description will be displayed after the element.
public bool $description_after_element
return boolean

$display_if public_oe property

Field name and value on which to display element. Sample: $element->display_if = array( 'src' => 'display-if-src-element', 'value' => 'display-if-src-value' );
public array[] $display_if
return array[]

$escape public_oe property

'escape' => array( 'label' => 'wp_kses_post' )
public array $escape
return array

$extra_elements public_oe property

How many empty fields to display if $limit != 1 when the total fields in the loaded data + $extra_elements > $minimum_count.
public int $extra_elements
return integer

$field_class public_oe property

CSS class for form element
public string $field_class
return string

$index public_oe property

Save this field additionally to an index
public bool $index
return boolean

$index_filter public_oe property

Function that parses an index value and returns an optionally modified value.
public callable|null $index_filter
return callable | null

$inline_label public_oe property

If true, the label and the element will display on the same line. Some elements may not support this.
public bool $inline_label
return boolean

$input_type public_oe property

Input type, mainly to support HTML5 input types.
public string $input_type
return string

$is_attachment public_oe property

Whether or not this field is present on the attachment edit screen
public bool $is_attachment
return boolean

$is_proto protected_oe property

If $is_proto is true, we're rendering the prototype element for a field that can have infinite instances.
protected bool $is_proto
return boolean

$is_tab protected_oe property

Render this element in a tab?
protected bool $is_tab
return boolean

$label public_oe property

Label to use for form element
public string $label
return string

$label_after_element public_oe property

If true, the label will be displayed after the element.
public bool $label_after_element
return boolean

$label_element public_oe property

HTML element to use for label
public string $label_element
return string

$limit public_oe property

How many of these fields to display, 0 for no limit
public int $limit
return integer

$meta_boxes_to_remove public_oe property

If $remove_default_meta_boxes is true, this array will be populated with the list of default meta boxes to remove
public array $meta_boxes_to_remove
return array

$minimum_count public_oe property

How many of these fields to display at a minimum, if $limit != 1. If $limit == $minimum_count, the "add another" button and the remove tool will be hidden.
public int $minimum_count
return integer

$name public_oe property

The name of the form element, As in 'foo' in
public string $name
return string

$one_label_per_item public_oe property

Repeat the label for each element if $limit > 1
public bool $one_label_per_item
return boolean

$parent protected_oe property

Parent element, if applicable. Would be a Fieldmanager_Group unless third-party plugins support this.
protected Fieldmanager_Field $parent
return Fieldmanager_Field

$remove_default_meta_boxes public_oe property

If true, remove any default meta boxes that are overridden by Fieldmanager fields
public bool $remove_default_meta_boxes
return boolean

$required public_oe property

Makes the field required on WordPress context forms that already have built-in validation. This is necessary only for the fields used with the term add context.
public bool $required
return boolean

$sanitize public_oe property

Function to use to sanitize input
public callback $sanitize
return callback

$save_empty public_oe property

If true, save empty elements to DB (if $this->limit != 1; single elements are always saved)
public bool $save_empty
return boolean

$seq protected_oe property

If $this->limit > 1, which element in sequence are we currently rendering?
protected int $seq
return integer

$serialize_data public_oe property

Save the fields to their own keys (only works in some contexts). Default is true.
public bool $serialize_data
return boolean

$skip_save public_oe property

Do not save this field (useful for fields which handle saving their own data)
public bool $skip_save
return boolean

$sortable public_oe property

Allow draggable sorting if $limit > 1
public bool $sortable
return boolean

$starting_count public_oe property

DEPREATED: How many of these fields to display initially, if $limit != 1.
Deprecation: This argument will have no impact. It only remains to avoid throwing exceptions in code that used it previously.
public int $starting_count
return integer

$template public_oe property

Template The path to the field template
public $template

$validate public_oe property

Functions to use to validate input
public callback[] $validate
return callback[]

$validation_messages public_oe property

jQuery validation messages used by the rule(s) defined for this field, entered as a string or associative array. These rules will be automatically converted to the appropriate Javascript format. Any messages without a corresponding rule will be ignored. For more information see http://jqueryvalidation.org/documentation/
public string|array $validation_messages
return string | array

$validation_rules public_oe property

jQuery validation rule(s) used to validate this field, entered as a string or associative array. These rules will be automatically converted to the appropriate Javascript format. For more information see http://jqueryvalidation.org/documentation/
public string|array $validation_rules
return string | array