Addendum
The following sections provide further information and advanced usage information useful for curious developers. You can safely ignore these.
More Info: Offline Widget Walkthrough
Let's take a look at what the offline widget looks like, to see all the stuff it does for you without lifting a finger - you can skip this section if you want, but it can be helpful to see what the offline widget looks like and what it does.
Let's peek at the offline widget a bit more, showing you its various states. If the user is offline, the offline widget will look like the following:
When the user goes back online, Dojo Offline automatically detects that the network and application have reappeared, and begins syncing:
When done, the offline widget provides automatic feedback to the end-user:
If the user does not have Google Gears installed, then we provide a prominent Learn How link:
If the user clicks the Learn How link, a popup-window will appear that provides them instructions on how to install Google Gears and use your application offline:
Notice that your application name is inserted into this Learn How page;
the Learn How page automatically inserts your application's name, defined
by setting dojox.off.appName
, into this page, making it customized for your end-users. You
do not have to edit it's HTML source.
The Learn How page also provides an easy hyperlink for your end-users to
run your application when offline. When offline, a user would open their browser
as normal and type your web application's URL into the location field, such as
www.mywebapp.com
. However, Google Gears is sensitive to how a user types this; for example,
if they type mywebapp.com
instead of www.mywebapp.com
, they might not be able to pull up the
application offline and will get an error. Also, if your web app has a long
name, such as http://mywebapp.com/foobar/something
then this is tedious and error-prone for an end user to type
when offline. To solve this, the Learn How page automatically provides a
hyperlink to your web application for a user to drag to their desktop or browser
link toolbar:
When offline, they can double-click this link to open a web browser and easily
access your app when offline. Dojo Offline automatically figures out what the
URL of this link should be (instructions on how to change this default URL are
available
here).
If Google Gears is already installed, perhaps from working with another offline web application such as Google Reader, the offline widget still has the Learn How link at the bottom of the widget:
When clicked, though, the Learn How page automatically adapts to show less instructions, basically just providing the user with some minimal instructions on how to use things offline and provides the same draggable hyperlink:
Again, all of this is the kind of fit-and-finish that is hard to get right that Dojo Offline provides out of the box - it all comes for free.
If you want to customize the look and feel of the offline widget then learn more here.
More Info: Manually Adding Offline Files
Manually adding offline files is easy; you can even mix this with the slurp()
method if you want, so you can slurp the page for most of your resources, then
perhaps manually add a few that weren't picked up because they are dynamically
brought in through JavaScript.
To add a single file:
dojox.off.files.cache("images/some_image_added_by_javascript.png");
To add many files at once:
dojox.off.files.cache([ "images/file1.png", "images/file2.png", "scripts/some_dynamic_script_tag.js" ]);
You can call cache()
as many times as you want; duplicates are automatically removed, and new cached additions are simply added to the end of our internal cached file list.
More Info: How Network Checking Works
Dojo Offline has a timer that every fifteen seconds is checking to make sure that your web application is available. By default, it looks for a simple static text file on your web server bundled with the Dojo Offline framework, located at dojox/off/network_check.txt
. This file is very short, with just the number 1
in it. We use a static text file rather than hitting your main web page since the main web application is probably dynamically generated and hitting it every 15 seconds would impose scalability limits, while a static text file is simple to serve.
You shouldn't need to change this part of the framework, but if you need to the interval for checking can be set on dojox.off.NET_CHECK
and the availability URL can be changed from the network_check.txt
file to your own custom page by setting dojox.off.availabilityURL
. If you want to completely disable this feature, you can set dojox.off.doNetChecking
to false
.
Advanced Usage
This section describes various advanced usage scenarios that most users will never need to use; you can safely ignore these unless you are doing various strange, advanced things.
Advanced Usage: Learn How URL
On the Learn How page is a URL that a user can drag to their desktop to run your
web application when offline. This URL is set automatically to the main page of
your web app, but you can manually set it for unusual situations by assigning a
URL to dojox.off.runLink
and change the title of the link by setting
dojox.off.runLinkTitle
; note that runLinkTitle
should be normal text and not
HTML.
Advanced Usage: Change The Dojo Offline Widget's Look and Feel
If you want to customize the look and feel of the offline widget you can. When
we automagically embed the widget on page load, we actually grab a template file
located at dojox/off/resources/offline-widget.html. This file simply has a bunch
of HTML elements that we inline into the page. Every element has an ID, such as
dot-widget-network-indicator
, that you can attach to with CSS to change. There
is also a CSS file with defaults in dojox/off/resources/offline-widget.css.
You have several options for customization. The easiest is to just create new
CSS rules for the element IDs in the offline-widget.html
file; look up the name
of the ID that you want to change, and then create a CSS rule. More advanced is
to cut and paste the HTML from the offline-widget.html
file right into your HTML
page, getting rid of the dot-widget
automagic DIV
you used in the past to have
the template file inserted. Then, you can selectively drop any elements you want
from the HTML, including adding new ones -- Dojo Offline is designed to be able
to work even if you have dropped parts of the template.
If you want to change the Offline Widget's image icons for some reason, such as for branding or color palette reasons, the following properties can be set through JavaScript to a new URL:
-
dojox.off.ui.onlineImagePath
- The green online ball -
dojox.off.ui.offlineImagePath
- The red offline ball -
dojox.off.ui.rollerImagePath
- The syncing spinner -
dojox.off.ui.checkmarkImagePath
- The green success checkmark after syncing
For example, if you wanted to change the green online ball to a different icon, you would do the following:
dojox.off.ui.onlineImagePath = "images/myonlineball.png";
If you want to brand the Learn How page in some special way, its HTML is at dojox/off/resources/learnhow.html and its CSS is inside dojox/off/resources/offline-widget.css, near the bottom of the file.
To completely throw the Offline Widget away, you can simply set
dojox.off.ui.autoEmbed
to false
. Note that while Dojo Offline is designed to not use the offline widget, dropping the offline widget and doing everything manually is currently not well tested yet. It is recommended that you use the offline widget in general.
Advanced Usage: Dojo Storage
This section provides further details on aspects of Dojo Storage that can help with advanced usage.
In addition to the standard put()
and get()
, there are some other methods on dojox.storage
you might find useful:
-
dojox.storage.hasKey(key, namespace)
- Determines if somekey
is available;namespace
is optional. dojox.storage.getKeys(namespace)
- Gets all of the keys available, as an array. namespace is optional. Example:dojox.storage.getKeys()
dojox.storage.clear(namespace)
- Clears all of the keys in the givennamespace
.namespace
is optional. Example:dojox.storage.clear()
dojox.storage.remove(key, namespace)
- Removes the given key.namespace
is optional. Example:dojox.storage.remove("someKey", "someValue")
dojox.storage.getNamespaces()
- Returns an array of all of the namespaces that are in use.dojox.storage.isValidKey(key)
- Will returntrue
orfalse
if the givenkey
is valid (i.e. it will make sure that it has only letters, numbers, or under score characters).dojox.storage.put(key, value, resultsHandler, namespace)
- You can use an optionalnamespace
to partition the keys you store -- useful for advanced usage when you have several different sets of data that might have similar keys. SetresultsHandler
tonull
when doing this:dojox.storage.put("someKey", "someValue", null, "someNamespace")
dojox.storage.get(key, namespace)
- You can also use an optionalnamespace
here when retrieving keys. Example:dojox.storage.get("someKey", "someNamespace")
Some readers of this tutorial might have used Dojo Storage in the past,
before the new Google Gears and Dojo Offline integration. Some
important notes. First,
Dojo Offline provides a new Dojo Storage Provider named
GearsStorageProvider
, which stores it's hash table data into Google
Gears. Second, we do not bundle any of the other storage providers with
the Dojo Offline build, such as the Flash and Firefox storage
providers, since they are not needed when used in conjunction with
Google Gears and take up valuable space. Finally, you will notice that
we did not give a callback to the put()
example above like in the past; when using Dojo
Storage in conjunction with Dojo Offline and Google Gears, put()
calls
happen immediately and won't be denied, so you do not need to provide a
callback. This makes doing put()
calls much easier.
You can safely ignore knowing this, but it can be useful for some
applications. The default namespace, if none is specified for the various Dojo Storage methods that take an optional namespace, is in
dojox.storage.DEFAULT_NAMESPACE
, which has the value default
. The
underlying Google Gears database is used to store the Dojo Storage
values; the table name is in dojox.storage.TABLE_NAME
(it is actually
defined in the dojox/storage/GearsStorageProvider.js
file), and it's
value is __DOJO_STORAGE
. Knowing these values can help with debugging in some cases so you can peer at them in the underlying Google Gears data store if necessary.
Advanced Usage: Dojo SQL Open/Close
The underlying Google Gears SQL data store must be opened before SQL can be executed, and should be closed when it is not used, though it will recover if you do not close it. Dojo SQL automatically does this open/close routine to simplify your code. When you execute a SQL statement with Dojo SQL, it will automatically open the database, execute your SQL, and close it. If you are working on performance sensitive code, where you have a for loop for example that is rapidly executing hundreds of inserts, this behavior could slow your app down considerably. In this case, you can just manually call dojox.sql.open()
and dojox.sql.close()
yourself, and Dojo SQL will automatically detect this and leave the database connection alone and open:
var bigData = getBigData(); // get an array that has a bunch of data in it dojox.sql.open(); for(var i = 0; i < bigData.length; i++){ dojox.sql("INSERT INTO MYTABLE (LAST_NAME, FIRST_NAME) VALUES (?, ?)", bigData[i].lastName, bigData[i].firstName); } dojox.sql.close();
Google Gears also supports having multiple named relational data stores for a single application; Dojo SQL does not currently expose this functionality, and stores its dataset as a Google Gears relational data store under the name given by dojox.sql.dbName
, which is currently PersistentStorage
. Note that if you have multiple applications running on the same web site they will create their tables in the same data store, the PersistentStorage
one, which can create conflicts; this is a known issue that will be fixed in the future.
Advanced Usage: Dojo Sync
The Dojo Sync onSync
event fires more than just the download
and finished
events touched on in the tutorial above. Here is the full list of event types if you want to do deep customization, such as updating your UI to display the progress of syncing (note that the default Dojo Offline UI widget does this for you if you choose to pull that in). Most of these are only appropriate for advanced usage and can be safely ignored:
start
- syncing has startedrefreshFiles
- syncing will begin refreshing our offline file cacheupload
- syncing will begin uploading any local data changes we have on the client. This event is fired before we fire thedojox.off.sync.actions.onReplay
event for each action to replay; use it to completely over-ride the replaying behavior and prevent it entirely, perhaps rolling your own sync protocol if needed.download
- syncing will begin downloading any new data that is needed into persistent storage. Applications are required to implement this themselves, storing the required data into persistent local storage using Dojo Storage or Dojo SQL.finished
- syncing is finished; this will be called whether an error ocurred or not; checkdojox.off.sync.successful
anddojox.off.sync.error
for sync detailscancel
- Fired when canceling has been initiated; canceling will be attempted, followed by the sync eventfinished
.
If you want to pop up a merge UI, you can create your own and choose to pop it up during your custom onReplay()
callback during replaying.
If you don't want to use the transactional action log system for syncing, register for the upload
event and simply do uploading however you want.
If you want to completely override the sync process in general and roll your own sync infrastructure, override dojox.off.sync.synchronize()
with your own logic; make sure to refresh the offline files as a minimum, though. Rolling your own sync infrastructure is not well supported, however, and is not recommended.
- Printer-friendly version
- Login or register to post comments
- Unsubscribe post