Please note that as of October 24, 2014, the Nokia Developer Wiki will no longer be accepting user contributions, including new entries, edits and comments, as we begin transitioning to our new home, in the Windows Phone Development Wiki. We plan to move over the majority of the existing entries. Thanks for all your past and future contributions.

Handling online/offline in WRT widget

From Wiki
Jump to: navigation, search
Article Metadata
Created: isalento (22 Mar 2010)
Last edited: hamishwillee (23 Jul 2012)
The perfect miniview


Creating the perfect Miniview

In the Nokia N97 device (11.0.021), Nokia N97 mini device (10.0.020), and onwards, an HTML 5-compliant Online/Offline API was introduced that makes it possible for a widget to know when it can access the network. Currently, this API is supported in all devices with BrowserNG/7.1 or newer, including selected S60 3rd Edition, Feature Pack 2 mobile devices.

Many home screen widgets rely on periodic updates from the web service to show up-to-date content. And this is the perfect way for the web service owner to push information to the user's home screen. However, since a widget behaving badly will very quickly be removed by the user, it is advisable to make sure the home screen gives a good user experience while also making sure the device's resources are not overused, the battery is not drained and the user's phone bill will not contain any nasty surprises.

The flow chart on the right displays the "perfect miniview" example as a high level presentation. The example attached to the end of this presentation (soon) is implemented in the manner described in the flow chart. All the code snippets in this document are from that example. You can click on the image to make it larger.

Saving battery life

The phone spends most of it's life time in a pocket or a handbag. Therefore there is no point in updating the miniview constantly, but rather stick to longer interval. 15 to 30 minutes is enough for most use cases. Also processing the data and especially images will use juice, so the less it's done - the less energy is needed -> the longer the battery lasts:

window.onload = init;
var updateIntervalMiniView = 20*60*1000;//20 minutes
var timerMV = null;
function init(){
timerMV= setInterval(updateMiniview,updateIntervalMiniView);
function updateMiniview(){
//Update the miniview

Saving data locally for the miniview

In the above code example, the miniview is updated every 20 minutes. If you look at the flow chart, you will notice that the miniview handler never reads data from the network. It uses locally stored data. The setPereferenceForKey() -function is used for this purpose. In the supported devices there is no limit for the saved data. Any data saved with the setPereferenceForKey() will persist and is available for the widget even if it is closed and removed from the miniview at some point. The locally stored data is only updated when the feed is being read, resulting in a lot fewer calls to the network and lower data usage. The feed will usually be read from the browser cache, even if the data is not stored locally, but according to the server's and device's settings the cache is periodically flushed so saving data locally is the safest choice.

var feedData = null;
function updateFeed(){
feedData = readFeed(URL);
if(!feedData=null) widget.setPreferenceForKey(rssxml, "offlineFEED");

Tip.pngTip: Prepare some data for the miniview and iclude it in the widget package. You can for example boast about your app and instruct the user to go online for latest news

var firstRun = true;
function init(){
firstRun = widget.preferenceForKey("firstRun");
rssxml ="<?xml data for the first time -->";
widget.setPreferenceForKey(rssxml, "offlineRSS");
widget.setPreferenceForKey(false, "firstRun");

Handling images in offline mode

Whether you use a feed from the browser's cache or a locally saved feed, you will not see images that have not been cached earlier. For this purpose, provide a default image using style.background


The Online/Offline API

Network access of home screen widgets is controlled by the user with the Options menu, using the ‘set content to offline mode’ or ‘set content to online mode’ options. Online/offline selection is added to the left softkey menu once there is at least one WRT widget on the home screen. If the user selects ‘set content to offline mode’, JavaScript gets a window.onoffline event. Respectively, window.ononline is fired when ‘set content to online mode’ is selected. Home screen online/offline selection does not affect widgets that are launched from the applications menu and are not placed on the home screen.

If the home screen is set to offline, widgets in mini-view mode should not try connect to the network. The home screen can either be turned online explicitly from the right softkey menu or the user can permit a full screen home screen widget to access the network when prompted if home screen content can connect.

If the network connection is denied by the user, the widget must take note of this and not try to connect again. If the connection is needed, the user must be notified and the option of closing the widget should be given:

window.onoffline =  function(){
//stop periodic callbacks to network
//show offline indicator on mini-view
window.ononline = function(){
//perform periodic update if needed
if(!timerFEED)timerFEED=setInterval(getRSS,updateIntervalFeed);//Start the miniview update
//hide the offline indicator from the miniview
function getRSS(){
case window.navigator.NetworkNotAllowed :
case window.navigator.NetworkAccessAllowed:
case window.navigator.NetworkAccessible:

Online/Offline API usage in non-home screen widgets

All widgets that should take advantage of the Online/Offline API, whether or not they have a home screen. Implementing the offline state improves user experience greatly when there is no network available, or network connection is not allowed. is triggered if a network connection is made by some other program in the background or if the connection status changes for some other reason. However, the stand-alone widget cannot blindly rely on the navigator.onLine property value before the initial network connection is made from the widget. That is because the ‘Allow network connection’ prompt is shown when the widget tries to connect to the network for the first time. If the user declines the connection, window.onoffline is fired and the widget cannot connect to the network until it is restarted.

See Online offline api for more information.

This page was last modified on 23 July 2012, at 07:39.
142 page views in the last 30 days.