Let's use the MarkMail gadget developed in the previous tutorial to set the mailing list as a user preference, so that we can use the same gadget, to display graphs for various lists.
For this, we can add a simple option where the user can set the URL of the list . We can pick that user set option and fetch data accordingly.
The user preference allows the user to set the URL of the mailing list. In the gadget's logic, we can use the value of the preference set rather than the hard-coded URL value. For that we need to first initialize the preferences within the gadget.
And then, use the prefs object to pick the value set for MailingList:
That's it! The rest of the logic is the same as we discussed in previous tutorials of this series. Note that, by default, the type of the preference is treated as a string. Therefore, we use the getString API, to retrieve the value of the user preference.
Now the user can use the settings menu icon on gadget’s title bar and set a mailing list address. The gadget will reload with new data.
Using enum Data Type as an Options List
Allowing users to set any URL using a string preference can lead to errors, and even usability concerns if the users do not know where to find the right URLs. Therefore, it is useful to provide a list of URLs as options. Also, based on the URL selected, we need to change some setting in the gadget presentation; for example the caption of the table. Therefore, we need something more than a simple string box to pick the URL.
Let’s say we want this gadget to support visualizing data for all main WSO2 mailing lists. We can allow users to pick a mailing list with an instance of the gadget. The enum type user preference can be used to implement this.
In this enum user preference, we have used values 0 to 5 and a descriptive text for each as display value. Then we can pick the user selection using:
Note that the selected value of enum can be accessed by using both getString and getInt, given that the value field contains a number. But, if it contains non-digit characters, using getInt will result in an error.
Using Boolean Data Type
In the gadget, we display only the graph. But we also have the data as a HTML table. If the user wishes, we can allow the user to see the table instead of the graph. This allows the user to duplicate the same gadget and see the data and the graph side by side.
This can be achieved with a simple Boolean type user preference.
Note that we can use the getBool API call to access boolean type user options.
Integer Settings with String Data Type
The user preference documentation here (http://code.google.com/apis/gadgets/docs/fundamentals.html#Datatypes), has no integer data type. But the API supports getInt as mentioned here (http://code.google.com/apis/gadgets/docs/reference/#gadgets.Prefs).
What this means is that, if you want to deal with integer type user option, such as the height and width of the graph, you can use a string type user preference and access the value using getInt.
Setting Preferences from Within the Gadget
User preference functionality is built into the gadget framework, and the API is easy to use. You just define the user preferences in the gadget, and the preferences will be generated with a form inside the action area of the gadget.
This is useful for most of the options which are usually one off. Once set, they will be hidden away from users without appearing in the visual area.
But some user preferences need to be changed more frequently. For example, as opposed to the mailing list URL, the theme of the graphs are more frequently changed. An admin can lay out the number of instances of the gadget and the mailing list but the graph theme might be a user-specific choice.
For such frequently changed options, having only the default user preference form could be a productivity-killer. This is because, the user has to go through 4 clicks each time a change is required, as shown in the following diagram.
For more frequently used options, we can facilitate one click instead of four. For this, we need to do three things, in addition to the usual user preference settings.
First, set "setprefs" inside <ModulePrefs> element as follows:
Second, provide an on-screen, within gadget HTML element to allow the user settings. In this example we use a select element for the user to pick the theme.
Note that inside the udateTheme fuction, we use the prefs.set API call to set the preference value. This means that the preference value will be persisted, and when the user views the gadget next time, the theme set last will be used as opposed to the default theme.
You can find more information on the use of setprefs feature and saving sate, on Google gadgets documentation here: http://code.google.com/apis/gadgets/docs/fundamentals.html#SetPrefs
Dealing with Views
There is a "view" attribute that is available with <Content> element. Multiple <Content> elements can be defined to make the gadget look different and fit for various views. However, defining multiple <Content> elements can lead to gadget logic duplication, especially for one as sophisticated as the MarkMail gadget that we developed from tutorial 1 of this series. Good news is that the Google gadget API has provisioning to deal with views programmatically as described here: http://code.google.com/apis/gadgets/docs/ui.html#curr_view.
For our example MarkMail gadget, we can choose to display both the table and the graphs side by side on the same gadget, when the gadget is in "canvas" view. Canvas view is the view you get when the gadget is maximized. In the maximized view, we have enough real state to show both the table and the graph on the same gadget.
For view API to be used, we need views feature.
If we are in canvas view, we show both content div and graph div.
Here is the maximized view of the gadget.
Versatility of Google Gadgets as a Presentation Instrument
In the past three tutorials of this series, we developed a gadget incrementally to fetch HTML from a URL, extract data and present those in an appealing manner. Let's have a look at a dashboard built using this gadget. The following is a screen shot of such a dashboard, created using the WSO2 Gadget Server.
As you can see, the gadget is duplicated six times and data presented on six different mailing lists. Moreover we have six themes used for the six graphs so that the mapping of the visual elements on the dashboard is natural. Furthermore, we have the architecture list, developer lists, code commit message list and issue reporting lists all presented side by side on the same dashboard. This offers the user a better view. For example, the user can easily spot the release efforts in sync with the peaks in svn commits and issue related activities.
This illustrates how a carefully designed gadget can help present and visualize information better. A gadget is worth a thousand pages!
In conclusion, let's look at some tips and tricks to keep in mind when developing gadgets in tutorial : Tips and Tricks in Developing Gadgets