Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Last updated Dec 8, 2017

Field definitions

This page gives more detail about the field types that were introduced in Creating a Gadget JavaScript Object.

Hidden Fields

Sometimes you want to pass values back to the server from a form submission, but you do not want the user to be able to change those values. You can use hidden fields to achieve this.

The following code defines a hidden field:

1
2
fields: [
    {
        userpref: "isConfigured",
        type: "hidden",
        value: "true"  /* This example is hard coded but it could be dynamically
                          generated or retrieved from the gadget prefs.*/        
    },
    ... /* Other fields */
]

Where:

userpref -- The name of the field. Should be the name of the UserPref to save.
type -- Use "hidden" to specify that this field is hidden.
value -- The value that will be passed back to the server for validation and will then be saved.

Text Input

This field type will be displayed as a simple text field. If the the type attribute is not defined, the field will be of this type by default.

1
2
fields: [
    {
        id: "numToDisplay",
        userpref: "numToDisplay",
        class: "numField"
        label: gadget.getMsg("gadget.common.num.label"),
        description: gadget.getMsg("gadget.common.num.description"),
        type: "text",
        value: gadget.getPref("numToDisplay")
    },
    ... /* Other fields */
]

Where:

id -- (Optional.) The HTML id to give this field. Defaults to the value of the userpref field.
userpref -- The name of the field. Should be the name of the UserPref to save.
class -- (Optional.) The HTML class to apply to this field. If omitted, will default to type.
label -- The label to display next to the field.
description -- (Optional.) The description of the field.
type -- (Optional.) If the value is "text" or omitted, a text field (i.e. the type discussed in this paragraph) is rendered.
value -- (Optional.) The initial value of the field. If this is a UserPref, we usually populate it with the UserPref value.

Text Area

This field type creates a text input area in the form, used for large text inputs.

1
2
fields: [
    {
        id: "textToDisplay",
        userpref: "textToDisplay",
        class: "textBox"
        label: gadget.getMsg("gadget.common.display.text.label"),
        description: gadget.getMsg("gadget.common.display.text.description"),
        type: "textarea",
        value: gadget.getPref("textToDisplay")
    },
    ... /* Other fields */
]

Where:

id -- (Optional.) The HTML id to give this field. Defaults to the value of the userpref field.
userpref -- The name of the field. Should be the name of the UserPref to save.
class -- (Optional.) The HTML class to apply to this field.
label -- The label to display next to the field.
description -- (Optional.) The description of the field.
type -- Value must be "textarea" for this type of field.
value -- (Optional.) The initial value of the field. If this is a UserPref, we usually populate it with the UserPref value.

Select

This field type is a simple selection list. As the AJAX options have been retrieved and are available during the creation of the field decscriptor, it is trivial to use them as options for the selection list. The results can be used raw or transformed.

1
2
fields: [
    {
        id: "cumulative-field",
        class: "cumulative-select-list",
        userpref: "isCumulative",
        label: gadget.getMsg("gadget.common.cumulative.label"),
        description:gadget.getMsg("gadget.common.cumulative.description"),
        type: "select",
        selected: gadget.getPref("isCumulative"),
        options:[
            {  /* These options are hard-coded but could easily be the results of an AJAX call
                  (E.g. args.projects) or be calculated at run time (E.g. the next three days) */
                label:gadget.getMsg("gadget.common.yes"),
                value:"true"
            },
            {
                label:gadget.getMsg("gadget.common.no"),
                value:"false"
            }
        ]
    },
    ... /* Other fields */
]

Where:

id -- (Optional.) The HTML id to give this field. Defaults to the value of the userpref field.
userpref -- The name of the field. Should be the name of the UserPref to save.
class -- (Optional.) The HTML class to apply to this field. Defaults to "select".
label -- The label to display next to the field.
description -- (Optional.) The description of the field.
type -- Value must be "select" for this type of field.
selected -- (Optional.) The value of initially selected option. If this is a UserPref, we usually populate it with the UserPref value.
options - An array of option pairs or groups.

An option is defined as:

1
2
{
    id : "option-id",
    label: "A human readable label",
    value: "option-value",
    selected: true
}

Where:

id -- (Optional.) The id of the option.
label -- The displayable label for the option.
value -- The value to save if this option is selected.
selected -- (Optional.) Specifies whether or not to initially select this option. If only one option can be selected (selection list or radio group) it is more convenient to specify the selected value on the field definition.

Option groups are used in the following example:

1
2
fields: [
    {
        userpref: "groupedOptions",
        label: gadget.getMsg("gadget.common.grouped.label"),
        type: "select",
        selected: gadget.getPref("groupedOptions"),
        options:[
            {
                group: {
                    label: "First Option Group",
                    options: [
                        {
                            label: "First Group -> First Option",
                            value: "group-1_opt-1",
                        },
                        {
                            label: "First Group -> Second Option",
                            value: "group-1_opt-2",
                        }
                    ]
                }
            },
            { /* You can mix groups and non-group options */ 
                label:"No Group Options", 
                value:"group-N/A_opt-1"
            },
            {
                group: {
                    label: "Second Option Group",
                    options: [
                        {
                            label: "Second Group -> First Option",
                            value: "group-2_opt-1",
                        }
                    ]
                }
            }
        ]
    },
    ... /* Other fields */
]

Where:

