Fieldmanager_Group
class Fieldmanager_Group extends Fieldmanager_Field (View source)
Define a groups of fields.
Groups shouldn't just be thought of as a top-level collection of fields (like a meta box). Groups can be infinitely nested, they can be used to create tabbed interfaces, and so on. Groups submit data as nested arrays.
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 | Override label element. |
|
| 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 | $children | Children elements of this group. Not much point in creating an empty group. |
|
| bool | $collapsible | If true, this group can be collapsed by clicking its header. |
|
| bool | $collapsed | If true, this group is collapsed by default. |
|
| bool|string | $tabbed | Use tabbed groups. Currently supports "horizontal" or "vertical". Default is false, which means that the group will not be tabbed. |
|
| int | $tab_limit | How many tabs, maximum? |
|
| bool | $persist_active_tab | Persist the active tab on the group between sessions. |
|
| array | $label_macro | Label macro is a more convenient shortcut to label_format and label_token. The first element of the two-element array is the title with a placeholder (%s), and the second element is simply the name of the child element to pull from, e.g.: |
|
| string | $label_format | If specified, $label_format combined with $label_token will override $label, but only if $(label).find(label_token).val() is not null. |
|
| string | $label_token | CSS selector to an element to get the token for the label format. |
|
| callable | $group_is_empty | Function that tells whether the group is empty or not. Gets an array of form values. |
|
| bool | $add_to_prefix | Should the group name be included in the meta key prefix for separate fields? Default is true. |
|
| protected bool | $child_count | Iterator value for how many children we have rendered. |
|
| bool | $has_unserialized_descendants | Flag that this field has some descendant with $serialize_data => false. |
Methods
Render the element, iterating over children and calling their form_element() functions.
Constructor; add CSS if we're looking at a tabbed view.
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.
Groups have their own drag and remove tools in the label.
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?
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 override for groups which dispatches to child presave_all methods.
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.
Maybe add the collapsible class for groups.
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.
Details
string
form_element(mixed $value = null)
Render the element, iterating over children and calling their form_element() functions.
__construct(string|array $label = '', array $options = array())
Constructor; add CSS if we're looking at a tabbed view.
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())
Groups have their own drag and remove tools in the label.
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 $values, mixed $current_values = array())
Presave override for groups which dispatches to child presave_all methods.
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()
Maybe add the collapsible class for groups.
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.
For Fieldmanager_Group, iterate over all children to see if they have meta boxes to remove. If $remove_default_meta_boxes is true for this group, set all children to also remove any default meta boxes if applicable.
string
escape(string $field, string $default = 'esc_html')
Escape a field based on the function in the escape argument.
add_child(Fieldmanager_Field $child)
Add a child element to this group.