Fieldmanager_Select
class Fieldmanager_Select extends Fieldmanager_Options (View source)
Select dropdown or multi-select field.
This class extends Fieldmanager_Options, which allows you to define options (values) via an array or via a dynamic Fieldmanager_Datasource}, like {@link Fieldmanager_Datasource_Post, Fieldmanager_Datasource_Term}, or {@link Fieldmanager_Datasource_User.
Properties
| static bool | $debug | If true, throw exceptions for illegal behavior. |
from Fieldmanager_Field |
| static bool | $enqueued_base_assets | Indicate that the base FM assets have been enqueued so we only do it once. |
from Fieldmanager_Field |
| int | $limit | How many of these fields to display, 0 for no limit. |
from Fieldmanager_Field |
| int deprecated | $starting_count | This is no longer used. |
from Fieldmanager_Field |
| 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. |
from Fieldmanager_Field |
| int | $extra_elements | How many empty fields to display if $limit != 1 when the total fields in the loaded data + $extra_elements > $minimum_count. |
from Fieldmanager_Field |
| string | $add_more_label | Text for add more button. |
from Fieldmanager_Field |
| string | $name | The name of the form element, as in 'foo' in |
from Fieldmanager_Field |
| string | $label | Label to use for form element. |
from Fieldmanager_Field |
| bool | $inline_label | If true, the label and the element will display on the same line. Some elements may not support this. |
from Fieldmanager_Field |
| bool | $label_after_element | If true, the label will be displayed after the element. |
from Fieldmanager_Field |
| string | $description | Description for the form element. |
from Fieldmanager_Field |
| bool | $description_after_element | If true, the description will be displayed after the element. |
from Fieldmanager_Field |
| 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. |
from Fieldmanager_Field |
| string | $field_class | Override $field_class. |
|
| bool | $one_label_per_item | Repeat the label for each element if $limit > 1. |
from Fieldmanager_Field |
| bool | $sortable | Allow draggable sorting if $limit > 1. |
from Fieldmanager_Field |
| string | $label_element | HTML element to use for label. |
from Fieldmanager_Field |
| callable | $sanitize | Function to use to sanitize input. |
from Fieldmanager_Field |
| array | $validate | Functions to use to validate input. |
from Fieldmanager_Field |
| string|array | $validation_rules | Validation rule(s) from jQuery used to validate this field, entered as a string or associative array. |
from Fieldmanager_Field |
| string|array | $validation_messages | Validation messages from jQuery used by the rule(s) defined for this field, entered as a string or associative array. |
from Fieldmanager_Field |
| bool | $required | Makes the field required on WordPress context forms that already have built-in validation. |
from Fieldmanager_Field |
| string | $data_type | Data type this element is used in, generally set internally. |
from Fieldmanager_Field |
| int | $data_id | ID for $this->data_type, eg $post->ID, generally set internally. |
from Fieldmanager_Field |
| Fieldmanager_Context | $current_context | Fieldmanager context handling data submitted with this field. Generally set internally. |
from Fieldmanager_Field |
| bool | $save_empty | If true, save empty elements to DB (if $this->limit != 1; single elements are always saved). |
from Fieldmanager_Field |
| bool | $skip_save | Do not save this field (useful for fields which handle saving their own data) |
from Fieldmanager_Field |
| bool | $index | Save this field additionally to an index. |
from Fieldmanager_Field |
| bool | $serialize_data | Save the fields to their own keys (only works in some contexts). Default is true. |
from Fieldmanager_Field |
| Fieldmanager_Datasource | $datasource | Optionally generate field from datasource. Used by Fieldmanager_Autocomplete and Fieldmanager_Options. |
from Fieldmanager_Field |
| array | $display_if | Field name and value on which to display element. Sample: |
from Fieldmanager_Field |
| string | $add_more_position | Where the new item should to added (top/bottom) of the stack. Used by Add Another button "top|bottom". |
from Fieldmanager_Field |
| bool | $remove_default_meta_boxes | If true, remove any default meta boxes that are overridden by Fieldmanager fields. |
from Fieldmanager_Field |
| string | $template | The path to the field template. |
from Fieldmanager_Field |
| 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. |
from Fieldmanager_Field |
| mixed | $default_value | The default value for the field, if unset. |
from Fieldmanager_Field |
| callable | $index_filter | Function that parses an index value and returns an optionally modified value. |
from Fieldmanager_Field |
| string | $input_type | Input type, mainly to support HTML5 input types. |
from Fieldmanager_Field |
| array | $escape | Custom escaping for labels, descriptions, etc. Associative array of $field => $callable arguments, for example: |
from Fieldmanager_Field |
| protected int | $seq | If $this->limit > 1, which element in sequence are we currently rendering? |
from Fieldmanager_Field |
| protected bool | $is_proto | If $is_proto is true, we're rendering the prototype element for a field that can have infinite instances. |
from Fieldmanager_Field |
| protected Fieldmanager_Field | $parent | Parent element, if applicable. Would be a Fieldmanager_Group unless third-party plugins support this. |
from Fieldmanager_Field |
| protected bool | $is_tab | Render this element in a tab? |
from Fieldmanager_Field |
| bool | $is_attachment | Whether or not this field is present on the attachment edit screen. |
from Fieldmanager_Field |
| array | $data | Full option data, allows grouping. |
from Fieldmanager_Options |
| array | $options | Shortcut to data which allows a simple associative array. |
from Fieldmanager_Options |
| bool | $grouped | Is the data grouped? E.g. should we use |
from Fieldmanager_Options |
| array | $first_element | Always prepend this element to the $data. |
from Fieldmanager_Options |
| bool | $multiple | Tell FM to save multiple values. |
|
| string | $options_template | Path to an options template to load. |
from Fieldmanager_Options |
| bool | $type_ahead | Should we support type-ahead? i.e. use chosen.js or not. |
|
| bool | $first_empty | Send an empty element first. |
Methods
Form element.
Override constructor to add chosen.js maybe.
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).
Is this element repeatable or does it have a repeatable ancestor?
Override presave_all to handle special cases associated with multiple options fields.
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.
Presave hook to set taxonomy data, maybe.
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.
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 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 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 get the list of default meta boxes to remove.
Escape a field based on the function in the escape argument.
Sanitize function that can handle arrays as well as string values.
Single data element (
Helper for output functions to toggle a selected options.
Add option data to the data attribute of this object.
Start an
End an
Init chosen.js.
Details
string
form_element(mixed $value = array())
Form element.
__construct(string|array $label = '', array $options = array())
Override constructor to add chosen.js maybe.
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)
Override presave_all to handle special cases associated with multiple options fields.
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.
array
presave_alter_values(array $values, array $current_values = array())
Presave hook to set taxonomy data, maybe.
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 get the list of default meta boxes to remove.
If $remove_default_meta_boxes is true and the datasource is Fieldmanager_Datasource_Term, this will return a list of all default meta boxes for the specified taxonomies. We only need to return id and context since the page will be handled by the list of post types provided to add_meta_box. Otherwise, this will just return an empty array.
string
escape(string $field, string $default = 'esc_html')
Escape a field based on the function in the escape argument.
array|string
sanitize(array|string $value)
Sanitize function that can handle arrays as well as string values.
add_options(array $options)
Add options.
string
form_data_elements(mixed $value)
Generate form elements.
string
form_data_element(mixed $data_row, mixed $value = array())
Single data element (
string
option_selected(string $current_option, array $options, string $attribute)
Helper for output functions to toggle a selected options.
protected
add_option_data(string $name, mixed $value, string $group = null, string|int $group_id = null)
Add option data to the data attribute of this object.
string
form_data_start_group(string $label)
Start an
string
form_data_end_group()
End an
chosen_init()
Init chosen.js.