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.
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.
The section description.
The value of the id attribute of the div element containing this section.
The value to be appended to the class attribute of the div element containing this section.
The value to be appended to the style attribute of the div element containing this section.
The content to be included in the tooltip for this section.
The tooltip class; the value to be appended to the class attribute of the element containing this sections tooltip.
See Dependency below.
The section fields; see Field Properties below.
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() ), );
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.
'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' ) ),
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.
The value of the fields input type attribute (e.g. password). Applies to fields of type text.
The setting name. For feed based add-ons this will be used as key to the setting value in the feed meta array.
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.
The setting label.
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.
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.
The content to be included in the tooltip for this setting.
The tooltip class; the value to be appended to the class attribute of the element containing this settings tooltip.
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.
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.
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.
See Dependency above.
An array of choices. Required for radio, checkbox and select field types. See Choices below.
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.
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’ )
The function containing the custom validation logic e.g. array( $this, ‘is_valid_setting’ ).
The content which is to be appended after the text field.
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.
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 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, ), ), ),
Each choice is configured with the following properties:
- label string
The choice label. Required.
Only used for checkboxes. The name/key of the setting. Note: This is also used as the id attribute for the containing div tag.
Only used for radio buttons and select. If omitted, then the label will be used as the value.
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.
The content to be included in the tooltip for this choice. Only used for checkboxes and radio buttons.
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 can be an image URL or Font Awesome icon class. Only used for checkboxes and radio buttons.
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.
- text Field (‘type’ => ‘text’)
- textarea Field (‘type’ => ‘textarea’)
- hidden Field (‘type’ => ‘hidden’)
- radio Field (‘type’ => ‘radio’)
- checkbox Field (‘type’ => ‘checkbox’)
- select Field (‘type’ => ‘select’)
- select_custom Field (‘type’ => ‘select_custom’)
- field_map Field (‘type’ => ‘field_map’)
- field_select Field (‘type’ => ‘field_select’)
- dynamic_field_map Field (‘type’ => ‘dynamic_field_map’)
- checkbox_and_select Field (‘type’ => ‘checkbox_and_select’)
- Save Button (‘type’ => ‘save’)
- Custom Field Type