group -- An object containing the sub-options.
group.label -- The label for the option group.
group.options -- The options to display under the option group.

Multi Select

This field type produces a multi-select input value.

1
2
fields: [
    {
        id: "version-field",
        class: "multiVersionField",
        userpref: "selectedVersions",
        label: gadget.getMsg("gadget.common.versions.label"),
        description:gadget.getMsg("gadget.common.versions.description"),
        type: "multiselect",
        selected: gadget.getPref("selectedVersions"), /* Only use this if you only want value selected.
                                                         Otherwise specify selection state on the option itself */
        options:[ /* See Select Field for valid options */]
    },
    ... /* Other fields */
]

Where:

id -- (Optional.) The HTML id to give this field. Defaults to the value of the userpref field.
userpref -- The name of the field. Should be the name of the UserPref to save.
class -- (Optional.) The HTML class to apply to this field. Defaults to "multi-select".
label -- The label to display next to the field.
description -- (Optional.) The description of the field.
type -- Value must be "multiselect" for this type of field.
selected -- (Optional.) The value of initially selected option. Only use this if you only want a single value selected. Otherwise specify selection state on the option itself.
options -- An array of options pairs or groups. See the Select field type (above) for valid options.

Radio Button Group

This field type produces a group of radio buttons for selecting a unique value from a list of choices.

1
2
fields: [
    {
        id: "security-level",
        class: "security-radio",
        userpref: "securityLevel",
        label: gadget.getMsg("gadget.common.security.label"),
        description:gadget.getMsg("gadget.common.security.description"),
        type: "radio",
        selected: gadget.getPref("securityLevel"),
        options:[ 
            {  /* See Select Field for valid options */
                label: "Publicly Available",
                value:"public"
            },
            {
                label:"Private",
                value:"private"
            }
        ]
    },
    ... /* Other fields */
]

Where:

id -- (Optional.) The HTML id to give this fieldset. Defaults to the value of the userpref field.
userpref -- The name of the field. Should be the name of the UserPref to save.
class -- (Optional.) The HTML class to apply to this fieldset.
label -- The label to display next to the fieldset.
description -- (Optional.) The description of the field.
type -- Value must be "radio" for this type of field.
selected -- (Optional.) The value of the option to be selected initially. If this is a UserPref, we usually populate it with the UserPref value.
options -- An Array of options pairs or groups. See the Select field type (above) for valid options.

Checkbox Group

This field type produces a group of checkboxes for selecting multiple values.

1
2
fields: [
    {
        id: "group-select",
        class: "group-selector-checkboxes",
        userpref: "selectedGroups",
        label: gadget.getMsg("gadget.common.groups.label"),
        description:gadget.getMsg("gadget.common.groups.description"),
        type: "checkbox",
        options:[ 
            {  /* See Select Field for valid options */
                id: "group-users",
                label: "Users",
                value: "users"
            },
            {
                id: "group-devs",
                label: "Developers",
                value: "developers",
                selected : true
            },
            {
                id: "group-admins",
                label: "Administrators",
                value: "admins",
                selected : true
            }
        ]
    },
    ... /* Other fields */
]

Where:

id -- (Optional.) The HTML id to give this fieldset. Defaults to the value of the userpref field.
userpref -- The name of the field. Should be the name of the UserPref to save.
class -- (Optional.) The HTML class to apply to this fieldset.
label -- The label to display next to the fieldset.
description -- (Optional.) The description of the field.
type -- Value must be "checkbox" for this type of field.
selected -- (Optional.) The value of the option to be selected initially. Only use this if you only want a single value selected. Otherwise specify the selection state on the option itself.
options -- An Array of options pairs or groups. See the Select field type (above) for valid options.

Custom Field

This field type simply injects the string into the form as HTML.

1
2
fields: [
    {
        label: gadget.getMsg("gadget.common.groups.label"),
        description:gadget.getMsg("gadget.common.groups.description"),
        type: "custom",
        userpref: "myfield",
        template: function(){ 
            /* Returned string is injected into form */
            return "<div>An example of a custom field</div>";
        }
    },
    ... /* Other fields */
]

Where:

label -- The label to display next to the field.
description -- (Optional.) The description of the field.
type -- Value must be "custom" for this type of field.
template - A function that returns a string to inject into the form.

Callback Builder

This is the most powerful and flexible type of field for configuration. The callback enables you to construct any HTML and attach event listeners to it.

1
2
fields: [
    {
        id: "my-callback-field",
        label: gadget.getMsg("gadget.common.builder.label"),
        description:gadget.getMsg("gadget.common.builder.description"),
        type: "callbackBuilder",
        userpref: "myCallback",
        callback: function(parentDiv){
            parentDiv.append(
                AJS.$("<input/>").attr({
                    id: "call-back-hidden-field",
                    type: "hidden",
                    name: "myCallback"
                }).val(gadget.getPref("myCallback"))
            );
        }
    },
    ... /* Other fields */
]

Where:

id -- The id given to the div that is passed into the builder.
label -- The label to display next to the field.
description -- (Optional.) The description of the field.
type -- Value must be "callbackBuilder" for this type of field.
callback -- A function that takes in a JQuery wrapped div. You can then manipulate the contents of that div and attach event handlers, e.g. click handlers.

Using the Atlassian Gadgets JavaScript Framework
Writing an Atlassian Gadget
Gadget Developer Documentation