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' 
);

Required Configurations

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

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

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

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

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

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

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

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

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

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

show_in_rest parametr is particularly important when settings page is using REST Api. It is useful in some cases. Details available here

class

class parameter is used to add additional CSS classes to fields for special styling.

Use space as separator for more than one class

size

class parameter is primarily used for configuring the size of field.

Available Options are:

regular | small | large

Default: regular