Settings 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.
Note: In order to use the Settings API, your class must extend one of the GFAddon Classes.
Creating a Plugin Settings Page
To create a plugin settings page, simply override the plugin_settings() function and return an array containing the sections and fields that should be added to the plugin settings page.
public function plugin_settings() {
return array(
array(
'title' => 'Title for Section 1',
'description' => 'Description for section 1',
'fields' => array(
'type' => 'text',
'name' => 'mytext',
'label' => 'This is a text input',
),
),
);
}
For more information about the array format and all supported properties, see Section Properties and Field Properties below.
Creating a Feed Settings Page
Add-ons that extend the GFFeedAddon Class have the ability to create settings pages for feeds. These are pages that allow users to add and edit feeds for the add-on. Similar to the plugin settings page above, to create a feed settings page, simply override the feed_settings_fields() function of the GFFeedAddon Class.
public function feed_settings_fields() {
return array(
array(
'title' => 'Title for Section 1',
'description' => 'Description for section 1',
'fields' => array(
'type' => 'text',
'name' => 'mytext',
'label' => 'This is a text input',
),
),
);
}
For more information about the array format and all supported properties, see Section Properties and Field Properties below.
Section Properties
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.
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
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 (). 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/dropdown 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.
allow_html boolean For Textarea fields only, if set to true, HTML in the textarea won't be all stripped, it uses wp_kses() with the post context instead of sanitize_text_field(), so any HTML allowed in a post, will be allowed in the textarea, if the property doesn't exist or is set to false, all HTML tags will be stripped, and other things sanitize_text_field() does that you can check here.
use_editor boolean For Textarea fields only, when set to true, it initialize as Rich Text Editor. HTML will be handled just like when allow_html is set to true.
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
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 this list of standard Field Types for detail and implementation examples of the various field types offered through this API.