Introduction
Each field in the Settings API is configured with the following properties:
| Property | Type | Description |
|---|---|---|
| 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 Form’s classes named “small”, “medium”, and “large” which you may use to control the size of the field generated.
| Property | Type | Description |
|---|---|---|
| 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.
| Property | Type | Description |
|---|---|---|
| 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. |
| 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.
| Property | Type | Description |
|---|---|---|
| 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. |