Additional Properties

Introduction

In the Gravity Forms Settings API, you can add HTML attributes to settings fields. These attributes include event handlers like onclick and onchange, which allow fields to respond to user actions. The API treats these attributes as strings and renders them in the HTML. This article explains how to use them in your settings fields.

Examples

Add 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>

Add 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:

PropertyTypeDescription
labelstringThe choice label. Required.
namestringOnly used for checkboxes. The name/key of the setting. Note: This is also used as the id attribute for the containing div tag.
valuestringOnly used for radio buttons and select. If omitted, then the label will be used as the value.
default_valuebooleanOnly 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 radio buttons and select in the field property array, not the choice array.
tooltipstringThe content to be included in the tooltip for this choice. Only used for checkboxes and radio buttons.
tooltip_classstringThe tooltip class; the value to be appended to the class attribute of the element containing this choice’s tooltip. Only used for checkboxes and radio buttons.
iconstringIcon can be an image URL or Font Awesome icon class. Only used for checkboxes and radio buttons.
choicesarrayAn array of choices for this optgroup. See above for the individual choice properties.

Resources