We’re making changes to our server and Data Center products, including the end of sale for new server licenses on February 2, 2021 and the end of support for server on February 2, 2024. Learn what this means for you.
This page gives an overview of the options available for allowing users to configure their instance of your gadget.
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:
Development is easy. Just declare what you want in your gadget XML specification.
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.