Skip to content

Settings Configuration Array

Jump to bottom
boospot edited this page May 19, 2019 · 4 revisions

General

Configurations

Examples

Clone this wiki locally

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 Configuration Array Elements

$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

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

tabs is optional parameter that defines whether to show sections as tabs or not.

Possible options are true or false

Default: false

menu

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

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

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

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.

Sample Configuration Array

$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,
	)
);