Last updated Dec 8, 2017

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.

Security Note

Keep in mind that user preferences are stored in the container server, and are passed as URL parameters to the gadget rendering server. You may want to be careful about what you put in there. In particular, a shipping gadget would never want to store a username and password in user preferences, because then anyone with read access to a shared dashboard with that gadget would be able to get the owner's login information. See user authentication guidelines.

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:

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

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

Creating your Gadget XML Specification

Writing an Atlassian Gadget

Gadget Developer Documentation

Rate this page: