-
Notifications
You must be signed in to change notification settings - Fork 6
Settings Configuration Array
Settings configuration is the main configuration array that is responsible to create menu, sections, fields and tabs of the settings page.
Typically, it will look like this:
$settings_config_array = array(
'prefix' => 'plugin_prefix_', // string to prefix with options id (optional)
'tabs' => true, // true | false (optional) ( Default: true )
'menu' => array(), // array of menu configuration
'sections' => array(), // array of arrays configuring sections
'fields' => array(), // array of arrays configuring fields. array key same as sections
'links' => array() // configuration array for links (optional)
);
You may also see Sample Configuration Array with some filled in values.
this settings configuration array should be passed to the Settings Helper Class inside a callback function hooked into admin_menu
action hook.
Details of each configuration parameter is discussed as under:
prefix
is optional parameter and is used to prefix the option id that will be used to store option value in database.
for instance, in the fields
array, there is a field with id text_field_id
. to get its value, we can use the wordpress function get_option( $option_key )
.
Without Using 'prefix' parameter
Without using prefix
param, we can get the option value like this:
$field_value = get_option( 'text_field_id' );
Using 'prefix' parameter
When using prefix
as plugin_prefix_
, we can ge the field option value like this:
$field_value = get_option( 'plugin_prefix_text_field_id' ); // format is: pluginPrefix_fieldId
Prefix is particularly helpful to avoid naming conflict while saving plugin options in WordPress options table in database.
tabs
is optional parameter that defines whether to show sections as tabs or not.
Possible options are true
or false
Default: false
menu
parameter is an array to define menu for the plugin. Details can be found at the wiki page dedicated for menu configuration.
Typically, it will look like this:
$settings_config_array = array(
//---
'menu' => array(
'page_title' => __( 'Plugin Name Settings', 'plugin-name' ),
'menu_title' => __( 'Plugin Name', 'plugin-name' ),
'slug' => 'plugin-name',
'capability' => 'manage_options',
// for top level menu
'position' => 10,
'icon' => 'dashicons-performance',
// for sub level menu
'submenu' => true,
'parent' => 'options-general.php',
),
//---
);
sections
is a required parameter and is an array to define sections for the plugin settings page. Details can be found at the wiki page dedicated for sections configuration array.
Typically, it will look like this:
$settings_config_array = array(
//---
'sections' => array(
array(
'id' => 'general_section',
'title' => __( 'General Settings', 'plugin-name' ),
'desc' => __( 'Description of general section', 'plugin-name' ),
),
array(
'id' => 'advance_section',
'title' => __( 'Advanced Settings', 'plugin-name' ),
'desc' => __( 'Description of advanced section', 'plugin-name' )
)
),
//---
);
The above code will generate 2 sections. Each of these sections can now hold settings fields. It is a required parameter and you must at least have one section for this class to work properly.
Section can be converted into tabs using tabs parameter
fields
is a required parameter and is an array of array to add fields to sections already defined in the sections
parameter.
Details about this parameter can be found on wiki page dedicated for Fields Configuration.
child array element should have array key matching the section id
Typically, it will look like this:
$settings_config_array = array(
//---
'fields' => array(
'general_section' => array(
array(
'id' => 'text_field_id',
'label' => __( 'Text Field', 'plugin-name' ),
),
array(
'id' => 'color_field_id',
'label' => __( 'Color Field', 'plugin-name' ),
'type' => 'color',
),
),
'advance_section' => array(
array(
'id' => 'select_field_id',
'label' => __( 'A Dropdown Select', 'plugin-name' ),
'type' => 'select',
'default' => 'option_2',
'options' => array(
'option_1' => 'Option 1',
'option_2' => 'Option 2',
'option_3' => 'Option 3'
),
),
)
),
//---
);
The above code will add total three fields.
text
and color
field to the General Section that has the id general_section
.
select
field shall be added to Advance Section having id advance_section
that is defined in the sections
parameter of settings configuration array.
links
is an optional parameter that is used to generate plugin action links.
This parameter can generate three type of links:
- default : linking to plugin settings page
- internal: for internal plugin links
- external: for external plugin links
Simple links array will look like this:
$settings_config_array = array(
//---
'links' => array(
'plugin_basename' => plugin_basename( __FILE__ ),
// Simply passing tru will generate default settings link
'action_links' => true,
),
//---
);
Links array default, external and internal links look like this:
$settings_config_array = array(
//---
'links' => array(
'plugin_basename' => plugin_basename( __FILE__ ),
'action_links' => array(
array(
'type' => 'default',
'text' => __( 'Configure', 'plugin-name' ),
),
array(
'type' => 'internal',
'text' => __( 'Gravity Forms', 'plugin-name' ),
'url' => 'admin.php?page=gf_edit_forms',
),
array(
'type' => 'external',
'text' => __( 'Github Repo', 'plugin-name' ),
'url' => 'https://github.com/boospot/boo-settings-helper',
),
),
)
//---
);
The above code will create three plugin action links.
$settings_config_array = array(
'prefix' => 'plugin_prefix_',
'tabs' => true,
'menu' => array(
'page_title' => __( 'Plugin Name Settings', 'plugin-name' ),
'submenu' => true,
),
'sections' => array(
array(
'id' => 'general_section',
'title' => __( 'General Settings', 'plugin-name' ),
'desc' => __( 'Description of general section', 'plugin-name' ),
),
array(
'id' => 'advance_section',
'title' => __( 'Advanced Settings', 'plugin-name' ),
'desc' => __( 'Description of advanced section', 'plugin-name' )
)
),
'fields' => array(
// array key should be same as section id
'general_section' => array(
array(
'id' => 'text_field_id',
'label' => __( 'Text Field', 'plugin-name' ),
),
array(
'id' => 'color_field_id',
'label' => __( 'Color Field', 'plugin-name' ),
'type' => 'color',
),
),
'advance_section' => array(
array(
'id' => 'select_field_id',
'label' => __( 'A Dropdown Select', 'plugin-name' ),
'type' => 'select',
'default' => 'option_2',
'options' => array(
'option_1' => 'Option 1',
'option_2' => 'Option 2',
'option_3' => 'Option 3'
),
),
)
),
'links' => array(
'plugin_basename' => plugin_basename( __FILE__ ),
'action_links' => true,
)
);
General
Configurations
Examples