bookmark_borderSettings API

Introduction

The Add-on Framework includes a Settings API that can be used to create form and plugin settings pages. The API provides the mechanisms for rendering field UIs and saving values automatically. It supports standard field types like radio buttons, text boxes and checkboxes and also custom field types.

Settings pages are created with a nested array structure which contains the configuration for each of the settings. Helper functions can then be used to render custom settings while still leveraging the API to handle the values.

Section Properties

The Settings API expects an array of sections. Each section is configured with an array containing the following properties:

  • form_title string

    The section title.

  • description string

    The section description.

  • id string

    The value of the id attribute of the div element containing this section.

  • class string

    The value to be appended to the class attribute of the div element containing this section.

  • style string

    The value to be appended to the style attribute of the div element containing this section.

  • tooltip string

    The content to be included in the tooltip for this section.

  • tooltip_class string

    The tooltip class; the value to be appended to the class attribute of the element containing this sections tooltip.

  • dependency string|array

    See Dependency below.

  • fields array

    The section fields; see Field Properties below.

Section Example

This example will render two empty sections with titles and descriptions:

array(
    array(
        'title'       => 'This is the title for Section 1',
        'description' => 'This is a description of the purpose of Section 1',
        'fields'      => array()
    ),
    array(
        'title'       => 'This is the title for Section 2',
        'description' => 'This is a description of the purpose of Section 2',
        'fields'      => array()
    ),
);

The code above will render a Settings page for the Simple Add-On similar to this.
Settings API Sections Example

Dependency

Controls the display of a section or field based on whether a single field has particular values or is not empty. You may specify a field name, a function to run, or a field name with an array of values. When specifying only a field name, the field will be checked to make sure it is not empty.

Note: The dependency is only checked upon page load and does not fire with events. For instance, if your dependency is checking the value of a drop down, if that value is changed, the dependency is not checked again. To do this, you would need to force the page to submit so the dependency will be checked again upon page load.

Field name:

'dependency' => 'the_field_to_check',

Function to run:

'dependency' => array( $this, 'check_textfield_dependency' ),

Field name with an array of values:

'dependency' => array( 'field' => 'mytextfield_name', 'values' => array( 'test', 'test2' ) ),

Field Properties

Each field is configured with the following properties:

  • type string

    The setting field type. Possible values: text, textarea, hidden, checkbox, radio, select, select_custom, field_map, dynamic_field_map, field_select, checkbox_and_select, save or a custom type.

  • input_type string

    The value of the fields input type attribute (e.g. password). Applies to fields of type text.

  • name string

    The setting name. For feed based add-ons this will be used as key to the setting value in the feed meta array.

  • id string

    The value of the id attribute of the element containing this setting. If the id is not specified, then the value from the name property will be used instead.

  • label string

    The setting label.

  • required boolean

    Determines whether the field is required to be filled out or not. Use true or false. The indicator for a required field will be displayed next to the label.

  • class string

    The value of the class attribute for the field input

    Note: There are three useful Gravity Forms’ classes named “small”, “medium”, and “large” which you may use to control the size of the field generated.

  • tooltip string

    The content to be included in the tooltip for this setting.

  • tooltip_class string

    The tooltip class; the value to be appended to the class attribute of the element containing this settings tooltip.

  • hidden boolean

    Controls the display of the field. If set to true, the html is still created but the field is not visible. The style “display:none” is applied. This functions similarly to the field type of “hidden”. The main difference is that when using the field type of hidden, a hidden text box is generated (<input type=”hidden”>). With this property, you can hide any field type.

  • default_value string

    The default value for the field. Does not apply to the checkbox field.

    For fields of type radio or select, if a default_value is specified for the field and a matching value is found for a choice, the radio button/drop down item will be selected. If the choice does not have a value specified, but does have a label, the label will be used to find a match.

  • horizontal boolean

    When set to true, the checkboxes or radio buttons will be displayed side-by-side instead of one per line. Applies to fields of type checkbox or radio only.

  • dependency string|array

    See Dependency above.

  • choices array

    An array of choices. Required for radio, checkbox and select field types. See Choices below.

  • feedback_callback string|array

    For text fields only. The function containing the feedback logic e.g. array( $this, ‘is_valid_setting’ ).

    The feedback callback function should return true or false and will determine which feedback indicator will be displayed in the UI. At present, the indicator is either a check icon for true or an x icon for false. This display is purely informative and does not prevent the settings from being saved. Check out the API key settings in the MailChimp Add-On for an example.

  • callback array

    Allows you to specify a different function used to create the field html instead of the function associated with the field type. This is the same as if you implemented a custom field type. e.g. array( $this, ‘my_replacement_function_for_displaying_field’ )

  • validation_callback string|array

    The function containing the custom validation logic e.g. array( $this, ‘is_valid_setting’ ).

  • after_input string

    The content which is to be appended after the text field.

  • field_map array

    An array of child fields, such as those used by a third-party service, which the user would map to their form fields. Used by the field_map and dynamic_field_map field types. Each child field is configured using the Field Properties.

