Canvas 2D Web Apps/iOS Web Apps

This chapter discusses the basic differences between HTML web apps for desktop browsers and web apps for iOS devices. It assumes that you are familiar with the previous chapter Getting Started with HTML Web Apps. If you haven't read that chapter yet, you should read it first.

Using Web Apps on iOS Devices
In order to open a web app on an iOS device, you simply open the HTML file with the Safari web browser (or other browsers) on your iOS device. Thus, if you want to develop a web app for an iOS device, you should put the HTML file on the web such that you can access it with Safari. (If you don't have access to a web server, you can use services like the public folder of a dropbox account.)

If you try this with the example from the previous chapter Getting Started with HTML Web Apps (which you can access online), you might realize some differences:
 * You can change the orientation of an iOS device by tilting it and the web app will be rotated accordingly; however, the web app might then no longer fill the whole display because it uses an incorrect viewport.
 * On an iOS device, you can pan and zoom the web app with the default touch gestures, which makes sense for standard web pages but usually doesn't make much sense for web apps.
 * You can add a link to the web app to the home screen of the iOS device by tapping the share icon and then tapping “Add to Home Screen”. However, this link will just open the web app with Safari and therefore it won't work if your iOS device is not connected to the internet.

This chapter explains how to address these issues; i.e., it shows how to set the correct viewport size, how to handle orientation changes, how to disable the default touch gestures, and how to configure the web app such that users can download it to their device and use it offline like any other app (without indicating that it runs in Safari).

An example that integrates all these techniques is presented at the end of this chapter.

Setting the Viewport Size and Handling Orientation Changes
In order to set the correct viewport size for a web app that is not supposed to be scaled or panned by the user, you should use this HTML  tag right after the   tag: This tells the Safari browser on iOS devices to always set the viewport to the full width of the device, disable scaling by the user, and start without scaling (i.e. a scale factor of 1.0). (Note that height should not be set to the device height since this can lead to problems.)

Orientation changes can be used to call an event function (similarly to  but using  ); however, orientation changes usually also result in resize events. Thus, it is sufficient to update the content of the canvas for the new width and height. If you want to render different contents for portrait and landscape orientation, you can check whether the width is larger than the height (landscape orientation) or the height is larger than the width (portrait orientation).

Apple developers can find more information about setting the viewport in Apple's Safari Web Content Guide under Configuring the Viewport. More information about handling orientation changes is available under Handling Events.

Disabling Default Mouse and Touch Gestures
In order to disable all the default mouse and touch gestures, a custom event handler has to be defined in JavaScript:

The line  disables the default behavior for the specific event. To call the event handler  for all mouse clicks and multitouch events, the following   tag can be used:

Additionally, this tag includes the attribute  in order to disable any user interaction with HTML elements of the web app.

Apple developers can find more information about preventing the default behavior in Apple's Safari Web Content Guide under Handling Events.

Configuring Web Apps for Offline Use
There are several ways to make web apps appear more similar to standard apps on iOS devices. These are:
 * customizing the icon on the user's home screen
 * customizing the startup image of the web app
 * hiding the Safari interface
 * changing the status bar appearance
 * specifying resources (in particular images) for offline use

Customizing the Icon on the User's Home Screen
The icon should be a PNG file of exactly 57 × 57 pixels. If the file is located in the same directory as the HTML page and the name is  then it could be specified this way:

For Apple developers, more information is available in Apple's Safari Web Content Guide under Configuring Web Applications.

Customizing the Startup Image
The startup image should be a PNG file of exactly 320 × 460 pixels in portrait orientation. If the filename is, it can be specified this way:

More information for Apple developers is available under Configuring Web Applications.

Hiding the Safari Interface and Changing the Status Bar
The Safari interface is hidden by a  tag, which should be placed right after the   tag:

If this line has been added then the appearance of the status bar can also be changed; for example to black:

Other options are  and.

More information for Apple developers is available under Configuring Web Applications.

Specifying Resources for Offline Use
In order to allow users to use a web app when they are not connected to the internet, you have to specify a manifest file that lists all the resource files (in particular images) that should be downloaded with the web app. (This does not include the manifest file itself nor the HTML file of the web app, nor the icon of the web app mentioned above nor the startup image.)

The manifest file is a plain text file with the filename extension  and line breaks according to MacOS conventions. (On a MacOS X computer, you can use  to create such a file. On Windows, you can use editors that allow you to customize the character for line breaks, e.g. geany.) The first line has to be. The following lines have to include the filenames of the resource files (one name per line). If you get any of this wrong, the web app won't work without an internet connection but there won't be any error message. (Also note that the iOS device must be connected to the internet when the web app is started from the home screen for the first time.)

An example of a manifest file with name  that specifies two images could be:

The manifest file itself has to be specified in the  tag of the web app:

For Apple developers, more information is available in Apple's Safari Web Content Guide under Storing Data on the Client. HTML5 specifies the related offline web applications. The Mozilla Developer Network offers a good introduction to using the application cache.

Complete Example
In order to apply the presented techniques, you have to download all image files that your web app requires. For example, I downloaded a PNG image from Wikimedia Commons and called it. Then, I created (with TextEdit on a Mac) a manifest file called  to specify the image file. The content of the manifest file is:

The manifest file  is then specified in the   tag of the HTML file. Furthermore, I created a simple startup PNG image of 320×460 pixels with the name  and an icon of 57×57 pixels with the name. Both these files are specifed by  tags in the HTML file. Note that the HTML file, the manifest file, and the image files are all in the same directory. The example is based on the example of the previous chapter Getting Started with HTML Web Apps but with the additions discussed in this chapter. (The full example with all files is available online.) The HTML file looks like this:

The complete example is available online such that you can easily try it out. Note that there is also a  tag, which specifies the default name of the web app when you download it to an iOS device (via tapping the share icon). Once you have added the web app to the home screen of an iOS device, you should start it once with an active internet connection. After that you should be able to start it even if the iOS device is offline.

When you develop for Safari on an iOS device, remember to save files under new names after every edit and use the new files in order to make sure that Safari doesn't use a cached version (without your changes) of the files.