-
Notifications
You must be signed in to change notification settings - Fork 6
Fields Configuration
Fields Array have a number of options that can be configured. All Fields arrays are sub arrays of main config array under its fields
array element.
All options of field array will look something like this:
array(
'id' => 'my_field_unique_id', // string unique
'label' => __( 'My Field Label', 'plugin-name' ), // Text
'desc' => __( 'Some description', 'plugin-name' ), // Text
'type' => '', // string like: 'select', 'radio' , 'media'
'placeholder' => '', // string | Text
'default' => '', // string | array
'options' => array(), // array
'callback' => '', // string | array
'sanitize_callback' => '', // string | array
'show_in_rest' => true, // true | false
'class' => 'my_custom_css_class', // css classes
'size' => 'regular', // 'small' | 'regular' | 'large'
);
At minimum, You need to define two elements: id
and label
. fields array will look like this:
array(
'id' => 'my_text_field_id',
'label' => __( 'My Text Field', 'plugin-name' ),
),
This will create a text field in settings page.
Lets Discuss these parameters one-by-one:
id
should be unique string for the fields config array. This id
parameter is used as key to store the options settings in WordPress options table and can be accessed like this:
get_option( 'my_text_field_id' );
if the main config array has prefix
defined (for instance its bsh_
, then options can be fetched from DB using the function:
get_option( 'bshmy_text_field_id' );
Note: There will be no change in the fields array, only change with the prfix is how the setting are stored in WordPress options table and how we can retrieve them.
label
is used as the field label on the Settings page.
- it should be Text that represent the settings field.
- Too Long and funny character set labels should be avoided.
- Ideally it should have translatable text.
desc
parameter is used to provide necessary description of the field.
- Description or instructions for the field.
- Too Long and funny character set labels should be avoided.
- Ideally it should have translatable text.
Default: empty
type
is a string parameter used to define the type of parameter to render on settings page.
Available options are:
text
url
number
color
textarea
radio
select
checkbox
multicheck
media
file
-
posts
(WP posts and Custom Post Types) -
pages
(WP pages) password
html
Default:
text
placeholder
is parameter is used to generate the placeholder for the fields that support placeholder attribute.
- it should be string that can be used as placeholder.
- Too Long and funny character set placeholder should be avoided.
- Ideally it should have translatable text to allow internationalization.
- Supported fields are:
text
url
number
default
parameter is used to provide default value of the field. It is the default value that is returned while using get_option()
function.
Possibilities:
Fields | Type | Example | Explanation |
---|---|---|---|
text | string | 'My Default Value' | Any Text |
url | string | 'http://example.com' | should be URL |
number | number | 55 | number |
color | string | '#ff0000' | color code |
texarea | string | 'This is default para for textarea' | Any Text |
radio | string | 'radio_2' | One of the element of options array |
select | string | 'select_3' | One of the element of options array |
file | string | 'http://example.com/my-image.jpg" | URL path to image or file |
media | number | 132 | id of the image in WordPress media gallery |
checkbox | bool | true | true value for checked, false for uncheck |
multicheck | array | array('check_1','check_2') | Sub array of options array for the field |
options
parameter array allow to configure different options for varying field types.
for instance,
options
array for select
or radio
field types will be the options for these field types. Like:
array(
//----
'type' => 'select',
'options' => array(
'option_1' => 'Option 1',
'option_2' => 'Option 2',
'option_3' => 'Option 3'
),
//----
),
alternatively, for media
field type, this options
array will be responsible for other parameter settings like:
array(
//----
'type' => 'media',
'options' => array(
'btn' => __( 'Get the image', 'plugin-name' ),
'width' => 150,
'max_width' => 150
)
//----
),
callback
parameter is intended for advance users as this parameter can be used to override the html render for a field and the value for this callback
parameter will be function name that will be used to render the field. Field parameters will be passed to this callback function as an array of parameters.
/* field array with callback function name defined */
array(
'id' => 'text_callback_field_id',
'label' => __( 'Field to Demonstrate Callback', 'plugin-name' ),
'callback' => 'plugin_name_my_callback_render_field'
)
/* Somewhere in the code,
this function is defined and it will
render the field in settings page */
function plugin_name_my_callback_render_field($args){
$html = sprintf(
'<input
class="regular-text"
type="%1$s"
name="%2$s"
value="%3$s"
placeholder="%4$s"
style="border: 3px solid red;"
/>',
$args['type'],
$args['name'],
$args['value'],
'Placeholder from callback'
);
$html .= '<br/><small>This field is generated with callback parameter</small>';
echo $html;
unset( $html );
}
sanitize_callback
parameter can be used to override the default sanitization of fields input. The value this sanitize_callback
parameter will be function name that will be used to sanitize the field. Field input will be passed as parameter to this function.
/* field array with sanitize_callback function name defined */
array(
'id' => 'text_field_custom_sanitize',
'label' => __( 'Field to Custom Sanitize', 'plugin-name' ),
'sanitize_callback' => 'abs_int'
);
// At the time of saving,
// input of this number field shall be sanitized
// using the function abs_int
show_in_rest
parametr is particularly important when settings page is using REST Api. It is useful in some cases.
Details available here
class
parameter is used to add additional CSS classes to fields for special styling.
Use
space
as separator for more than one class
class
parameter is primarily used for configuring the size of field.
Available Options are:
regular
| small
| large
Default:
regular
General
Configurations
Examples