public
|
#
addSettingSections( array|string $aSection1, array $aSection2 = null, array $_and_more = null )
Adds sections.
It inserts the given section definition arrays into the class property and
later they are parsed when sections are registered. The section definition array
have required keys. Refer to the parameter section of this method.
Example
$this->addSettingSections(
array(
'section_id' => 'text_fields',
'title' => __( 'Text Fields', 'your-text-domain' ),
'description' => __( 'These are text type fields.', 'your-text-domain' ),
),
array(
'section_id' => 'selectors',
'title' => __( 'Selectors', 'your-text-domain' ),
'description' => __( 'These are selector type options such as dropdown lists, radio buttons, and checkboxes', 'your-text-domain' ),
)
);
Example
$this->addSettingSections(
array(
'section_id' => 'text_fields',
'page_slug' => 'first_page',
'tab_slug' => 'textfields',
'title' => 'Text Fields',
'description' => 'These are text type fields.',
'order' => 10,
),
array(
'section_id' => 'selectors',
'page_slug' => 'first_page',
'tab_slug' => 'selectors',
'title' => 'Selectors',
'description' => 'These are selector type options such as dropdown lists, radio buttons, and checkboxes',
)
);
Parameters
- $aSection1
array|string the section array or the target page slug. If the target page slug is set, the
next section array can omit the page slug key.
Section Array
- section_id - (required, string) the section ID. Avoid using
non-alphabetic characters except underscore and numbers.
- page_slug - (optional, string) the page slug that the
section belongs to. If the target page slug is set, it can be omitted.
- tab_slug - (optional, string) the tab slug that the section
belongs to. The tab here refers to in-page tabs.
- section_tab_slug - (optional, string) [3.0.0+] the section
tab slug that the section are grouped into. The tab here refers to section
tabs.
- title - (optional, string) the title of the section.
- capability - (optional, string) the access level of the
section. If the page visitor does not have sufficient capability, the section
will be invisible to them.
- if - (optional, boolean) if the passed value is false, the
section will not be registered.
- order - (optional, integer) the order number of the
section. The higher the number is, the lower the position it gets.
- help - (optional, string) the help description added to the
contextual help tab.
- help_aside - (optional, string) the additional help
description for the side bar of the contextual help tab.
- repeatable - (optional, boolean|array) [3.0.0+] Indicates
whether or not the section is repeatable. To set a minimum/maximum number of
sections, pass an array with the key,
min , and max .
e.g. array( 'min' => 3, 'max' => 10 )
- $aSection2
array (optional) another section array.
- $_and_more
array (optional) add more section array to the next parameters as many as necessary.
Since
2.0.0
3.0.0 Changed the scope to public from protected.
Remark
Accepts variadic parameters; the number of accepted parameters are not limited
to three.
The actual registration will be performed in the
_replyToRegisterSettings() method with the admin_menu hook.
The target section tab slug and the target tab slug will be reset once the
method returns.
Overrides
|
public
|
#
addSettingFields( array $aField1, array $aField2 = null, array $_and_more = null )
Adds form fields.
It inserts the given field definition arrays into the class property and
later they are parsed when fields are registered. The field definition array
requires specific keys. Refer to the parameter section of this method.
Example
$this->addSettingFields(
array(
'field_id' => 'text',
'section_id' => 'text_fields',
'title' => __( 'Text', 'my-text-domain' ),
'description' => __( 'Type something here.', 'my-text-domain' ),
'type' => 'text',
'order' => 1,
'default' => 123456,
),
array(
'field_id' => 'text_multiple',
'section_id' => 'text_fields',
'title' => __( 'Multiple Text Fields', 'my-text-domain' ),
'description' => __( 'These are multiple text fields.', 'my-text-domain' ),
'type' => 'text',
'order' => 2,
'default' => __( 'Hello World', 'my-text-domain' ),
'label' => __( 'First Item', 'my-text-domain' ),
'attributes' => array(
'size' => 30
),
array(
'label' => __( 'Second Item', 'my-text-domain' ),
'default' => __( 'Foo bar', 'my-text-domain' ),
'attributes' => array(
'size' => 60,
),
),
array(
'label' => __( 'Third Item', 'my-text-domain' ),
'default' => __( 'Yes, we can.', 'my-text-domain' ),
'attributes' => array(
'size' => 90,
),
),
)
);
Parameters
- $aField1
array the field definition array.
Built-in Field Types
- text - a normal field to enter text input.
- password - a masked text input field.
- textarea - a text input field with multiple lines. It
supports rich text editor.
- radio - a set of radio buttons that lets the user pick an
option.
- checkbox - a check box that lets the user enable/disable an
item.
- select - a drop-down list that lest the user pick one or
more item(s) from a list.
- hidden - a hidden field that will be useful to insert
invisible values.
- file - a file uploader that lets the user upload
files.
- image - a custom text field with the image uploader script
that lets the user set the image URL.
- media - a custom text field with the media uploader script
that lets the user set the file URL.
- color - a custom text field with the color picker
script.
- submit - a submit button that lets the user send the
form.
- export - a custom submit field that lets the user export
the stored data.
- import - a custom combination field of the file and the
submit fields that let the user import data.
- posttype - a check-list of post types enabled on the
site.
- taxonomy - a set of check-lists of taxonomies enabled on
the site in a tabbed box.
- size - a combination field of the text and the select
fields that let the user set sizes with a selectable unit.
- section_title - [3.0.0+] a text field type that will be
placed in the section title so that it lets the user set the section title. Note
that only one field with this field type is allowed per a section.
- system - [3.3.0+] a custom textara field that displays the
system information including the PHP settings, the framework version, MySQL
version etc.
Field Definition Array
- field_id - ( required, string) the field ID. Avoid using
non-alphabetic characters except underscore and numbers.
- type - ( required, string) the type of the field. The
supported types are listed below.
- section_id - (optional, string) the section ID that the
field belongs to. If not set, the internal
_default section ID will
be assigned.
- title - (optional, string) the title of the section.
- description - (optional, string) the description of the
field which is inserted into the after the input field tag.
- tip - (optional, string) the tip for the field which is
displayed when the mouse is hovered over the field title.
- capability - (optional, string) the access level of the
section. If the page visitor does not have sufficient capability, the section
will be invisible to them.
- error_message - (optional, string) the error message to
display above the input field.
- before_field - (optional, string) the HTML string to insert
before the input field output.
- after_field - (optional, string) the HTML string to insert
after the input field output.
- if - (optional, boolean) if the passed value is false, the
section will not be registered.
- order - (optional, integer) the order number of the
section. The higher the number is, the lower the position it gets.
- label - (optional, string) the text label(s) associated
with and displayed along with the input field. Some input types can ignore this
key.
- default - (optional, string|array) the default value(s)
assigned to the input tag's value attribute.
- value - (optional, string|array) the value(s) assigned to
the input tag's
value attribute to override the default and the
stored value.
- delimiter - (optional, string) the HTML string that
delimits multiple elements. This is available if the label key is
passed as array. It will be enclosed in inline-block elements so the passed HTML
string should not contain block elements.
- before_input - (optional, string) the HTML string inserted
right before the input tag. It will be enclosed in the
label tag so
the passed HTML string should not contain block elements.
- after_input - (optional, string) the HTML string inserted
right after the input tag. It will be enclosed in the
label tag so
the passed HTML string should not contain block elements.
- label_min_width - (optional, string) the inline style
property of the
min-width of the label tag for the field. If the
unit is not specified, 'px' is applied. Default: 120 . e.g.
100%
- help - (optional, string) the help description added to the
contextual help tab.
- help_aside - (optional, string) the additional help
description for the side bar of the contextual help tab.
- repeatable - [3.0.0+] (optional, array|boolean) whether the
fields should be repeatable. If it yields true, the plus and the minus buttons
appear next to each field that lets the user add/remove the fields. Optionally
an setting array can be passed.
Repeatable Fields Setting Array
- max - the allowed maximum number of fields to be
repeated.
- min - the allowed minimum number of fields to be
repeated.
- sortable - [3.0.0+] (optional, boolean) whether the fields
should be sortable. If it yields true, the fields will be enclosed in a
draggable box.
- attributes - [3.0.0+] (optional, array) holds key-value
pairs representing the attribute and its property. Note that some field types
have specific keys in the first dimensions. e.g.
array( 'class' =>
'my_custom_class_selector', 'style' => 'background-color:#777', 'size' =>
20, ) Every field holds the following nested attribute definition arrays.
- fieldrow - the
td tag element containing the
field output.
- fieldset - the
fieldset tag element containing
the field output.
- fields - the
div tag element containing the
sub-fields and the main field.
- field - the
div tag element containing each
field.
- show_title_column - [3.0.0+] (optional, boolean) If true,
the field title column will be omitted from the output.
- hidden - [3.0.0+] (optional, boolean) If true, the entire
field row output will be invisible with the inline style attribute of
style="display:none" .
Field Type Specific Arguments
Each field type uses specific array arguments.
- text - a text input field which allows the user to type
text.
- password - a password input field which allows the user to
type text.
- number, range - HTML5 input field types. Some browsers do
not support these.
- textarea - a textarea input field. The following array keys
are supported.
- rich - [2.1.2+] (optional, array) to make it a rich text
editor pass a non-empty value. It accept a setting array of the
_WP_Editors class defined in the core. For more information, see
the argument section of this page.
- radio - a radio button input field.
- checkbox - a check box input field.
- select_all_button - [3.3.0+] (optional, array) pass
true to enable the Select All button. To set a custom
label, set the text such as __( 'Check All', 'test-domain' ) .
Default: true .
- select_none_button - [3.3.0+] (optional, array) pass
true to enable the Select None button. To set a custom
label, set the text such as __( 'Check All', 'test-domain' ) .
Default: true .
- select - a drop-down input field.
- is_multiple - (optional, boolean) if this is set to true,
the
multiple attribute will be inserted into the field input tag,
which enables the multiple selections for the user.
- size - a size input field. This is a combination of number
and select fields.
- units - (optional, array) defines the units to show. e.g.
array( 'px' => 'px', '%' => '%', 'em' => 'em' ) Default:
array( 'px' => 'px', '%' => '%', 'em' => 'em', 'ex' => 'ex',
'in' => 'in', 'cm' => 'cm', 'mm' => 'mm', 'pt' => 'pt', 'pc' =>
'pc' )
- is_multiple - (optional, boolean) if this is set to true,
the
multiple attribute will be inserted into the field input tag,
which enables the multiple selections for the user.
- attributes - [3.0.0+] (optional, array) The attributes
array of this field type has four initial keys: size, unit, optgroup, and option
and they have a regular attribute array in each.
- hidden - a hidden input field.
- file - a file upload input field.
- submit - a submit button input field.
- href - (optional, string) the url(s) linked to the submit
button.
- redirect_url - (optional, string) the url(s) redirected to
after submitting the input form.
- reset - [2.1.2+] (optional, boolean) the option key to
delete. Set 1 for the entire option.
- email - [3.3.0+] (optional, array) Coming soon...
- to - (string|array) the email address to send the email to.
For multiple email addressed, set comma delimited items.
- subject - (string|array) the email title.
- message - (string|array) the email body text.
- attachments - (string|array) the file path.
- name - (string|array) the sender name.
- from - (string|array) the sender email.
- is_html - (boolean|array) indicates whether the message
should be sent as an html or plain text.
- import - an import input field. This is a custom file and
submit field.
- option_key - (optional, string) the option table key to
save the importing data.
- format - (optional, string) the import format. json, or
array is supported. Default: array
- is_merge - (optional, boolean) [2.0.5+] determines whether
the imported data should be merged with the existing options.
- export - an export input field. This is a custom submit
field.
- file_name - (optional, string) the file name to
download.
- format - (optional, string) the format type. array, json,
or text is supported. Default: array.
- data - (optional, string|array|object ) the data to
export.
- image - an image input field. This is a custom text field
with an attached JavaScript script.
- show_preview - (optional, boolean) if this is set to false,
the image preview will be disabled.
- attributes_to_store - [2.1.3+] (optional, array) the array
of the attribute names of the image to save. If this is set, the field will be
an array with the specified attributes. The supported attributes are, 'title',
'alt', 'width', 'height', 'caption', 'id', 'align', and 'link'. Note that for
external URLs, ID will not be captured. e.g.
'attributes_to_store' =>
array( 'id', 'caption', 'description' )
- allow_external_source - [2.1.3+] (optional, boolean)
whether external URL can be set via the uploader.
- attributes - [3.0.0+] (optional, array) The attributes
array of this field type has three keys: input, button, and preview and they
have a regular attribute array in each.
- media - [2.1.3+] a media input field. This is a custom text
field with an attached JavaScript script.
- attributes_to_store - [2.1.3+] (optional, array) the array
of the attribute names of the image to save. If this is set, the field will be
an array with the specified attributes. The supported attributes are, 'id',
'caption', and 'description'. Note that for external URLs, ID will not be
captured. e.g.
'attributes_to_store' => array( 'id', 'caption',
'description' )
- allow_external_source - [2.1.3+] (optional, boolean)
whether external URL can be set via the uploader.
- color - a color picker input field. This is a custom text
field with a JavaScript script.
- taxonomy - a taxonomy check list. This is a set of check
boxes listing a specified taxonomy. This does not accept to create multiple
fields by passing an array of labels.
- taxonomy_slugs - (optional, array) the taxonomy slug to
list.
- max_width - (optional, string) the inline style property
value of
max-width of this element. Include the unit such as px, %.
Default: 100%
- height - (optional, string) the inline style property value
of
height of this element. Include the unit such as px, %. Default:
250px
- select_all_button - [3.3.0+] (optional, array) pass
true to enable the Select All button. To set a custom
label, set the text such as __( 'Check All', 'test-domain' ) .
Default: true .
- select_none_button - [3.3.0+] (optional, array) pass
true to enable the Select None button. To set a custom
label, set the text such as __( 'Check All', 'test-domain' ) .
Default: true .
- label_no_term_found - [3.3.2+] (optional, string) The label
to display when no term is found. Default:
No Term Found .
- label_list_title - [3.3.2+] (optional, string) The heading
title string for a term list. Default:
'' . Insert an HTML custom
string right before the list starts.
- query - [3.3.2+] (optional, array) the query array to
search terms. For more details, see the argument of the get_terms()
function.
- child_of - (integer) The parent term ID. All the descendant terms such as
child's child term will be listed. default:
0
- parent - (integer) The direct parent term ID. Only the first level children
will be listed. default: ``
- orderby - (string) The type of how the term list should be ordered by.
Either
ID , term_id , or name can be
accepted. Default: name .
- order - (string) The order of the list.
ASC or
DESC . Default: ASC .
- hide_empty - (boolean) whether to show the terms with no post associated.
Default:
false .
- hierarchical - (boolean) whether to show the terms as a hierarchical tree.
Default:
true
- number - (integer) The maximum number of the terms to show. 0 for no limit.
Default:
0 .
- pad_counts - (boolean) whether to sum up the post counts with the child post
counts. Default:
false
- exclude - (string|array) Comma separated term IDs or an array to exclude
from the list. for example
1 will remove the 'Uncategorized'
category from the list.
- exclude_tree - (integer) For more details see get_terms()..
- include - (string|array) Comma separated term IDs to include in the
list.
- fields - (string) Default:
all . For more details see get_terms().
- slug - (string) Default: ``. For more details see get_terms().
- get - (string) Default ``. For more details see get_terms().
- name__like - (string) Default ``. For more details see get_terms().
- description__like - (string) Default ``. For more details see get_terms().
- offset - (integer) Default ``. For more details see get_terms().
- search - (string) The search keyword to get the term with. Default ``.
- cache_domain - (string) Default:
core . For more details see get_terms().
- queries - [3.3.2+] (optional, array) Allows to set a query
argument for each taxonomy. The array key must be the taxonomy slug and the
value is the query argument array.
Example
array(
'field_id' => 'taxonomy_custom_queries',
'title' => __( 'Custom Taxonomy Queries', 'admin-page-framework-demo' ),
'type' => 'taxonomy',
'description' =>
array(
__( 'With the query argument array, you can customize how the terms should be retrieved.', 'admin-page-framework-demo' ),
sprintf( __( 'For the structure and the array key specifications, refer to the parameter section of the get_term() function.', 'admin-page-framework-demo' ), 'http://codex.wordpress.org/Function_Reference/get_terms#Parameters' ),
),
// (required) Determines which taxonomies should be listed
'taxonomy_slugs' => $aTaxnomies = get_taxonomies( '', 'names' ),
// (optional) This defines the default query argument. For the structure and supported arguments, see http://codex.wordpress.org/Function_Reference/get_terms#Parameters
'query' => array(
'depth' => 2,
'orderby' => 'term_id', // accepts 'ID', 'term_id', or 'name'
'order' => 'DESC',
// 'exclude' => '1', // removes the 'Uncategorized' category.
// 'search' => 'PHP', // the search keyward
// 'parent' => 9, // only show terms whose direct parent ID is 9.
// 'child_of' => 8, // only show child terms of the term ID of 8.
),
// (optional) This allows to set a query argument for each taxonomy.
// Note that each element will be merged with the above default 'query' argument array.
// So unset keys here will be overridden by the default argument array above.
'queries' => array(
// taxonomy slug => query argument array
'category' => array(
'depth' => 2,
'orderby' => 'term_id',
'order' => 'DESC',
'exclude' => array( 1 ),
),
'post_tag' => array(
'orderby' => 'name',
'order' => 'ASC',
// 'include' => array( 4, ), // term ids
),
),
),
- posttype - a post-type check list. This is a set of check
boxes listing post type slugs.
- slugs_to_remove - (optional, array) the post type slugs not
to be listed. e.g.
array( 'revision', 'attachment', 'nav_menu_item'
)
- select_all_button - [3.3.0+] (optional, array) pass
true to enable the Select All button. To set a custom
label, set the text such as __( 'Check All', 'test-domain' ) .
Default: true .
- select_none_button - [3.3.0+] (optional, array) pass
true to enable the Select None button. To set a custom
label, set the text such as __( 'Check All', 'test-domain' ) .
Default: true .
- $aField2
array (optional) another field array.
- $_and_more
array (optional) add more field arrays to the next parameters as many as necessary.
Since
2.0.0
3.0.0 Changed the scope to public from protected.
Remark
Accepts variadic parameters; the number of accepted parameters are not limited
to three.
The actual registration will be performed in the
_replyToRegisterSettings() method with the admin_menu hook.
Overrides
|