Fieldmanager_Field
abstract class Fieldmanager_Field (View source)
Abstract base class containing core functionality for Fieldmanager fields.
Fields are UI elements that allow a person to interact with data.
Properties
| static bool | $debug | If true, throw exceptions for illegal behavior. |
|
| static bool | $enqueued_base_assets | Indicate that the base FM assets have been enqueued so we only do it once. |
|
| int | $limit | How many of these fields to display, 0 for no limit. |
|
| int deprecated | $starting_count | This is no longer used. |
|
| int | $minimum_count | 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. |
|
| int | $extra_elements | How many empty fields to display if $limit != 1 when the total fields in the loaded data + $extra_elements > $minimum_count. |
|
| string | $add_more_label | Text for add more button. |
|
| string | $name | The name of the form element, as in 'foo' in |
|
| string | $label | Label to use for form element. |
|
| bool | $inline_label | If true, the label and the element will display on the same line. Some elements may not support this. |
|
| bool | $label_after_element | If true, the label will be displayed after the element. |
|
| string | $description | Description for the form element. |
|
| bool | $description_after_element | If true, the description will be displayed after the element. |
|
| string|bool|array | $attributes | Extra HTML attributes to apply to the form element. Use boolean true to apply a standalone attribute, e.g. 'required' => true. |
|
| string | $field_class | CSS class for form element. |
|
| bool | $one_label_per_item | Repeat the label for each element if $limit > 1. |
|
| bool | $sortable | Allow draggable sorting if $limit > 1. |
|
| string | $label_element | HTML element to use for label. |
|
| callable | $sanitize | Function to use to sanitize input. |
|
| array | $validate | Functions to use to validate input. |
|
| string|array | $validation_rules | Validation rule(s) from jQuery used to validate this field, entered as a string or associative array. |
|
| string|array | $validation_messages | Validation messages from jQuery used by the rule(s) defined for this field, entered as a string or associative array. |
|
| bool | $required | Makes the field required on WordPress context forms that already have built-in validation. |
|
| string | $data_type | Data type this element is used in, generally set internally. |
|
| int | $data_id | ID for $this->data_type, eg $post->ID, generally set internally. |
|
| Fieldmanager_Context | $current_context | Fieldmanager context handling data submitted with this field. Generally set internally. |
|
| bool | $save_empty | If true, save empty elements to DB (if $this->limit != 1; single elements are always saved). |
|
| bool | $skip_save | Do not save this field (useful for fields which handle saving their own data) |
|
| bool | $index | Save this field additionally to an index. |
|
| bool | $serialize_data | Save the fields to their own keys (only works in some contexts). Default is true. |
|
| Fieldmanager_Datasource | $datasource | Optionally generate field from datasource. Used by Fieldmanager_Autocomplete and Fieldmanager_Options. |
|
| array | $display_if | Field name and value on which to display element. Sample: |
|
| string | $add_more_position | Where the new item should to added (top/bottom) of the stack. Used by Add Another button "top|bottom". |
|
| bool | $remove_default_meta_boxes | If true, remove any default meta boxes that are overridden by Fieldmanager fields. |
|
| string | $template | The path to the field template. |
|
| array | $meta_boxes_to_remove | If $remove_default_meta_boxes is true, this array will be populated with the list of default meta boxes to remove. |
|
| mixed | $default_value | The default value for the field, if unset. |
|
| callable | $index_filter | Function that parses an index value and returns an optionally modified value. |
|
| string | $input_type | Input type, mainly to support HTML5 input types. |
|
| array | $escape | Custom escaping for labels, descriptions, etc. Associative array of $field => $callable arguments, for example: |
|
| protected int | $seq | If $this->limit > 1, which element in sequence are we currently rendering? |
|
| protected bool | $is_proto | If $is_proto is true, we're rendering the prototype element for a field that can have infinite instances. |
|
| protected Fieldmanager_Field | $parent | Parent element, if applicable. Would be a Fieldmanager_Group unless third-party plugins support this. |
|
| protected bool | $is_tab | Render this element in a tab? |
|
| bool | $is_attachment | Whether or not this field is present on the attachment edit screen. |
Methods
Generate HTML for the form element itself. Generally should be just one tag, no wrappers.
Superclass constructor, just populates options and sanity-checks common elements.
Build options into properties and throw errors if developers add an unsupported opt.
Generates all markup needed for all form elements in this field.
Generate wrappers and labels for one form element. Is called by
element_markup(), calls form_element().
Alter values before rendering.
Wrap a chunk of HTML with "remove" and "move" buttons if applicable.
Get HTML form name (e.g. questions[answer]).
Recursively build path to this element, e.g. [grandparent, parent, this].
Get the ID for the form element itself, uses $this->seq (e.g. which position is this element in).
Get the storage key for the form element.
Is this element repeatable or does it have a repeatable ancestor?
Is the current field a group?
Presaves all elements in what could be a set of them, dispatches to $this->presave().
Optionally save fields to a separate postmeta index for easy lookup with WP_Query Handles internal arrays (e.g. for fieldmanager-options).
Hook to alter handling of an individual index value, which may make sense to change per field type.
Hook to alter or respond to all the values of a particular element.
Presave function, which handles sanitization and validation.
Generates an HTML attribute string based on the value of $this->attributes.
Get an HTML label for this element.
Generates HTML for the "Add Another" button.
Return HTML for the sort handle (multi-tools); a separate function to override.
Return HTML for the remove handle (multi-tools); a separate function to override.
Return HTML for the collapse handle (multi-tools); a separate function to override.
Return extra element classes; overridden by some fields.
Add a form on user pages.
Add a form on a frontend page.
Add a form on a term add/edit page
Add fields to the term add/edit page
Add this field as a metabox to a post type.
Add this field to a post type's quick edit box.
Add this group to an nav menu.
Add this group to an options page.
Activate this group in an already-added submenu page.
Die violently. If self::$debug is true, throw an exception.
Fail validation. If self::$debug is true, throw an exception.
Die violently. If self::$debug is true, throw an exception.
In a multiple element set, return the index of the current element we're rendering.
Are we in the middle of generating a prototype element for repeatable fields?
Helper function to add to the list of meta boxes to remove. This will be defined in child classes that require this functionality.
Escape a field based on the function in the escape argument.
Details
string
form_element(mixed $value)
Generate HTML for the form element itself. Generally should be just one tag, no wrappers.
__construct(string|array $label = '', array $options = array())
Superclass constructor, just populates options and sanity-checks common elements.
It might also die, but only helpfully, to catch errors in development.
set_options(string|array $label, array $options)
Build options into properties and throw errors if developers add an unsupported opt.
string
element_markup(mixed|array|null $values = array())
Generates all markup needed for all form elements in this field.
Could be called directly by a plugin or theme.
string
single_element_markup(mixed|array|null $value = null, bool $is_proto = false)
Generate wrappers and labels for one form element. Is called by
element_markup(), calls form_element().
mixed|array|null
preload_alter_values(mixed|array|null $values)
Alter values before rendering.
string
wrap_with_multi_tools(string $html, array $classes = array())
Wrap a chunk of HTML with "remove" and "move" buttons if applicable.
string
get_form_name(string $multiple = '')
Get HTML form name (e.g. questions[answer]).
array
get_form_tree()
Recursively build path to this element, e.g. [grandparent, parent, this].
string
get_element_id()
Get the ID for the form element itself, uses $this->seq (e.g. which position is this element in).
Relying on the element's ID for anything isn't a great idea since it can be rewritten in JS.
string
get_element_key()
Get the storage key for the form element.
bool
is_repeatable()
Is this element repeatable or does it have a repeatable ancestor?
bool
is_group()
Is the current field a group?
mixed
presave_all(mixed $values, mixed $current_values)
Presaves all elements in what could be a set of them, dispatches to $this->presave().
protected
save_index(array $values, array $current_values)
Optionally save fields to a separate postmeta index for easy lookup with WP_Query Handles internal arrays (e.g. for fieldmanager-options).
Is called multiple times for multi-fields (e.g. limit => 0).
protected mixed
process_index_value(mixed $value)
Hook to alter handling of an individual index value, which may make sense to change per field type.
protected array
presave_alter_values(array $values, array $current_values = array())
Hook to alter or respond to all the values of a particular element.
array
presave(mixed $value, array $current_value = array())
Presave function, which handles sanitization and validation.
string
get_element_attributes()
Generates an HTML attribute string based on the value of $this->attributes.
string
get_element_label(array $classes = array())
Get an HTML label for this element.
string
add_another()
Generates HTML for the "Add Another" button.
string
get_sort_handle()
Return HTML for the sort handle (multi-tools); a separate function to override.
string
get_remove_handle()
Return HTML for the remove handle (multi-tools); a separate function to override.
string
get_collapse_handle()
Return HTML for the collapse handle (multi-tools); a separate function to override.
array
get_extra_element_classes()
Return extra element classes; overridden by some fields.
add_user_form(string $title = '')
Add a form on user pages.
add_page_form(string $uniqid)
Add a form on a frontend page.
add_term_form(string $title, string|array $taxonomies, bool $show_on_add = true, bool $show_on_edit = true, int $parent = '')
deprecated
deprecated
Add a form on a term add/edit page
add_term_meta_box(string $title, string|array $taxonomies, bool $show_on_add = true, bool $show_on_edit = true, int $parent = '')
Add fields to the term add/edit page
add_meta_box(string $title, string|array $post_types, string $context = 'normal', string $priority = 'default')
Add this field as a metabox to a post type.
add_quickedit_box(string $title, string|array $post_types, callable $column_display_callback, string $column_title = '')
Add this field to a post type's quick edit box.
add_nav_menu_fields()
Add this group to an nav menu.
add_submenu_page(string $parent_slug, string $page_title, string $menu_title = null, string $capability = 'manage_options', string $menu_slug = null)
Add this group to an options page.
activate_submenu_page()
Activate this group in an already-added submenu page.
_unauthorized_access(string $debug_message = '')
Die violently. If self::$debug is true, throw an exception.
protected
_failed_validation(string $debug_message = '')
Fail validation. If self::$debug is true, throw an exception.
_invalid_definition(string $debug_message = '')
Die violently. If self::$debug is true, throw an exception.
protected int
get_seq()
In a multiple element set, return the index of the current element we're rendering.
protected bool
has_proto()
Are we in the middle of generating a prototype element for repeatable fields?
protected
add_meta_boxes_to_remove(array $meta_boxes_to_remove)
Helper function to add to the list of meta boxes to remove. This will be defined in child classes that require this functionality.
string
escape(string $field, string $default = 'esc_html')
Escape a field based on the function in the escape argument.