Allowing Configuration Options in your Gadget

This page gives an overview of the options available for allowing users to configure their instance of your gadget.

On this page:

Setting User Preferences via the UserPref Element in the Gadget XML

You can make use of the user preferences section of your gadget XML specification, where you can declaratively specify a set of configurable options. See our guide to the gadget XML specification.

Each user preference has a name, a display name, a data type and a default value. You can also flag a user preference as required or optional.

To access the user preferences from your gadget, you can use one or more of the following:

• The user preferences JavaScript API, as described in the OpenSocial JavaScript API.
• Specially-formatted tokens in the gadget XML file that are automatically substituted by the gadget renderer. These tokens look like this: __UP_pref_name__.
• JavaScript that sets the user preferences via the setprefs feature. See our guide to including features into your gadget.

Advantages of this Configuration Method

• Development is easy. Just declare what you want in your gadget XML specification.
• The container handles generation of the configuration UI, saves the settings and provides an API to access the settings in JavaScript.
• You can make use of automatic substitution in the gadget specification content, including substitution in the gadget title and other metadata as well as the body content.
• It is easy for users to figure out how to change the settings, because the container handles the configuration consistently for all gadgets.

Disadvantages of this Configuration Method

• It is inflexible. You are limited to a small number of data types, have no control over the UI, and the only validation you can do is to set fields as required or optional.
• The user preferences are static. There is no way to change the number or type of configuration settings programatically. Enum type preferencess (rendered as a radio button or select list) can only have values that are hardcoded in the specification file. This means that they are not useful for something like choosing a project from JIRA.
• Both iGoogle and Atlassian Gadgets currently refresh the whole page when you save a user preference form.
• Both iGoogle and Atlassian Gadgets (via Shindig) automatically HTML-escape values returned from prefs.getString(). (See SHINDIG-89.) This means:
  • If you're using the value as literal HTML, you must not double-escape it.
  • If you're using the value in some other way (in a URL for example) then you must unescape it.

Handling Configuration Inside your Gadget

The other option is to handle configuration yourself, inside the gadget. This is the approach used by the Remember the Milk gadget, for example. In this case, you can store the settings in a user preference of type hidden, using the setprefs API as described in the Google developer guide, or you can come up with some other way to store the settings. You might be interested in looking at the json API for serialising data.

Advantages of this Configuration Method

• You can do whatever you want in your configuration UI: Load dynamic data, provide fancy UI controls, use Flash or Java, hide and show sections depending on what users enter. And so on.
• You can store the data however you want: Post it back to the application server, keep it in a cookie, use a Google Gears database.
• If you want to, you can still use user preferences to store the values and save yourself the effort of figuring out where to put the data.
• Because everything happens inside the gadget, you can avoid reloads and dynamically refresh the parts of your gadget that are affected when configuration settings change.

Disadvantages of this Configuration Method

• This method demands a lot more work. You have to write a lot of code to do things that the container handles automatically for UserPref. For example, if you want your gadget's title to be based on a user preference, you will have to use the settitle feature to do that yourself.
• There are no established conventions or guidelines for this yet.
• You will need to provide your own UI for entering the configuration mode, since the edit command provided by the container only works for UserPref.

RELATED TOPICS

Creating your Gadget XML Specification
Writing an Atlassian Gadget
Gadgets and Dashboards Development Hub