Additional properties

HTML attributes may also be specified as field properties to be rendered with the HTML. Especially useful are events, such as onclick and onchange. These field properties will be handled as strings.

This example adds an onchange event to the select field which will call a javascript function named “SelectChanged” when the user selects a different choice from the drop down.

array(
    'title'       => 'This is the title for Section 1',
    'description' => 'This is a description of the purpose of Section 1',
    'fields'      => array(
                         array(
                             'type'     => 'select',
                             'name'     => 'myselect',
                             'label'    => 'This is a select',
                             'onchange' => 'SelectChanged()',
                             'choices'	=> array(
                                               array(
                                                   'label' => 'my first choice',
                                                   'value' => '1'
                                               ),
                                               array(
                                                   'label' => 'my second choice',
                                                   'value' => '2'
                                               )
                                           )
                         ),
                     )
),
?>
<script language="javascript">
    function SelectChanged(){
      alert("this is a test using js");
    }
</script>

This example has a text box which includes the HTML event attribute “onfocus”, a checkbox using the HTML event attribute “onclick”, and a textarea with the HTML attribute “disabled”.

array(
    'title'       => 'HTML Attributes Tests',
    'description' => 'This is a section with fields that also have html attributes added as properties.',
    'fields'      => array(
                         array(
                             'type'    => 'text',
                             'label'   => 'Text Box with onfocus',
                             'onfocus' => 'alert("The text box has received focus.");',
                         ),
                         array(
                             'type'    => 'checkbox',
                             'label'   => 'Check box with onclick',
                             'onclick' => 'alert("You have clicked on the check box named " + this.name);',
                             'choices' => array(
                                              array(
                                                  'label' => 'One',
                                                  'name'  => 'one',
                                                  'value' => 1,
                                              ),
                                              array(
                                                  'label' => 'Two',
                                                  'name'  => 'two',
                                                  'value' => 2,
                                              ),
                                          ),
                         ),
                         array(
                             'type'     => 'textarea',
                             'label'    => 'Textarea disabled',
                             'disabled' => true,
                         ),
                     ),
),

Choice Properties

Each choice is configured with the following properties:

  • label string

    The choice label. Required.

  • name string

    Only used for checkboxes. The name/key of the setting. Note: This is also used as the id attribute for the containing div tag.

  • value string

    Only used for radio buttons and select. If omitted, then the label will be used as the value.

  • default_value boolean

    Only used for checkboxes. The default value for the choice. This may be set to 1 or 0 with 1 marking the checkbox as checked. Note: The “default_value” property may be set for the radio buttons and select in the field property array, not the choice array.

  • tooltip string

    The content to be included in the tooltip for this choice. Only used for checkboxes and radio buttons.

  • tooltip_class string

    The tooltip class; the value to be appended to the class attribute of the element containing this choices tooltip. Only used for checkboxes and radio buttons.

  • icon string

    Icon can be an image URL or Font Awesome icon class. Only used for checkboxes and radio buttons.

  • choices array

    An array of choices for this optgroup. See above for the individual choice properties.

Field Type Examples

See the following pages for implementation examples of the various field types.