Safari Web Content Guide
`
`User Experience
`
`2009-06-08
`
`SV0134983
`
`

`

`Even though Apple has reviewed this document,
`APPLE MAKES NO WARRANTY OR REPRESENTATION,
`EITHER EXPRESS OR IMPLIED, WITH RESPECT TO
`THIS DOCUMENT, ITS QUALITY, ACCURACY,
`MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
`PURPOSE. AS A RESULT, THIS DOCUMENT IS
`PROVIDED "AS IS/' AND YOU, THE READER, ARE
`ASSUMING THE ENTIRE RISK AS TO ITS QUALITY
`AND ACCURACY.
`
`IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,
`INDIRECT, SPECIAL, INCIDENTAL, OR
`CONSEQUENTIAL DAMAGES RESULTING FROM ANY
`DEFECTOR INACCURACY IN THIS DOCUMENT, even
`if advised of the possibility of such damages.
`
`THE WARRANTY AND REMEDIES SETFORTH ABOVE
`ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL
`OR WRITTEN, EXPRESS OR IMPLIED. No Apple
`dealer, agent, or employee is authorized to make
`any modification, extension, or addition to this
`warranty.
`
`Some states do not allow the exclusion or limitation
`of implied warranties or liability for incidental or
`consequential damages, so the above limitation or
`exclusion may not apply to you. This warranty gives
`you specific legal rights, and you may also have
`other rights which vary from state to state.
`
`• Apple Inc.
`
`© 2009 Apple Inc.
`All rights reserved.
`
`No part of this publication may be reproduced,
`stored in a retrieval system, or transmitted, in
`any form or by any means, mechanical,
`electronic, photocopying, recording, or
`otherwise, without prior written permission of
`Apple Inc., with the following exceptions: Any
`person is hereby authorized to store
`documentation on a single computer for
`personal use only and to print copies of
`documentation for personal use provided that
`the documentation contains Apple's copyright
`notice.
`
`The Apple logo is a trademark of Apple Inc.
`
`Use of the "keyboard" Apple logo
`(Option-Shift-K) for commercial purposes
`without the prior written consent of Apple may
`constitute trademark infringement and unfair
`competition in violation of federal and state
`laws.
`
`No licenses, express or implied, are granted
`with respect to any of the technology described
`in this document. Apple retains all intellectual
`property rights associated with the technology
`described in this document. This document is
`intended to assist application developers to
`develop applications only for Apple-labeled
`computers.
`
`Every effort has been made to ensure that the
`information in this document is accurate. Apple
`is not responsible for typographical errors.
`
`Apple Inc.
`1 Infinite Loop
`Cupertino, CA 95014
`408-996-1010
`
`Apple, the Apple logo, Cocoa, Dashcode, iPod,
`iTunes, Mac, Mac OS, Objective-(, Pages,
`Quick Time, and Safari are trademarks of Apple
`Inc., registered in the United States and other
`countries.
`
`Finder, iPhone, and Multi-Touch are trademarks
`of Apple Inc.
`
`Java and all Java-based trademarks are
`trademarks or registered trademarks of Sun
`Microsystems, Inc. in the U.S. and other
`countries.
`
`Simultaneously published in the United States
`and Canada.
`
`SV0134984
`
`

`

`Contents
`
`Introduction
`
`Introduction 11
`
`Who Should Read This Document 12
`Organization ofThis Document 12
`See Also 13
`
`Chapter 1
`
`Creating Compatible Web Content 15
`
`Use Standards 15
`Follow Good Web Design Practices 16
`Use Security Features 16
`Avoid Framesets 17
`Use Columns and Blocks 18
`Know iPhone OS Resource Limits 19
`Checking the Size of Webpages 20
`Use the Select Element 20
`Use Supported JavaScript Windows and Dialogs 21
`Use Supported Content Types and iPhone OS Features 22
`Use Canvas for Vector Graphics and Animation 24
`Use the Audio and Video Elements 24
`Use Supported iPhone OS Rich Media MIME Types 25
`Don't Use Unsupported iPhone OS Technologies 26
`
`Chapter 2
`
`Optimizing Web Content 29
`
`Using Conditional CSS 29
`Using the Safari User Agent String 31
`
`Chapter 3
`
`Configuring the Viewport 33
`
`Layout and Metrics of Safari on iPhone OS 33
`What Is the Viewport? 34
`Safari on the Desktop Viewport 35
`Safari on iPhone OS Viewport 36
`Examples ofViewports on iPhone OS 36
`Default Viewport Settings 40
`Using the Viewport Meta Tag 40
`Changing the Viewport Width and Height 41
`How Safari Infers the Width, Height, and Initial Scale 44
`Viewport Settings for Web Applications 47
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`3
`
`SV0134985
`
`

`

`CONTENTS
`
`Chapter 4
`
`Customizing Style Sheets 51
`
`Leveraging CSS3 Properties 51
`Adjusting the Text Size 51
`Highlighting Elements 52
`
`Chapter 5
`
`Designing Forms 55
`
`Laying Out Forms 55
`Customizing Form Controls 57
`Configuring Automatic Correction and Capitalization 59
`
`Chapter 6
`
`Handling Events 61
`
`One-Finger Events 61
`Two-Finger Events 64
`Form and Document Events 65
`Making Elements Clickable 65
`Handling Multi-Touch Events 66
`Handling Gesture Events 68
`Preventing Default Behavior 69
`Handling Orientation Events 70
`Supported Events 71
`
`Chapter 7
`
`Configuring Web Applications 73
`
`Specifying a Webpage Icon for Web Clip 73
`Specifying a Startup Image 74
`Hiding Safari User Interface Components 74
`Changing the Status Bar Appearance 74
`
`Chapter 8
`
`Creating Video 75
`
`Sizing Movies Appropriately 75
`Don't Let the Bit Rate Stall Your Movie 76
`Using Supported Movie Standards 76
`Encoding Video for Wi-Fi and EDGE 76
`Creating a Reference Movie 77
`Creating a Poster Image for Movies 78
`Configuring Your Server 79
`
`Chapter 9
`
`Storing Data on the Client 81
`
`Creating a Manifest File 81
`Declaring a Manifest File 82
`Updating the Cache 82
`
`4
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`SV0134986
`
`

`

`CONTENTS
`
`Handling Cache Events 83
`
`Chapter 10
`
`Getting Geographic locations 85
`
`Geographic Location Classes 85
`Getting the Current Location 85
`Tracking the Current Location 86
`Handling Location Errors 86
`
`Chapter 11
`
`Debugging 87
`
`Enabling the Safari Console 87
`Viewing Console Messages 88
`Creating Messages in JavaScript 91
`
`Appendix A
`
`HTML Basics 93
`
`What Is HTML? 93
`Basic HTML Structure 93
`Creating Effective HTML Content 95
`Using Other HTML Features 97
`
`Appendix B
`
`CSS Basics 99
`
`What Is CSS? 99
`lnline CSS 99
`Head-Embedded CSS 100
`External CSS 101
`
`Document Revision History 1 03
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`5
`
`SV0134987
`
`

`

`CONTENTS
`
`6
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`SV0134988
`
`

`

`Figures, Tables, and Listings
`
`Chapter 1
`
`Creating Compatible Web Content 15
`
`Figure 1-1
`Figure 1-2
`Figure 1-3
`Figure 1-4
`Figure 1-5
`Figure 1-6
`Table1-1
`
`Comparison of frameset on the desktop and iPhone OS 17
`Comparison of no columns vs. columns 18
`Comparison of the select element on the desktop and iPhone OS 21
`Confirm dialog 22
`Playing video on iPhone OS 23
`Viewing PDF documents on iPhone OS 23
`Supported iPhone OS rich media MIME types 25
`
`Chapter 2
`
`Optimizing Web Content 29
`
`Figure 2-1
`Figure 2-2
`Listing 2-1
`Listing 2-2
`Listing 2-3
`Listing 2-4
`Listing 2-5
`
`Small device rendering 30
`Desktop rendering 30
`Screen-specific style sheet 31
`Print-specific style sheet 31
`iPhone running on iPhone OS 2.0 user agent string 31
`iPod touch running iPhone OS 1.1.3 user agent string 32
`iPhone running iPhone OS 1.0 user agent string 32
`
`Chapter 3
`
`Configuring the Viewport 33
`
`Figure 3-1
`Figure 3-2
`Figure 3-3
`Figure 3-4
`Figure 3-5
`Figure 3-6
`Figure 3-7
`Figure 3-8
`Figure 3-9
`Figure 3-10
`Figure 3-11
`Figure 3-12
`Figure 3-13
`Figure 3-14
`Figure 3-15
`Figure 3-16
`Figure 3-17
`Figure 3-18
`Figure 3-19
`
`Layout and metrics in portrait orientation 34
`Differences between Safari on iPhone OS and Safari on the desktop 35
`Safari on desktop viewport 36
`Viewport with default settings 37
`Viewport with width set to 320 37
`Viewport with width set to 320 and scale set to 150% 38
`Viewport with width set to 320 and scale set to 50% 39
`Viewport with arbitrary user scale 39
`Default settings work well for most webpages 40
`Comparison of 320 and 980 viewport widths 42
`Webpage is too narrow for default settings 43
`Web application page is too small for default settings 44
`Default width and initial scale 45
`Default width with initial scale set to 1.0 45
`Width set to 320 with default initial scale 46
`Width set to 200 with default initial scale 46
`Width set to 980 and initial scale set to 1.0 47
`Not specifying viewport properties 48
`Width set to device-width pixels 48
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`7
`
`SV0134989
`
`

`

`FIGURES, TABLES, AND LISTINGS
`
`Chapter 4
`
`Customizing Style Sheets 51
`
`Figure 4-1
`Figure 4-2
`Listing 4-1
`Listing 4-2
`
`Comparison of text adjustment settings 52
`Differences between default and custom highlighting 53
`Setting the text size adjustment property 52
`Changing the tap highlight color 53
`
`Chapter 5
`
`Designing Forms 55
`
`Figure 5-1
`Figure 5-2
`Figure 5-3
`Figure 5-4
`Table 5-1
`Table 5-2
`Listing 5-1
`Listing 5-2
`Listing 5-3
`
`Form metrics when the keyboard is displayed 56
`A custom checkbox 57
`A custom text field 58
`A custom select element 58
`Form metrics 56
`Automatic correction and capitalization attributes 59
`Creating a custom checkbox with CSS 57
`Creating a custom text field with CSS 58
`Creating a custom select control with CSS 59
`
`Chapter 6
`
`Handling Events 61
`
`Figure 6-1
`Figure 6-2
`Figure 6-3
`Figure 6-4
`Figure 6-5
`Figure 6-6
`Table 6-1
`Listing 6-1
`Listing 6-2
`Listing 6-3
`
`The panning gesture 62
`The touch and hold gesture 62
`The double-tap gesture 63
`One-finger gesture emulating a mouse 64
`The pinch open gesture 64
`Two-finger panning gesture 65
`Types of events 71
`A menu using a mouseover handler 65
`Adding an onclick handler 66
`Displaying the orientation 70
`
`Chapter 8
`
`Creating Video 75
`
`Figure 8-1
`Figure 8-2
`Table 8-1
`
`Export movie panel 77
`Reference movie components 78
`File name extensions for MIME types 79
`
`Chapter 9
`
`Storing Data on the Client 81
`
`Listing 9-1
`
`Sample manifest file 81
`
`Chapter 11
`
`Debugging 87
`
`Figure 11-1
`
`Selecting Developer settings 87
`
`8
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`SV0134990
`
`

`

`FIGURES, TABLES, AND LISTINGS
`
`Figure 11-2
`Figure 11-3
`Figure 11-4
`Figure 11-5
`Figure 11-6
`Figure 11-7
`Figure 11-8
`
`Enabling the debug console 88
`The message banner 89
`Messages in the console 89
`Filtered console messages 90
`Viewport width or height tip 90
`JavaScript timeout message 91
`Console messages from your JavaScript code 92
`
`Appendix A
`
`HTML Basics 93
`
`Listing A-1
`Listing A-2
`Listing A-3
`Listing A-4
`Listing A-5
`Listing A-6
`
`Basic HTML document 93
`Adding a paragraph 95
`Adding a heading 95
`Creating a hyperlink 95
`Adding an image 96
`Creating a table 97
`
`Appendix B
`
`CSS Basics 99
`
`Listing B-1
`
`The styles.css file 101
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`9
`
`SV0134991
`
`

`

`FIGURES, TABLES, AND LISTINGS
`
`10
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`SV0134992
`
`

`

`INTRODUCTION
`
`Introduction
`
`Safari runs on multiple platforms. All versions of Safari-Safari on the desktop and Safari on iPhone OS-use
`the same WebKit engine. Therefore, web content intended for the desktop might work well on iPhone without
`any modifications. Some differences exist, however, so at a minimum you should ensure that your webpages
`are compatible with Safari on iPhone OS. Next, you might optimize your webpages for iPhone OS simply as
`a convenience to the user. For example, ensure that your webpages work over both Wi-Fi and EDGE, scale
`correctly when rendered, and contain media that is viewable on iPhone OS. Finally, you might build custom
`web applications for either platform that look and behave like native applications.
`
`Safari on the desktop is available for Mac OS X and Windows. It is a full-featured web browser for the desktop
`that supports industry standards as well as many WebKit extensions. In addition, it includes a number of
`tools that developers can use to analyze, test, and debug websites and web applications.
`
`Safari on iPhone OS, the application for browsing the web on iPhone and iPod touch, is also a full web browser
`running on a small handheld device with a high-resolution screen. This unique implementation of Safari
`responds to a finger as the input device and supports gestures for zooming and panning. It also renders
`webpages in portrait or landscape orientation. It contains many built-in features such as PDF viewing, video
`playback, and support for links to the native Phone, Mail, Maps, and You Tube applications.
`
`The WebKit is an open source project as well as a framework in Mac OS X that lets developers embed a web
`browser in their Cocoa applications. The WebKit has a JavaScript and Objective-( interface to access the
`Document Object Model (DOM) of a webpage. Dashboard, Mail, and many other Mac OS X applications also
`use the WebKit as an embedded browser. You can use the U I Web View class in UIKit on iPhone OS to embed
`a web browser in an iPhone application.
`
`In addition to providing browser functionality, the WebKit also implements some extensions to HTML, CSS,
`and JavaScript, including several specific to Safari. Safari extensions include CSS animation and transform
`properties, and JavaScript database support. Safari on iPhone OS includes JavaScript multi-touch event
`support.
`
`This document teaches you how to create web content compatible with Safari running on any platform and
`how to separate your iPhone OS-specific web content from your other web content so that when you optimize
`your web content for iPhone OS, it still works on the desktop and other browsers. This document also covers
`some basics on tailoring web applications for iPhone OS.
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`11
`
`SV0134993
`
`

`

`CHAPTER6
`
`Handling Events
`
`Figure 6-1
`
`The panning gesture
`
`Finger down
`
`Finger move
`
`Pan (no events)
`
`Finger stop
`
`on scroll
`
`Displaying the information bubble doesn't generate any events as shown in Figure 6-2. However, if the user
`touches and holds an image, the image save sheet appears instead of an information bubble.
`
`iPhone OS Note: The image save sheet appears on iPhone OS 2.0 and later.
`
`Figure 6-2
`
`The touch and hold gesture
`
`Finger held down
`
`Information bubble
`(no events)
`
`Finally, a double tap doesn't generate any events either as shown in Figure 6-3.
`
`62
`
`One-Finger Events
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`SV0135044
`
`

`

`CHAPTER6
`
`Handling Events
`
`Figure 6-3
`
`The double-tap gesture
`
`Mouse events are delivered in the same order you'd expect in other web browsers illustrated in Figure 6-4.
`If the user taps a nonclickable element, no events are generated. If the user taps a clickable element, events
`arrive in this order: mouseover, mousemove, mousedown, mouse up, and click. The mouseout event occurs
`only if the user taps on another clickable item. Also, ifthe contents of the page changes on the mousemove
`event, no subsequent events in the sequence are sent. This behavior allows the user to tap in the new content.
`
`One-Finger Events
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`63
`
`SV0135045
`
`

`

`CHAPTER6
`
`Handling Events
`
`Figure 6-4
`
`One-finger gesture emulating a mouse
`
`Not a clickable
`element
`
`>----------11 No events I
`
`Finger up· ·
`
`Clickable element
`
`1--c_o_nt_e_nt_c_h_a_ng_e-~1~ H~~ ~~~~t~ HI
`mouseover, mousemove
`~----r----~
`
`No content change
`
`( mousedown, mouseup, click )
`
`Two-Finger Events
`
`The pinch open gesture does not generate any mouse events as shown in Figure 6-5.
`
`Figure 6-5
`
`The pinch open gesture
`
`Fingers separate
`
`Two fingers down
`
`Figure 6-6 illustrates the mouse events generated by using two fingers to pan a scrollable element. The flow
`of events is as follows:
`
`•
`
`•
`
`If the user holds two fingers down on a scrollable element and moves the fingers, mo us ewh eel events
`are generated.
`
`If the element is not scrollable, Safari on iPhone OS pans the webpage. No events are generated while
`panning.
`
`• An on s c r o l l event is generated when the user stops panning.
`
`64
`
`Two-Finger Events
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`SV0135046
`
`

`

`CHAPTER6
`
`Handling Events
`
`Figure 6-6
`
`Two-finger panning gesture
`
`Scrollable element
`(
`>-----':..:..;,c:..;;.::.;:.;.:_..:..;.:.;,;.;.:.."-'---1 mousewheel
`
`)
`
`Two fingers move
`
`Not a scrollable element
`
`Pan (no events)
`
`Finger stop
`
`.. onscrou .. J
`
`Form and Document Events
`
`Typical events generated by forms and documents include b l u r, foe us, l oa d, u n l oa d, reset, submit,
`e hang e and abort. See "Supported Events" (page 71) for a complete list of supported events on iPhone
`OS.
`
`Making Elements Clickable
`
`Because of the way Safari on iPhone OS creates events to emulate a mouse, some of your elements may not
`behave as expected on iPhone OS. In particular, some menus that only use mousemove handlers, as in Listing
`6-1, need to be changed because iPhone OS doesn't recognize them as clickable elements.
`
`Listing 6-1
`
`A menu using a mouseover handler
`
`<span onmouseover =
`onmouseout
`
`" . . . "
`
`WHERE TO BUY
`
`<!span>
`
`To fix this, add a dummy one lie k handler, one l i e k = "void ( 0) ",so that Safari on iPhone OS recognizes
`the span element as a clickable element, as shown in Listing 6-2.
`
`Form and Document Events
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`65
`
`SV0135047
`
`

`

`CHAPTER6
`
`Handling Events
`
`Listing 6-2
`
`Adding an onclick handler
`
`<span onmouseover = " ... "
`onmouseout
`onclick = "void(Ol">
`
`WHERE TO BUY
`
`<!span>
`
`Handling Multi-Touch Events
`
`You can use JavaScript DOM touch event classes available on iPhone OS to handle multi-touch and gesture
`events in a way similar to the way they are handled in native iPhone OS applications.
`
`If you register for multi-touch events, the system continually sends Touch Event objects to those DOM
`elements as fingers touch and move across a surface. These are sent in addition to the emulated mouse
`events unless you prevent this default behavior as described in "Preventing Default Behavior" (page 69). A
`touch event provides a snapshot of all touches during a multi-touch sequence, most importantly the touches
`that are new or have changed for a particular target. The different types of multi-touch events are described
`in Touch Event in Safari DOM Extensions Reference.
`
`A multi-touch sequence begins when a finger first touches the surface. Other fingers may subsequently touch
`the surface, and all fingers may move across the surface. The sequence ends when the last of these fingers
`is lifted from the surface. An application receives touch event objects during each phase of any touch.
`
`Touch events are similar to mouse events except that you can have simultaneous touches on the screen at
`different locations. A touch event object is used to encapsulate all the touches that are currently on the
`screen. Each finger is represented by a touch object. The typical properties that you find in a mouse event
`are in the touch object, not the touch event object.
`
`Note that a sequence of touch events is delivered to the element that received the original touch start
`event regardless of the current location of the touches.
`
`Follow these steps to use multi-touch events in your web application.
`
`1. Register handlers for multi-touch events in HTML as follows:
`
`<div
`ontouchstart="touchStart(event);"
`ontouchmove="touchMove(event);"
`ontouchend="touchEnd(event);"
`ontouchcancel="touchCancel (event);"
`><ldiv>
`
`2. Alternatively, register handlers in JavaScript as follows:
`
`element.addEventlistener("touchstart", touchStart, false);
`element.addEventlistener("touchmove", touchMove, false);
`element.addEventlistener("touchend", touchEnd, false);
`element.addEventlistener("touchcancel ", touchCancel, false);
`
`3. Respond to multi-touch events by implementing handlers in JavaScript.
`
`66
`
`Handling Multi-Touch Events
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`SV0135048
`
`

`

`REVISION HISTORY
`
`Document Revision History
`
`This table describes the changes to Safari Web Content Guide.
`
`Date
`
`2009-06-08
`
`2009-03-05
`
`2009-01-30
`
`2009-01-06
`
`2008-11-17
`
`2008-10-15
`
`2008-09-09
`
`2008-07-15
`
`2008-02-05
`
`2008-01-15
`
`2007-10-31
`
`2007-10-11
`
`2007-09-27
`
`2005-08-11
`
`2005-06-04
`
`Notes
`
`Changed the title from "Safari Web Content Guide for iPhone OS" and applied
`minor edits throughout.
`
`Minor edits throughout.
`
`Minor edits throughout.
`
`Moved appendix to separate book called Apple URL Scheme Reference. Removed
`redundant reference now included in the Safari HTML Reference and Safari DOM
`Extensions Reference books.
`
`Added the chapter "Storing Data on the Client."
`
`Minor edits throughout.
`
`Updated for iPhone OS 2.1.
`
`Updated for iPhone OS 2.0.
`
`Updated book link in "Specifying a Webpage Icon for Web Clip".
`
`Added section on specifying a web clip icon.
`
`Added instructions for exporting movies for iPhone using Quicktime Pro 7.2.1.
`
`Added figures to the "Customizing Style Sheets" and "Debugging" articles.
`Removed the "Configuring Keyboard" section from "Designing Forms" because
`using the lang property to select keyboard languages is deprecated.
`
`Changed the title from Safari Web Content Guide. Completely revised to describe
`how to create web content for Safari on the desktop and Safari on iPhone using
`Web 2.0 technologies.
`
`Corrected typos.
`
`New document that discusses creating effective web content for Safari and the
`Web Kit.
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`103
`
`SV0135085
`
`

`

`REVISION HISTORY
`
`Document Revision History
`
`104
`
`2009-06-08 I © 2009 Apple Inc. All Rights Reserved.
`
`SV0135086
`
`