Dashcode_UserGuide.pdf

Loading ...
Global Do...
News & Politics
Dashcode User Guide
Development Environments: Dashcode
2009-07-24
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, Dashcode, iCal, iPhoto,
iPod, Mac, Mac OS, Monaco, Objective-C,
Quartz, QuickTime, Safari, and Xcode are
trademarks of Apple Inc., registered in the
United States and other countries.
Finder, iPhone, and MobileMe are trademarks
of Apple Inc.
Adobe, Acrobat, and PostScript are trademarks
or registered trademarks of Adobe Systems
Incorporated in the U.S. and/or other countries.
Helvetica and Times are registered trademarks
of Heidelberger Druckmaschinen AG, available
from Linotype Library GmbH.
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.
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
DEFECT OR INACCURACY IN THIS DOCUMENT, even
if advised of the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH 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.
Contents
Introduction
Introduction to Dashcode User Guide 9
Who Should Read This Document? 9
Organization of This Document 9
Getting and Running Dashcode 10
Reporting Bugs 10
See Also 10
Chapter 1
Dashboard Widget Tutorial 13
Before You Begin 13
Choose a Template 13
Set the Target Date 15
Test the Countdown 15
Customize the Widget’s Appearance 16
Add Functionality Using Parts 17
Write Code to Show the Apple Store 17
Deploy Your Widget 18
Chapter 2
Mobile Safari Web Application Tutorial 19
Before You Begin 19
Choose a Template 19
Learn About the Template 21
Test the Default Product 21
Explore the Views in the Stack Layout 22
Add Functionality Using Parts 23
Write Code to Perform a Search 24
Deploy Your Mobile Safari Web Application 25
Chapter 3
Dual-Product Web Application Tutorial 27
Before You Begin 27
Choose a Template 29
Save and Test the Default Web Applications 31
Customize the User Interface of the Safari Web Application 33
Specify a Data Source and Examine the Data Model 35
Create Bindings for the Safari Web Application 37
Create the First Binding 37
Create the Remaining Bindings 39
Test the Safari Web Application 40
Customize the User Interface of the Mobile Safari Web Application 40
3
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
Create Bindings for the Mobile Safari Web Application 41
Create a Binding to an Element on the Master List Page 42
Create Four Bindings to Elements on the Detail Page 42
Test the Mobile Safari Web Application 43
Next Steps 43
Chapter 4
Starting a Project 45
Creating a Project from a Template 45
Creating a Project from an Existing Dashboard Widget 45
Providing Attributes for a Dashboard Widget 46
Providing Attributes for a Web Application 46
Application Attributes for Safari Web Applications 47
Application Attributes for Mobile Safari Web Applications 47
Opening an Existing Dashboard Widget 49
Chapter 5
Designing the User Interface of a Widget or Web Application 51
Laying Out the Interface 51
Showing a Widget’s Sides 51
Adding Parts to an Interface 51
Using Photos from iPhoto 52
Changing an Element’s Properties 52
Arranging and Locking Elements 53
Absolute versus Document-Flow Positioning 54
Searching for Elements 54
Rulers and Guides 55
Placing a Widget’s Close Box 55
Disabling the Canvas 55
Previewing a Widget’s Default Image 55
Designing a Widget Icon 56
Designing a Web Clip Icon 56
Designing a Favicon 57
Chapter 6
Adding Source Code and Creating Bindings 59
Viewing a Project’s Source Code 59
Viewing a Project’s Data Sources and Bindings 60
Using HTML, CSS, and JavaScript Programming Interfaces 61
Adding a Data Source 62
Creating Bindings 63
Adding a Value Transformer 64
Adding a Handler for an Event 65
Supporting Offline Usage of a Web Application 65
Adding or Removing a Web Application Product 66
Adding Code for Custom Controllers 66
4
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CONTENTS
Code Completion Using Code Sense 67
Code Snippets 67
Adding and Moving Files and Folders 67
Resource Access for Widgets 68
Code Editing Preferences 69
Chapter 7
Testing and Sharing 71
Testing a Widget or a Web Application 71
The Run Log and Tracing Execution 73
Pausing and Step-by-Step Execution 73
Checking Values in Memory 74
Breakpoints 74
The Code Evaluator 74
Sharing a Widget 75
Deploying a Web Application 75
Chapter 8
Advanced Topics for Widgets 77
Localization 77
Widget Plug-ins 77
Appendix A
Dashcode Templates 79
Widget Templates 79
The Custom Widget Template 79
The Countdown Template 79
The Maps Template 80
The RSS Widget Template 80
The Podcast Widget Template 80
The Photocast Template 81
The Quartz Composer Template 81
The Video Podcast Template 81
The Gauge Template 82
The Daily Feed Template 82
Web Application Templates 82
The Custom Web Application Template 83
The Browser Template 83
The Podcast Web Application Template 83
The RSS Web Application Template 83
The Utility Template 84
Appendix B
Dashcode Parts 85
Activity Indicator 85
Back Button 85
5
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CONTENTS
Box 86
Browser 86
Canvas 86
Call Button 86
Column Layout 87
Edge-to-Edge List 87
Forward Button 88
Gauge 88
Grid 88
Image 88
Indicator 88
Level Indicators 89
Mail Button 89
Map Button 89
Quartz Composer 90
QuickTime 90
Rounded-Rectangle List 90
Split Layout 91
Stack Layout 91
Stack Layout Methods 91
Stack Layout Transitions 92
Video 94
Document Revision History 95
6
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CONTENTS
Figures
Chapter 1
Dashboard Widget Tutorial 13
Figure 1-1
The Birthday widget 13
Figure 1-2
A project window showing a new Dashboard widget 14
Figure 1-3
The Countdown template’s properties 15
Figure 1-4
Tweaking the front image using the Fill & Stroke inspector 16
Figure 1-5
A function in the source code editor 17
Chapter 2
Mobile Safari Web Application Tutorial 19
Figure 2-1
A new mobile Safari web application project based on the Browser template 20
Figure 2-2
The default Browser-based mobile Safari web application contains a top-level page
(left) and a detail page (right) 22
Figure 2-3
Adding a part to the mobile Safari web application’s user interface 24
Figure 2-4
Adding code to handle the button’s click event 25
Chapter 3
Dual-Product Web Application Tutorial 27
Figure 3-1
The finished products: Safari web application (top) and mobile Safari web application
(bottom) 28
Figure 3-2
A new dual-product project 30
Figure 3-3
The default Safari web application running in the Dashcode simulator application
31
Figure 3-4
The default mobile Safari web application running in the iPhone Simulator 32
Figure 3-5
In the navigator, drag the image element into the detailBox element 34
Figure 3-6
The canvas of the Safari web application after the new parts are added 35
Figure 3-7
Completed bindings and binding controls are visible in the data model 36
Figure 3-8
Dashcode displays a blue connection line between a data source property and an
element on the canvas 38
Figure 3-9
The canvas of the mobile Safari web application after the Image part is added to
the detail page 41
7
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
8
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
FIGURES
This document provides an overview of the Dashcode development environment. It describes how to use
Dashcode to create two types of projects:
 ■ Dashboard widgets—simple, lightweight applications that perform a single task in the Mac OS X
Dashboard environment. Widgets are actually packaged webpages powered by standard web technologies
such as Hypertext Markup Language (HTML), Cascading Style Sheets (CSS), and JavaScript.
 ■ Web applications—webpages that provide discrete functionality to users. Web applications also make
use of web technologies such as HTML, CSS, and JavaScript. Dashcode helps you create mobile Safari
web applications, which are also known as iPhone web applications (that is, web applications optimized
to run in Safari on iPhone), and Safari web applications (that is, web applications optimized to run in
Safari).
Dashcode’s integrated environment allows you to lay out, code, and even test widgets and web applications
without opening any other applications. Its layout tools, composers, and editors simplify the process of
creating all the resources these projects need. Dashcode also includes handy coding and debugging tools
that help you manage and test the code you write.
Who Should Read This Document?
Read Dashcode User Guide to learn how to use Dashcode to create web applications and Dashboard widgets.
Developers who are new to either widget or web application creation learn how to build simple projects and
find out more about Dashcode’s capabilities. Experienced developers learn how to speed up development
using Dashcode.
Organization of This Document
This document contains the following chapters:
 ■
“Dashboard Widget Tutorial” (page 13) walks you through creating your first Dashboard widget with
Dashcode.
 ■
“Mobile Safari Web Application Tutorial” (page 19) shows you how to create a simple mobile Safari web
application with Dashcode.
 ■
“Dual-Product Web Application Tutorial” (page 27) shows you how to create a project that produces
both a mobile Safari web application and a Safari web application.
 ■
“Starting a Project” (page 45) discusses the different starting points when working with Dashcode.
 ■
“Designing the User Interface of a Widget or Web Application” (page 51) shows you the tools Dashcode
provides for designing the user interface of a widget or web application.
Who Should Read This Document?
9
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
INTRODUCTION
Introduction to Dashcode User Guide
 ■
“Adding Source Code and Creating Bindings” (page 59) details the source code editing tools included
with Dashcode.
 ■
“Testing and Sharing” (page 71) includes information on testing, debugging, and distributing a widget
or web application.
 ■
“Advanced Topics for Widgets” (page 77) talks about localizing a widget using Dashcode and including
a widget plug-in.
Dashcode User Guide also includes these appendixes:
 ■
“Dashcode Templates” (page 79) describes the project templates included with Dashcode.
 ■
“Dashcode Parts” (page 85) includes information on Dashcode-originated elements, called parts, and
how to customize them.
Getting and Running Dashcode
Apple provides a comprehensive suite of developer tools (including Dashcode) for creating Mac OS X software
on a Mac. The Xcode tools include applications to help you design, create, debug, and optimize your software.
This tools suite also includes header files, sample code, and documentation for Apple technologies. You can
download the Xcode tools from the Apple Developer Connection (ADC) website (http://developer.apple.com).
Registration is required, but free.
After you download the Xcode tools, use the Xcode tools installer to install Dashcode on your Mac. After
installation, you’ll find Dashcode in /Developer/Applications/.
Reporting Bugs
If you encounter bugs in Apple software or documentation, you are encouraged to report them to Apple.
You can also file enhancement requests to describe features you would like to see in future revisions of a
product or document. To file bugs or enhancement requests, go to the Bug Reporting page of the ADC
website, which is at the following URL:
http://developer.apple.com/bugreporter/
You must have a valid ADC login name and password to file bugs. You can obtain a login name for free by
following the instructions found on the Bug Reporting page. To file a bug for Dashcode, use the Dashcode
component, version X.
See Also
For in-depth information on how to create web applications that work well on iPhone and iPod touch, see
SafariWebContent Guide. For guidance on how to design the user interface of such an application, see iPhone
Human Interface Guidelines for Web Applications.
10
Getting and Running Dashcode
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
INTRODUCTION
Introduction to Dashcode User Guide
Read Dashboard Programming Topics for information on the technologies available to you when creating a
Dashboard widget. All of the Dashboard-specific information discussed in this document is covered in more
depth in Dashboard Reference. Additional Dashboard documents and sample code can be found on the ADC
topic page for Dashcode.
The Safari Dev Center contains useful information on WebKit, the technology that powers Dashboard widgets,
and other Safari-related topics. For more information on the HTML, CSS, and JavaScript capabilities found in
WebKit, consult:
 ■
Safari HTML Reference
 ■
Safari CSS Reference
 ■
Safari DOM Extensions Reference
The XMLHttpRequest object allows you to parse XML in JavaScript and use the results. Read the ADC article
Dynamic HTML and XML: The XMLHttpRequest Object for more information.
See Also
11
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
INTRODUCTION
Introduction to Dashcode User Guide
12
See Also
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
INTRODUCTION
Introduction to Dashcode User Guide
This tutorial walks you through using Dashcode to create a Dashboard widget. As you follow the steps, you
learn how to choose a widget template, customize your widget’s appearance and code, and share your
widget with others. Completing this tutorial is a quick and easy way to get started building Dashboard widgets
in Dashcode.
This document includes two additional tutorials, “Mobile Safari Web Application Tutorial” (page 19) and
“Dual-Product Web Application Tutorial” (page 27), which follow this one. The remainder of the document
delves more deeply into the Dashcode development environment, describing how it supports both widget
and web application development. If you don’t want to learn how to create a web application, you can
continue learning more about Dashcode by reading “Starting a Project” (page 45).
Before You Begin
In this tutorial, you build a Dashboard widget that counts down to your birthday, similar to the widget shown
in Figure 1-1.
Figure 1-1
The Birthday widget
Before continuing, make sure that you have Dashcode installed on your Mac (the location is
/Developer/Applications/). If you don’t have Dashcode installed, read “Getting and Running
Dashcode” (page 10) to learn how to get and install Dashcode.
Choose a Template
To start, double-click the Dashcode icon to open it. A new project window opens and displays a dialog in
which you first select the type of project you’re interested in—in this case, Dashboard—and then, the kind
of widget you want to create from an assortment of templates. Templates are handy starting points for
creating common types of widgets. Select a template’s icon to show a short description of what that template
does.
To make the Birthday widget, this tutorial uses the Countdown template. Select its icon and click Choose. A
project window opens with a new widget based on the Countdown template, as shown in Figure 1-2.
Before You Begin
13
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 1
Dashboard Widget Tutorial
Figure 1-2
A project window showing a new Dashboard widget
Along the left side of the project window is the navigator, which you use to switch between the various
tools available when you’re designing a widget. The main portion of the window is the canvas, which you
use to design your widget’s interface.
At the bottom of the navigator in Figure 1-2 you can see the Workflow Steps list, which guides you through
the widget development process. Each step is a milestone in creating a widget, telling you what to do and
where to do it. When you complete a step, mark it as done and move on to the next step.
14
Choose a Template
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 1
Dashboard Widget Tutorial
Note:  If you don’t want to see the Workflow Steps list, you can hide it by choosing View > Steps or by clicking
the button that looks like a checkbox at the bottom edge of the project window (this button is highlighted
in Figure 1-2).
Alternatively, you can view a list of the widget’s files in place of the Workflow Steps list. If you want to see
the Files list, choose View > Files or click the list button in the bottom edge of the project window (it’s the
button that looks like a bulleted list).
Set the Target Date
The Countdown template gives you a Dashboard widget with all the elements and code needed to count
down to an event. All you need to do is tell the widget the target date. To set the target date, select Widget
Attributes in the navigator. The canvas is replaced by the widget attributes pane, in which you specify
important values that your widget needs.
In the Properties section of the widget attributes pane, choose Date and Time in the Target Kind pop-up
menu and enter the date of your next birthday, as shown in Figure 1-3.
Figure 1-3
The Countdown template’s properties
Test the Countdown
Your new Dashboard widget is already fully functional. To prove this, choose Debug > Run to run the widget.
Dashcode can run a widget without opening it in Dashboard, making it a handy place to test your widget
and fix any problems you encounter. After the widget loads, it starts counting down towards your next
birthday.
When you’re satisfied that your widget is working as you expect, choose Debug > Stop to stop it.
Now is a good time to save your widget project. Choose File > Save to save the project. Give your project a
name and select a location to save it in. Your widget is saved in a widget project that encapsulates the widget
and information Dashcode needs to create the widget for you.
Set the Target Date
15
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 1
Dashboard Widget Tutorial
Customize the Widget’s Appearance
Although you now have a fully functioning Dashboard widget that’s ready to share, you might want to
personalize it to make it unique. Dashcode’s design tools make it easy to customize your widget’s interface.
Select the widget item in the navigator (it should display the name you gave it when you saved the project).
The widget attributes pane is replaced with the canvas.
First, change your widget’s body color. Select the widget body (also called the front image or frontImg) on
the canvas and then choose Window > Show Inspector. The inspector window allows you to modify a
selected element’s properties, such as its appearance and behavior. Click the Fill & Stroke button at the top
of the inspector window (it’s the second from the left). If it’s not already selected, click the Style tab to reveal
fill, stroke, corner roundness, and opacity values. Click the color well and choose a new color in the Colors
window that appears. Try different fill styles until you find a combination that you like. If you want to try
changing other effects, such as the glass appearance, click the Effects tab to reveal these values, as shown
in Figure 1-4.
Figure 1-4
Tweaking the front image using the Fill & Stroke inspector
When you’re finished customizing your widget’s body, add a photo of yourself from iPhoto to the widget.
Your iPhoto library is available from the Library window. To show your iPhoto library, choose Window >
Show Library; then click the Photos button. Find a photo and drag it to your widget on the canvas. Resize it
by dragging any of the resize handles on the photo.
Finally, change the Event Label text to something like “...days until my birthday.“ You can do this by selecting
the Event Label text, clicking the Attributes button in the inspector window (it’s the leftmost button), and
entering the text in the Value field, or by double-clicking the text in the widget body itself and entering the
new text.
16
Customize the Widget’s Appearance
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 1
Dashboard Widget Tutorial
Add Functionality Using Parts
Now that you have a personalized Dashboard widget that counts down to your birthday, add a button that,
when clicked, shows the Apple Store (so your friends and family can buy you a birthday present!). To add a
button to your widget, use a button part. Parts are controls and views used on a widget’s interface.
To find a button part, choose Window > Show Library and click Parts. You can use the search field at the
bottom of the window to help you find a particular part or type of part. From the list of parts, drag the
Lozenge Button part from the Library window to your widget’s body. Double-click the button to select its
label text, enter the text “Buy me a gift” and press Return. You'll probably need to resize the button to fit the
new label.
Write Code to Show the Apple Store
To make the button take the user to the Apple Store when it’s clicked, you need to add a behavior to the
button. In the inspector window, click the Behaviors button (it’s the rightmost button). This shows the
Behaviors pane, in which you assign handler functions to events on an object. Select the button on the canvas
and double-click in the Handlers column next to the onclick event name. Enter the name of a new function,
such as showAppleStore, and press Return. Click the arrow next to the function name you entered to reveal
the source code editor below the canvas. Here you write code to add functionality to your widget. Clicking
the arrow reveals the showAppleStore function Dashcode inserted in your widget’s code. Between the
braces ({ .. }) enter the following line of code:
widget.openURL("http://store.apple.com/");
The code in the source code editor should look like that in Figure 1-5.
Figure 1-5
A function in the source code editor
Add Functionality Using Parts
17
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 1
Dashboard Widget Tutorial
Test your widget again by choosing Debug > Run. Click the button you added and make sure a new Safari
window opens with the Apple Store website displayed. Be sure you save your project often to preserve the
changes you make.
Deploy Your Widget
Congratulations! You’ve created your first complete Dashboard widget using Dashcode.
To open your widget in Dashboard, choose File > Deploy Widget. Click Install in the dialog that appears to
view your widget in Dashboard.
To share your widget with the world, select Run & Share in the navigator. The pane that appears displays the
widget project name you chose in “Test the Countdown” (page 15), but you can replace this with a different
name if you want. You can also set the minimum version of Mac OS X your widget should run in. Click Save
to Disk to save your widget. You can now email it to friends or post it on your webpage. You can use the File
> Compress command in the Finder to archive it.
18
Deploy Your Widget
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 1
Dashboard Widget Tutorial
This tutorial walks you through using Dashcode to create project that produces a mobile Safari web application.
A mobile Safari web application (also known as an iPhone web application) is web content that is optimized
for Safari on iPhone and that offers users an application-like experience. As you follow the steps, you learn
how to choose a template, customize your code, and share your application with others. Completing this
tutorial is a quick and easy way to get started building mobile Safari web applications in Dashcode.
This is the second of three tutorials in this document. If you’re interested in learning how to start developing
Dashboard widgets, be sure to read “Dashboard Widget Tutorial” (page 13). If you want to learn how to
create a project that produces both a mobile Safari web application and a Safari web application, read
“Dual-Product Web Application Tutorial” (page 27). The remainder of the document, beginning with “Starting
a Project” (page 45), delves more deeply into the Dashcode development environment, describing how it
supports both widget and web application development.
Before You Begin
In this tutorial, you build a mobile Safari web application that displays information about national parks. This
project is based on the browser type of web application, and supports navigation through multiple levels of
content.
Before continuing, make sure that you have Dashcode version 3.0 or later installed on your Mac (the install
location is /Developer/Applications/). If you don’t have Dashcode installed, read “Getting and Running
Dashcode” (page 10) to learn how to get and install Dashcode.
Choose a Template
To start, double-click the Dashcode icon to open it. A new project window opens and displays a dialog that
displays two types of projects—Safari and Dashboard—and an assortment of templates for each project
type. Templates are handy starting points for creating common types of web applications and widgets. (To
find out what a template does, select it to show a short description of its capabilities.)
For this tutorial, select the Safari project type. Then, to create a browser-type web application that’s optimized
to run in Safari on iPhone:
1.
Select the Browser template.
2. Click the “Develop for: Safari” checkbox to deselect it. (Make sure the “Develop for: Mobile Safari” checkbox
is still selected.)
3. Click Choose.
Before You Begin
19
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 2
Mobile Safari Web Application Tutorial
A project window opens, displaying the first page of a new mobile Safari web application based on the
Browser template, as shown in Figure 2-1.
Figure 2-1
A new mobile Safari web application project based on the Browser template
Along the left side of the project window is the navigator, which you use to switch between the various
tools available when you’re designing a web application. The main portion of the window is the canvas,
which you use to design your web application’s interface.
At the bottom of the navigator in Figure 2-1 you can see the Workflow Steps list, which guides you through
the web application development process. Each step is a milestone in creating a web application, telling you
what to do and where to do it. When you complete a step, mark it as done and move on to the next step.
20
Choose a Template
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 2
Mobile Safari Web Application Tutorial
Note:  If you don’t want to see the Workflow Steps list, you can hide it by choosing View > Steps or by clicking
the button that looks like a checkbox at the bottom edge of the project window (this button is highlighted
in Figure 2-1).
Alternatively, you can view a list of the web application’s files in place of the Workflow Steps list. If you want
to see the Files list, choose View > Files or click the list button in the bottom edge of the project window (it’s
the button that looks like a bulleted list).
Learn About the Template
The Browser template gives you a mobile Safari web application that displays some built-in information and
supports navigating from one page to the next. You don’t need to customize the application at all to see
how it works, but you should specify a title to display.
In the canvas, double-click Browser and type in a new title, such as Parks. You’ll see this title in the header
of the first page.
You should also give a name to the webpage itself. When you begin a project, this name is Untitled. To specify
a name, double-click Untitled at the top of the navigator and type the name you want, say, National Parks.
Now is also a good time to save your project. Choose File > Save to save the project. Give your project a
name and select a location to save it in. The project encapsulates the web application and all the information
Dashcode needs to create it for you.
Test the Default Product
Your new mobile Safari web application is already functional, even though it only displays placeholder data.
To prove this, click the green Run button in the Dashcode toolbar (alternatively, you can choose Debug >
Run).
Dashcode opens your web application in a simulator application.
Note:  If you've installed the iPhone SDK on your computer, Dashcode opens the mobile Safari web application
in the iPhone Simulator application provided by the SDK. If you do not have the iPhone SDK installed on
your computer, Dashcode opens the mobile Safari web application in its own simulator application.
Take a few moments to use the application. You should see Parks (or a different title you typed in) displayed
in the header of the first page and you should see National Parks (or a different title you gave the webpage)
in the title bar area, if this area is visible.
Notice that when you click a row item in the first page, a new page appears that gives details about the item.
There are a few other things you should notice about the second page:
 ■ The title of the second page is the same as the name of the row item you selected in the first page.
 ■ A back button has appeared to the left of the title and its label is Parks, which is the title of the first page.
You can click this button to return to the first page.
Learn About the Template
21
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 2
Mobile Safari Web Application Tutorial
 ■ The text in the middle of the second page includes the name of the row item you selected.
The two pages of your web application should look similar to those shown in Figure 2-2.
Figure 2-2
The default Browser-based mobile Safari web application contains a top-level page (left) and
a detail page (right)
Although the information about national parks is just placeholder information provided by the Browser
template, it helps you see some of the connections between the pages. You’ll learn a bit more about these
connections in the next step, “Explore the Views in the Stack Layout” (page 22).
Before you continue, quit the simulation by choosing Quit from the simulation application menu or pressing
Command-Q. Or, in Dashcode, you can click the red Stop button.
Explore the Views in the Stack Layout
A browser-style mobile Safari web application allows users to navigate from one page to the next. As you
found out when you tested it, your web application already supports the ability to select an item in the
top-level list and reveal information about it in a detail view. One of the keys to this structure is the stack
layout.
If you can’t already see it in the navigator, reveal the stack layout by clicking the disclosure triangles next to
National Parks and, below that, next to browser. When you click the disclosure triangle next to stackLayout,
you see two items: listLevel and detailLevel. In this application, the list level view contains the list of
parks, and the detail level view contains the text that describes a selected park.
You can change the way the detail page is revealed when you select a row in the top-level list. To do this,
follow these steps:
22
Explore the Views in the Stack Layout
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 2
Mobile Safari Web Application Tutorial
1. Make sure the inspector is open. If it isn’t, click the blue Info button in Dashcode’s toolbar.
2. Select stackLayout in the navigator.
3. Click the Attributes toolbar item in the inspector (it’s the one on the left). This should change the
inspector’s title to Attributes (stackLayout).
At the bottom of the inspector is a section titled Subview Transition. The values in this section control the
transitions between pages. You can choose to have pages slide in from right to left (this is the default) or
other ways, such as from top to bottom. Note that you may not be able to see the effect of changing the
transition type in the simulator application, but you will see the effect when you view your application on
an actual device.
Note:  The transitions described in this step are based on CSS transitions and animations. In the stack layout
Attributes inspector, Dashcode gives you a way to specify attributes of the transitions you want to use, but
does not provide a user interface for manipulating them directly. After you complete this tutorial, you might
want to access the code for these transitions to make finer-grained adjustments. Before you do this, you
should read Safari Visual Effects Guide for more information.
Add Functionality Using Parts
As you’ve seen, the mobile Safari web application you created using the Browser template is already functional
even though all its data is static. To make it more useful, you can add functionality that gets current information
from the web. In this step, you use Dashcode’s design tools to add a button to the detail page that performs
a Google search on the featured park (you’ll add the code to support this action in the next step).
To add a button to your web application, use a button part. Parts are controls and views used in a web
application’s user interface. Dashcode lists the available parts in the Library.
To find the appropriate button part, choose Window > Show Library and click Parts. Scroll through the list
of parts until you find the Push Button part, and drag this part into your detail page on the canvas.
Double-click the button on your detail page and give it a label (you can also do this by typing the label in
the Label field of the Attributes inspector for the button). You may need to resize the button to fit the label
you choose. Figure 2-3 shows the new button in the detail view, before it receives a new label.
Add Functionality Using Parts
23
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 2
Mobile Safari Web Application Tutorial
Figure 2-3
Adding a part to the mobile Safari web application’s user interface
Write Code to Perform a Search
To make the button perform a search on the featured park, you need to add behavior to the button. In the
Inspector, click Behaviors (it’s the rightmost button). This shows the Behaviors pane, in which you assign
handler functions to events on an object.
On the canvas, select the button you added to the detail page. In the Behaviors inspector, double-click in
the Handlers column next to the onclick event name. Enter the name of a new function, such as
detailButtonHandler, and press Return. If you don’t already see it, click the arrow next to the function
name you entered to reveal the source code editor below the canvas. Clicking the arrow reveals the
detailButtonHandler function Dashcode inserted in your web application’s code (specifically, in the
main.js file).
Between the braces ({...}), enter the following three lines of code:
var dsource = dashcode.getDataSource("list");
var name = dsource.selection().valueForKey("name");
document.location = ("http://www.google.com/search?client=googlet&q=" + name);
These lines of code do the following:
 ■ The first line of code creates a local variable named dsource, and gives it the value of the data source
named list.
In the Browser template, the list data source supplies the detail page with the static information about
the selected park.
24
Write Code to Perform a Search
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 2
Mobile Safari Web Application Tutorial
 ■ The second line of code creates a local variable named name, and gives it the value of the name property
of the currently selected park.
In a data source, each category of data is represented by a different property. In the list data source,
the name property contains the name of the selected park.
 ■ The third line of code tells the web application to display the search results for the park specified in
name.
Note:  You don’t need to understand anything about data sources or properties to complete this tutorial.
Later, you can begin learning about them in “Viewing a Project’s Data Sources and Bindings” (page 60).
After you add the code for the button’s event handler, the source code editor should look similar to Figure
2-4.
Figure 2-4
Adding code to handle the button’s click event
Test your web application again by clicking Run (or by choosing Debug > Run). In the detail page for a park,
click the button you added and make sure it displays the results of a Google search on the featured park (be
sure you’re connected to the Internet before you try this).
Deploy Your Mobile Safari Web Application
Congratulations! You’ve created your first mobile Safari web application using Dashcode.
To use your application on an iPhone or iPod touch, you need to deploy the application and make it available
on a web server. To learn how to do this, see “Deploying a Web Application” (page 75).
Deploy Your Mobile Safari Web Application
25
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 2
Mobile Safari Web Application Tutorial
26
Deploy Your Mobile Safari Web Application
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 2
Mobile Safari Web Application Tutorial
This tutorial walks you through using Dashcode version 3.0 or later to create a project that produces two
products: a Safari web application and a mobile Safari web application. A Safari web application is a dedicated
part of a website that provides Safari users with interactivity and discrete functionality. A mobile Safari web
application (also known as an iPhone web application) is web content optimized for Safari on iPhone that
provides users of iPhone OS–based devices with interactivity and discrete functionality.
As you follow the steps in this tutorial, you learn:
 ■ How to set up and work with a dual-product project
 ■ How to customize the user interface of both products
 ■ How to specify a data source
 ■ How to use bindings to automatically update each product’s user interface with data from a server
This is the third of three tutorials in this document. If you’re interested in learning how to develop a Dashboard
widget, read the first tutorial, “Dashboard Widget Tutorial” (page 13). If you want to learn how to create a
mobile Safari web application only and not a Safari web application, read the second tutorial, “Mobile Safari
Web Application Tutorial” (page 19).
Before You Begin
In this tutorial, you create a single Dashcode project that contains two products: a Safari web application
and a mobile Safari web application. A product is a set of files and resources that defines a web application
optimized to run in either Safari or Safari on iPhone.
The project you create in this tutorial is based on the browser style of web application and displays current
movie trailers available on Apple’s website. When you’re finished, the products will look similar to those
shown in Figure 3-1.
Before You Begin
27
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Figure 3-1
The finished products: Safari web application (top) and mobile Safari web application (bottom)
28
Before You Begin
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Important:  Although you can see current movie trailer information when you test your new products in
Dashcode, you cannot deploy such web applications unless you do additional work that is beyond the scope
of this document. This is because your web applications cannot request information from a domain other
than the one they’re running on unless you make changes to your server configuration and to your code.
Before continuing, make sure that you have Dashcode version 3.0 or later installed on your Mac (the install
location is /Developer/Applications/). If you don’t have Dashcode installed, read “Getting and Running
Dashcode” (page 10) to learn how to get and install Dashcode.
Choose a Template
To start, double-click the Dashcode icon to open it. A new project window opens and a dialog appears that
displays two types of projects—Safari and Dashboard—and an assortment of templates for each project
type. Templates are handy starting points for creating common types of web applications and widgets. (To
find out what a template does, select its icon to show a short description of its capabilities.)
For this tutorial, select the Safari project type. Then, to create a browser-type, dual-product web application
project:
1.
Select the Browser template.
2. Make sure both “Develop for:” checkboxes are selected (they are selected by default).
3. Click Choose.
The dialog disappears and the project window displays the first page of a new web application based on the
Browser template, as shown in Figure 3-2.
Choose a Template
29
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Figure 3-2
A new dual-product project
The main portion of the window is the canvas, which you use to design your web application’s interface.
The bar between the canvas and the toolbar is the product bar, which contains buttons you use to switch
between the products of a dual-product project. As shown in Figure 3-2 (page 30), the user interface of the
Safari web application is displayed on the canvas by default (note that the Safari button is selected). To see
the user interface of the mobile Safari web application, click the Mobile Safari button in the product bar.
Along the left side of the project window is the navigator, which you use to switch between the various
tools available when you’re designing a web application. When you switch between products in a dual-product
project, the contents of the navigator changes appropriately.
At the bottom of the navigator in Figure 3-2 you can see the Workflow Steps list, which guides you through
the development process. If you don’t want to see the Workflow Steps list, you can hide it by choosing View
> Steps or by clicking the button that looks like a box with a checkmark in it at the bottom edge of the project
window (this button is highlighted in Figure 3-2).
Alternatively, you can view a list of the current product’s data sources or code files in place of the Workflow
Steps list. If you want to see the Data Sources list, click the data source button in the bottom edge of the
project window (it’s to the left of the workflow steps button and it looks like a circle with a square inside it).
If you want to see the Files list, choose View > Files or click the list button in the bottom edge of the project
window (it’s the button to the left of the data sources button and it looks like a bulleted list).
30
Choose a Template
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Save and Test the Default Web Applications
You don’t need to customize your project at all to see how the default web applications work, but it’s good
practice to save your project before you begin to make changes. Choose File > Save to save the project. Give
your project a name, such as MyMovieTrailersProject, and select a location to save it in. The project encapsulates
both web application products and the information that Dashcode needs to create them for you. If you quit
Dashcode at any time, you can double-click your saved project to reopen it.
Your new web applications are already functional, even though they display only placeholder data. To prove
this, start by testing the Safari web application:
1. Make sure the Safari button is selected in the product bar.
2. Click the green Run button in the Dashcode toolbar (alternatively, you can choose Debug > Run).
When you do this, Dashcode opens the Safari web application in a simulator application.
Take a few moments to use the web application. Notice that when you click the name of a park in the list
along the left edge of the window, the area to the right displays information about that park. The list on the
left is known as the master list, because it contains the complete list of items you can view. The right portion
of the window is known as the detail area or detail view, because it shows details about the item selected in
the master list. Figure 3-3 shows the default Safari web application running in the Dashcode simulator (the
simulator displays the saved project name, in this case MyMovieTrailersProject, in the title bar).
Figure 3-3
The default Safari web application running in the Dashcode simulator application
Save and Test the Default Web Applications
31
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
After you’ve tested the Safari web application, stop the simulation and test the mobile Safari web application.
To stop the simulation, you can choose Quit from the simulation application menu, press Command-Q, or
click the red close button in the upper-left corner of the simulator window. Alternatively, in Dashcode, you
can click the red Stop button in the toolbar.
To test the mobile Safari web application:
1.
Select the Mobile Safari button in the product bar.
2. Click the green Run button in the Dashcode toolbar or choose Debug > Run.
Note:  If you've installed the iPhone SDK on your computer, Dashcode opens the mobile Safari web application
in the iPhone Simulator the SDK provides. If you do not have the iPhone SDK installed on your computer,
Dashcode opens the mobile Safari web application in its own simulator application. (Dashcode always opens
a Safari web application in its own simulator application.)
As you use the mobile Safari web application, you see that the master list of parks takes up the entire first
page. When you click a park name, a new page slides in that displays details about that park.
Notice that a back button appears near the upper-left corner of the detail page and that its label is the same
as the title of the first page. You click this button to return to the previous page. The two pages of the default
mobile Safari web application should look similar to those shown in Figure 3-4.
Figure 3-4
The default mobile Safari web application running in the iPhone Simulator
Now that you’ve seen the default appearance and behavior of both of your products, it’s time to customize
them to display the movie trailer data similar to the data shown in Figure 3-1 (page 28). Before you do this,
be sure to quit the simulation of the mobile Safari web application. As you did after testing the Safari web
32
Save and Test the Default Web Applications
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
application, quit the simulation by choosing Quit from the simulation application menu, pressing Command-Q,
or clicking the red close button in the upper-left corner of the simulator window. Or, in Dashcode, you can
click the red Stop button in the toolbar.
Customize the User Interface of the Safari Web Application
As you can see when you compare the finished Safari web application shown in Figure 3-1 (page 28) with
the default product shown in Figure 3-3 (page 31), there are a few differences in the detail area. Specifically,
the finished Safari web application displays the following details about the selected movie:
 ■ Title
 ■ Rating
 ■ Poster
 ■ Description
 ■ Trailer
This section shows you how to change the default user interface to resemble the user interface of the finished
product. Before you begin, make sure the Safari button is selected in the product bar.
To make enough room to display the poster of the selected movie trailer to the left of the description, you
need to move the description element to the right. Follow these steps to do this:
1. Click the word “Description” on the canvas. This displays a rectangular outline around the
detailDescription element. Look closely at this rectangle and notice the small, circular resize handles
that Dashcode displays at intervals along the perimeter.
2. Using the resize handle on the left edge of the outlined detailDescription element, drag to the right
until the word “Description” is centered horizontally in the detail area on the canvas.
Now you need to add two new parts to the canvas. If the Library isn’t open already, open it by clicking the
Library button in the Dashcode toolbar or by choosing Window > Show Library. Click the Parts tab in the
Library window to see the Dashcode parts you can use.
You need to add the Image part to display the selected movie’s poster in your web application. To find the
Image part, you can scroll through the list of parts in the Library until you find it or you can type image in
the search field at the bottom of the Library window.
Drag the Image part onto the canvas and place it to the left of the description element you moved earlier.
Use the resize handles on the perimeter of the image to adjust its size until you think it looks good.
Before you can align the top edge of the image with the top edge of the description, you need to change
the way Dashcode displays the Image part in relation to the other parts on the canvas. To do this, follow
these steps:
1.
If the inspector isn’t open already, click the blue Info button in the Dashcode toolbar, or choose Window
> Show Inspector. Open the Metrics inspector by clicking the button that looks like a ruler in the inspector’s
toolbar.
2. Select the Image part on the canvas. The title of the inspector changes to “Metrics (image).”
Customize the User Interface of the Safari Web Application
33
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
3.
In the Layout section of the Metrics inspector, choose Absolute from the pop-up menu.
After you’ve done this, you can move the Image part so that its top edge aligns with the top edge of the
description element. To do this, drag from the center of the Image part (don’t use the resize handles).
Go back to the Library and find the Video part. This part displays the selected movie’s trailer and includes
playback controls. Drag the Video part onto the bottom half of the canvas, into the area below the Image
part you added and below the word “Description.” Using its resize handles, adjust the size of the Video part
until you think it fits well in the lower half of the canvas.
In the navigator, make sure both the image and the video elements that you added are inside the detailBox
element. To do this, follow these steps:
1.
In the navigator, slowly drag the image element straight upwards until the detailBox element is
highlighted and a blue line appears below the detailDescription element, as shown in Figure 3-5.
Figure 3-5
In the navigator, drag the image element into the detailBox element
2. Release the mouse button. In the navigator, the image element is now directly below the
detailDescription element.
3. Similarly, slowly drag the video element straight upwards until the detailBox element is highlighted
and a blue line appears below the image element.
4. Release the mouse button. In the navigator, the video element is now directly below the image element.
After you’ve placed the new parts appropriately, the project window should look similar to the project window
shown in Figure 3-6. (Note the placement of the image and video elements in the navigator.)
34
Customize the User Interface of the Safari Web Application
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Figure 3-6
The canvas of the Safari web application after the new parts are added
You do not need to add any more parts to your web application, so you might want to close the Library
window. However, you’ll need to open it again when you customize the user interface of the mobile Safari
web application.
Specify a Data Source and Examine the Data Model
Now that you’ve completed the user interface of the Safari web application, it’s time to specify a data source
that supplies actual data in place of the default placeholder data the template provides.
As described in “Before You Begin” (page 27), your finished products display movie-trailer information from
Apple’s website. To make this happen, you need to give Dashcode the correct URL. To do this, follow these
steps:
1.
Show the Data Sources list in the navigator. To do this, click the data sources button in the lower-left
corner of the project window (it’s the one that looks like a circle with a square inside it). After you do
this, you should see two data sources in the Data Sources list, one named dataSource and one named
itemsList.
2. Select dataSource in the Data Sources list. This reveals a view below the canvas, which contains the
layout of data in the data source. This layout is called the data model.
3. Paste the following URL into the URL field at the top of the data model view:
Specify a Data Source and Examine the Data Model
35
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
http://www.apple.com/trailers/home/xml/current.xml
4. Click the Reload button to the right of the URL field or press Return.
If you’ve entered the URL correctly, Dashcode refreshes the data model view to display the layout of the new
data source and some current movie-trailer data from Apple’s website.
Take some time to look at the data model. Notice that it is a hierarchy with each member, called a property,
displayed on a separate line. A property that contains other properties has a disclosure triangle to the left of
it.
The data model also displays bindings and binding controls. As you can see in Figure 3-7, a gray capsule that
contains the text itemsList.dataArray is displayed to the right of the top-level content property. This
capsule represents a completed binding that Dashcode provides by default in the Browser template. This
binding means that the itemsList element on the canvas can get its information from the content property
in the data source.
Figure 3-7
Completed bindings and binding controls are visible in the data model
If a property in the data model does not already have a binding, moving the mouse pointer over the property
reveals a circular binding control to the right of the property. For example, in Figure 3-7 you can see a binding
control revealed next to the poster property.
36
Specify a Data Source and Examine the Data Model
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Because the data source you’ve specified is available to both products your project creates, you do not have
to perform the steps in this section again when you switch to the mobile Safari product. However, you must
create a separate set of bindings in each product. This is because bindings connect properties in the data
source with elements in the user interface, and each product can have a different set of elements in its user
interface.
Create Bindings for the Safari Web Application
Note:  Although the bindings you create in this section do not apply to the mobile Safari web application,
the actions you take to create them are the same.
As mentioned in “Specify a Data Source and Examine the Data Model” (page 35), there is already a binding
in the data model view of the data source named dataSource. In this tutorial, you do not change this existing
binding between the content property and the itemsList element, but you do create a few new bindings.
Create the First Binding
The first binding you create identifies which data source property should supply the movie titles to display
in the web application’s master list. To do this, make sure you can still see the data model for dataSource
and that the disclosure triangle next to the content property is pointing down (you should see something
similar to the data model shown in Figure 3-7 (page 36)). Then, follow these steps:
1.
If it’s not already pointing down, click the disclosure triangle next to the movieinfo property to open
it. Then, click the disclosure triangle next to the info property (it’s inside the movieinfo property).
2. Press and hold the mouse button on the binding control next to the title property (it’s the first property
inside the info property).
3. Without releasing the mouse button, drag from the binding control to the item title element on the
canvas (it’s the first occurrence of the word “Title” in the master list on the canvas).
Create Bindings for the Safari Web Application
37
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
When you do this, you should see a blue connection line extend from the binding control to the item
title element and a little gray box that contains the element’s name, itemTitle, as shown in Figure 3-8.
Figure 3-8
Dashcode displays a blue connection line between a data source property and an element
on the canvas
4. Release the mouse button while the item title element is highlighted. Immediately, Dashcode displays
a contextual menu that lists the bindable properties for this element.
In this case, you should see a contextual menu that contains: text, editable, visible, enabled, html, and
class.
5.
In this contextual menu, choose text.
Note that if you click outside the contextual menu, the binding does not complete and you must start
over from step 2.
After you finish these steps, you should see a new gray capsule in the data model. This capsule should be
next to the title property and should contain the text itemTitle.text.
38
Create Bindings for the Safari Web Application
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Note:  If you see different text inside the gray capsule next to the title property, erase the binding (by
clicking the delete control inside the left end of the capsule) and try the steps again. (The delete control looks
like an X.)
You can be sure that you’re binding to the correct element when you see the element’s name in the little
gray box that Dashcode displays as you drag over the canvas.
Create the Remaining Bindings
Now you need to create bindings to parts in the detail area of your Safari web application. Even though these
new bindings are between different data source properties and parts, the actions you take to create each
one are very similar to the actions described in steps 2 through 5 in “Create the First Binding” (page 37).
The new bindings you need to create are from properties in the itemsList data source. To reveal the data
model for this data source, click itemsList in the Data Sources list.
The four new bindings you need to create are described below. You do not have to create these bindings in
the order given, but you must create each one using the precise properties and elements described. Before
you begin, make sure the disclosure triangle next to the selection property is pointing down, because all
the properties you need to use are inside this property.
1. Bind the title of the selected movie to the title in the detail header.
a.
In the data model, find the title property inside the info property.
b. Drag from the title property’s binding control to the detailTitle element on the canvas. (On
the canvas, the detailTitle element displays the word “Title” in a large font, and appears above
the word “Location.”)
c. Choose text from the contextual menu that appears when you release the mouse button.
2. Bind the description of the selected movie to the description that appears above the video.
a.
In the data model, find the description property inside the info property.
b. Drag from the description property’s binding control to the detailDescription element on
the canvas. (The detailDescription element is the one you moved to the right to make room
for the Image part in “Customize the User Interface of the Safari Web Application” (page 33)).
c. Choose text from the contextual menu that appears when you release the mouse button.
3. Bind the poster of the selected movie to the Image part.
a.
In the data model, find the xlarge property inside the poster property.
b. Drag from the xlarge property’s binding control to the image element on the canvas (this is the
Image part you added in “Customize the User Interface of the Safari Web Application” (page 33)).
c. Choose src from the contextual menu that appears when you release the mouse button.
4. Bind the trailer of the selected movie to the Video part.
Create Bindings for the Safari Web Application
39
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
a.
In the data model, find the large property inside the preview property.
b. Drag from the large property’s binding control to the video element on the canvas (this is the
Video part you added in “Customize the User Interface of the Safari Web Application” (page 33))
c. Choose src from the contextual menu that appears when you release the mouse button.
After you’ve finished creating these bindings, you’ve completed all the steps necessary to produce a Safari
web application that looks similar to the one shown in Figure 3-1 (page 28).
Test the Safari Web Application
If you haven’t saved your project recently, save it now. Make sure the Safari button is still selected in the
product bar and click Run to test your product. If this is the first time you’ve run your web application since
you specified Apple’s website for the dataSource data source in “Specify a Data Source and Examine the
Data Model” (page 35), Dashcode displays a dialog that asks you if you want to simulate running on the
domain that hosts that website. Click Simulate in this dialog so you can see the data from the website.
You should see something similar to the Safari web application shown in Figure 3-1 (page 28). Note that
you will probably see a different list of movies, depending on which movie trailers are available.
Scroll the master list and select a movie title. Click the Video part’s playback control to see the trailer for the
movie you selected.
Customize the User Interface of the Mobile Safari Web Application
Now that your Safari web application is in good shape, it’s time to turn your attention to your mobile Safari
web application. Although you don’t need to make any changes to the master list displayed on the first page,
you do want to display the poster for the selected movie on the detail page, as shown in Figure 3-1 (page
28). Before you begin, be sure to select the Mobile Safari button in the product bar.
To show the detail page on the canvas, click detailLevel in the navigator. If you don’t see detailLevel
listed in the navigator, open the disclosure triangles next to browser and next to stackLayout to reveal
it.
As you did with the Safari web application, you need to add the Image part to your page. If the Library is not
already open, open it by clicking the Library button in the Dashcode toolbar or choose Window > Show
Library. Click the Parts tab in the Library window to see the available parts. Find the Image part by scrolling
through the list of parts or by typing image in the search field at the bottom of the Library window.
Place the Image part inside the white box on the detail page, below the title, location, and description
elements. To do this, drag the Image part onto the canvas and, without releasing the mouse button, drag it
towards the bottom edge of the white box until the title, location, and description elements jump above the
Image part. If you happen to release the mouse button before you finish placing the Image part, delete the
Image part, drag in a new one, and try again.
40
Test the Safari Web Application
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Adjust the size of the Image part by using its resize handles until you think it fits well into the space inside
the white box. After you do this, your project window should look something like the project window shown
in Figure 3-9:
Figure 3-9
The canvas of the mobile Safari web application after the Image part is added to the detail
page
Create Bindings for the Mobile Safari Web Application
Note:  The bindings you created for your Safari web application do not apply to your mobile Safari web
application, so you must follow the steps in this section to create separate bindings for it. However, the data
source you specified in “Specify a Data Source and Examine the Data Model” (page 35) is available to both
products, so you do not have to specify it again.
In this section, you’ll create five bindings: one to an element on the master list page and four to elements
on the detail page. Before you begin, make sure the Mobile Safari button is selected in the product bar.
Create Bindings for the Mobile Safari Web Application
41
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
Create a Binding to an Element on the Master List Page
The first binding you create identifies which data source property should supply the movie titles to your web
application’s master list. (If you don’t remember the meaning of terms such as data source and property, see
“Specify a Data Source and Examine the Data Model” (page 35).) To show the master list on the canvas, click
the listLevel element in the navigator. If you don’t see listLevel listed in the navigator, open the
disclosure triangles next to browser and stackLayout.
If the Data Sources list isn’t already visible in the navigator, show it by clicking the data sources button in
the lower-left corner of the project window (it’s the one that looks like a circle with a square inside it). Select
dataSource in the Data Sources list to reveal its data model. Notice that the URL you entered for your Safari
web application is already in the URL field.
To bind the movie titles to the master list’s row titles, open the disclosure triangle next to the content
property and do the following:
1.
In the data model, find the title property inside the info property.
2. Drag from the title property’s binding control to the rowTitle element on the canvas. (The rowTitle
element contains the first occurrence of the word “Item” in the list.)
3. Choose text from the contextual menu that appears when you release the mouse button.
Create Four Bindings to Elements on the Detail Page
Now create the four bindings you need on the detail page. In the navigator, select the detailLevel element
to show the detail page on the canvas. In the Data Sources list, select the list data source to reveal its data
model. In the data model, make sure the disclosure triangle next to the selection property is pointing
down, because all the properties you need to use are inside this property.
1. Bind the title of the selected movie to the title in the white box.
a.
In the data model, find the title property inside the info property.
b. Drag from the title property’s binding control to the detailTitle element on the canvas. (The
detailTitle element contains the word “Title” on the canvas.)
c. Choose text from the contextual menu that appears when you release the mouse button.
2. Bind the rating of the selected movie to the subtitle in the white box.
a.
In the data model, find the rating property inside the info property.
b. Drag from the rating property’s binding control to the detailSubtitle element on the canvas.
(The detailSubtitle element contains the word “Location” on the canvas.)
c. Choose text from the contextual menu that appears when you release the mouse button.
3. Bind the description of the selected movie to the description in the white box.
a.
In the data model, find the description property inside the info property.
42
Create Bindings for the Mobile Safari Web Application
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
b. Drag from the description property’s binding control to the detailDescription element on
the canvas. (The detailDescription element contains the word “Description" on the canvas.)
c. Choose text from the contextual menu that appears when you release the mouse button.
4. Bind the poster of the selected movie to the Image part.
a.
In the data model, find the xlarge property inside the poster property.
b. Drag from the xlarge property’s binding control to the image element on the canvas (this is the
Image part that you added in “Customize the User Interface of the Mobile Safari Web
Application” (page 40)).
c. Choose src from the contextual menu that appears when you release the mouse button.
After you’ve finished creating these bindings, you’ve completed all the steps necessary to produce a mobile
Safari web application that looks similar to the one shown in Figure 3-1 (page 28).
Test the Mobile Safari Web Application
If you haven’t saved your project recently, save it now. Make sure the Mobile Safari button is still selected in
the product bar and click Run to test your product. You do not see the dialog that asks you if you want to
simulate running on the www.apple.com domain, because Dashcode continues to simulate running on the
remote domain you specify until you change it.
On the first page you should see a long list of current movie titles. Click a title and you should see the rating,
description, and poster for that movie.
Next Steps
Congratulations! You’ve learned how to use Dashcode to create a dual-product project that produces two
web application products.
To learn about deploying your products, see “Deploying a Web Application” (page 75).
Test the Mobile Safari Web Application
43
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
44
Next Steps
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 3
Dual-Product Web Application Tutorial
When you start a new project, you base it on a Dashcode template or, in the case of Dashboard widgets, you
can also base it on an existing widget. A project encapsulates all the files and resources that Dashcode uses
to build a widget or web application for you.
This chapter discusses the options you have when you start a project. It also discusses opening a Dashboard
widget in Dashcode, a feature that allows you to forgo Dashcode’s design tools to code, test, and debug an
existing widget.
Creating a Project from a Template
Dashcode creates new projects based on templates. Templates are preconfigured widgets or web applications
that include code and graphics that perform common tasks. When you open Dashcode or choose File > New
Project after you open it, a dialog appears that offers you a choice of project types. When you choose one
of these, the dialog offers you a choice of templates appropriate for the project type. Click a template icon
to see a short description of the template’s abilities. If the template matches the task you’re trying to perform,
select its icon and click Choose. For more on the templates included with Dashcode, read “Dashcode
Templates” (page 79).
In Dashcode version 3.0 and later, you can choose to create a Safari web application or a mobile Safari web
application or both. By default, Dashcode creates a single project that produces both products. This allows
you to use the same data and much of the same code, but design a different user interface for each product.
If you want to create only one type of web application in a project, make sure you deselect the “Develop
for:” checkbox for the type of product that you don’t want to develop. The “Develop for:” checkboxes appear
between the template icons and their descriptions.
After you choose a template, you may need to provide required values for the widget or web application to
work properly. For widgets in particular, make sure to provide the Identity and Properties values, as discussed
in “Providing Attributes for a Dashboard Widget” (page 46).
Creating a Project from an Existing Dashboard Widget
Dashcode can create a new project from an existing widget. If you want to continue work on an existing
widget in Dashcode, you should import it. Importing a widget copies it into a new widget project and enables
the code generator. When the code generator is active, all of Dashcode’s design and management tools are
enabled.
To import a widget, choose File > Import Widget or choose Import from the template chooser dialog.
Creating a Project from a Template
45
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 4
Starting a Project
Note:  If your widget uses objects created at runtime (such as those created from an Apple Button or an
Apple Scroll Area, both Apple classes that Apple provides widget developers), they do not appear on the
canvas since their constructors are not executed when the widget is shown.
Once you import your widget into a Dashcode project, use the widget attributes pane, as discussed in
“Providing Attributes for a Dashboard Widget” (page 46), to edit your widget’s Identity values.
Providing Attributes for a Dashboard Widget
Each widget project has required values you need to provide for the widget to work properly. You set these
values in the widget attributes pane, available when you select Widget Attributes in the navigator. Make
sure to provide values in the following sections of the editor, if available:
Identity
The values in this section are used to identify a widget.
You need to provide a widget identifier, used by Dashboard to differentiate your widget from others.
Widget identifiers are commonly formatted in reverse domain notation, starting with a top-level
domain (such as com), followed by a company or creator name (such as apple), and then a unique
product name (such as my-fabulous-widget, yielding a name such as
com.apple.my-fabulous-widget).
Additionally, you need to provide a unique version number. This number is used by Dashboard to
differentiate between versions of a widget, so that it’s always running the most recent version.
Note:  The widget identifier and version fields correspond to the CFBundleIdentifier and
CFBundleVersion information property list values, as discussed in Dashboard Info.plist Keys.
Properties
Template-specific options are in this section. If you’re using an imported or opened widget or the
Custom template, this section is absent. For each template’s specific properties, read “Dashcode
Templates” (page 79).
Providing Attributes for a Web Application
Each web application project has values you need to provide for the products to work properly. You set these
values in the application attributes pane, available when you select Application Attributes in the navigator.
Although only the page title is required, it’s a good idea to set the other values so your web application
behaves as you intend.
Some templates include a Properties section in the application attributes pane, in which you set
template-specific options. For more information about the options you can set for a template, see the template
descriptions in “Web Application Templates” (page 82).
In Dashcode version 3.0 and later, some application attributes are different, depending on whether you’re
developing a Safari web application or a mobile Safari web application. If you’re developing both types of
web application, you see a product bar below the toolbar that contains a Safari button and a Mobile Safari
46
Providing Attributes for a Dashboard Widget
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 4
Starting a Project
button. Click these buttons to switch between the attributes you need to set for each product. If you’re
developing only one type of web application (or if you’re using an earlier version of Dashcode to develop a
mobile Safari web application), you do not need to switch between attributes for different products, so you
do not see the product bar.
Application Attributes for Safari Web Applications
To set the application attributes for the Safari web application product of your dual-product project in
Dashcode version 3.0 and later, be sure to select the Safari button in the product bar. If you’re using Dashcode
version 3.0 and later to develop a Safari web application only, you do not need to do this. If you’re using an
earlier version of Dashcode to develop a mobile Safari web application, see “Application Attributes for Mobile
Safari Web Applications” (page 47) for information about the attributes you can set.
Provide values in the following section of the application attributes pane:
General
The Page Title value in this section is used to identify the Safari web application. In the Page Title
field, title your web application by giving it an appropriate, human-readable name. The title you
supply is the <title> element in your webpage and is displayed in the title bar of the browser.
The Offline Viewing value in this section controls whether users can still use your web application if
they lose their network connection. If you select this checkbox, be sure to read “Supporting Offline
Usage of a Web Application” (page 65) to find out what you need to do to handle offline viewing of
your web application.
Application Attributes for Mobile Safari Web Applications
To set application attributes for the mobile Safari web application product of your dual-product project in
Dashcode version 3.0 and later, be sure to select the Mobile Safari button in the product bar. If you’re using
Dashcode version 3.0 and later to develop a mobile Safari web application only (or if you’re using an earlier
version of Dashcode), you do not need to do this.
Provide values in the following sections of the application attributes pane, if available:
General
The Page Title value in this section is used to identify the mobile Safari web application. In the Page
Title field, title your web application by giving it an appropriate, human-readable name. The title you
supply is the <title> element in your webpage and is displayed in the title bar of Safari on iPhone.
Viewport
The values in this section control how users can view your mobile Safari web application when they
use it on iPhone or iPod touch. When users change the device orientation from portrait to landscape,
webpages can get scaled to fit the new screen orientation.
The two options for the Orientation value are:
 ■
“Adjust page width to fit.” When you choose this option, your web application resizes (that is,
increases or decreases in width) when the device orientation changes. This option is generally
recommended for mobile Safari web applications, because it enhances the user’s perception of
the web application as a standalone application and not a webpage.
Providing Attributes for a Web Application
47
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 4
Starting a Project
 ■
"Zoom page to fit.” When you choose this option, the width of your mobile Safari web application
does not change when the device orientation changes, but the scale does. In other words, the
content of your web application will appear a bit bigger. You might want to choose this option
if your web application has a complicated layout that you don’t want to change in width when
the device orientation changes.
The Page Zooming value in this section controls whether users can zoom your web application when
they view it on iPhone or iPod touch. In general, because you want iPhone and iPod touch users to
view your web application as a standalone application and not as a webpage, it’s recommended that
you turn off Page Zooming (that is, deselect “Allow users to adjust page zoom”).
Web Clip
The values in this section control how your web application can be displayed on iPhone and iPod
touch and how your Web Clip icon is created and displayed.
In iPhone OS 2.0 and later you can choose to make your mobile Safari web application available in a
full-screen mode, which hides the Safari toolbar and navigation bar. If you want to do this, you must
also provide a Web Clip icon, because tapping a Web Clip icon is the only way users can open a web
application in full-screen mode (navigating to the application in Safari on iPhone does not open it in
full-screen mode). If you choose not to support full-screen mode, you should still consider providing
a Web Clip icon so users have a convenient way to open your web application.
To make your mobile Safari web application available in full-screen mode, select the “Show as full
screen application (hide Safari toolbar and navigation bar)” checkbox. This allows users to open your
web application in full-screen mode when they tap the Web Clip icon. Note that users press the Home
button to leave a web application that is running in full-screen mode.
If you selected the “Show as full screen application (hide Safari toolbar and navigation bar)” checkbox,
you can also specify one of the following three styles for the status bar:
 ■ Gray
 ■ Black
 ■ Black (Translucent)
Use the pop-up menu to choose the status bar style that best coordinates with the appearance of
your web application. You can specify a status bar style only if you selected the “Show as full screen
application (hide Safari toolbar and navigation bar)” checkbox. This is because the status bar appearance
automatically matches the appearance of the Safari navigation bar when it is visible.
The two options for the Icon value are:
 ■
"Use custom icon.” Choose this option if you want to design your own Web Clip icon to represent
your mobile Safari web application. See “Designing a Web Clip Icon for an iPhone Web
Application” (page 56) for more information on how to do this.
If you choose this option, you can also specify whether you want the shiny glass overlay effect
to be added automatically by selecting the “Add glass visual effect” checkbox. Note that you do
not have control over a Web Clip icon’s rounded corners and drop shadow; these are always
added automatically.
 ■
"Use Safari generated icon.” Choose this option if you want to allow users to create their own
Web Clip icon to represent your mobile Safari web application.
48
Providing Attributes for a Web Application
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 4
Starting a Project
Opening an Existing Dashboard Widget
If you want to forgo Dashcode’s project management and design tools, you can open an existing widget in
Dashcode without importing it into a new project. When Dashcode opens a widget, you have access to its
code and all of Dashcode’s debugging tools, but not its design tools.
To open a widget in Dashcode, choose File > Open and select a widget in the Open dialog, or choose File >
New Project and click the Open Existing button at the bottom of the template chooser dialog. When you
open a widget with Dashcode, the canvas is locked. This means that Dashcode’s design tools, responsible
for generating HTML, CSS, and images for a widget, are turned off. When you open an existing widget instead
of importing it into a new project, Dashcode displays a lock over the bottom of the canvas.
Opening an Existing Dashboard Widget
49
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 4
Starting a Project
50
Opening an Existing Dashboard Widget
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 4
Starting a Project
After you’ve started a project as discussed in “Starting a Project” (page 45), use Dashcode’s design tools to
design the interface of the widget or web application. This chapter describes the canvas, the interface design
area in Dashcode, and how to begin laying out an interface. It also discusses how to add Dashcode parts to
your project and how to use the inspector window to adjust the appearance or behavior of a part.
Read this chapter to learn how to use Dashcode’s design tools to create, modify, and preview the appearance
of your widget or web application.
Laying Out the Interface
Dashcode includes a workspace where you lay out the elements that comprise the user interface of a web
application or a widget. This workspace, called the canvas, is visible in the main portion of the project window
when you select your widget or web application in the navigator. You can freely move and resize any element
in an interface when the canvas is visible. To move an element, drag it to where you want it to be. To resize
an element, drag one of its resize handles. If you hold down the Shift key while resizing an element, the
original proportions are maintained.
Dashcode also provides commands you can use to arrange and align elements in a widget or web application
interface. For more on how to do this, see “Arranging and Locking Elements” (page 53).
You can drag any item from the Finder to the canvas to add it to a your widget or web application. This
means that you can design the user interface in an application such as Adobe Illustrator or Photoshop, save
the images, and drag them into your Dashcode project from the Finder. Dashcode, however, offers its own
design elements. Learn about them in “Adding Parts to an Interface” (page 51).
Showing a Widget’s Sides
By default, all new widgets created from a Dashcode template have two sides: a front and a back. The canvas
shows you only one of these sides at a time. To switch between the sides, click front or back in the navigator.
(If you don’t see front and back in the navigator, click the disclosure triangle next to the widget’s name.)
When a side is visible on the canvas, you can add and arrange elements on it. To work on the other side, click
the corresponding name in the navigator.
Adding Parts to an Interface
Dashcode includes a set of controls, shapes, and views called parts. Choose Window > Show Library and
click the Parts button to see the parts included with Dashcode.
Laying Out the Interface
51
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 5
Designing the User Interface of a Widget or
Web Application
Some parts are appropriate only for specific products. The Library displays only those parts that can be used
in the product that is selected in the currently active project. For example, in Dashcode 3.0, you see a different
set of parts when you switch between the Safari and mobile Safari products of your dual-product web
application project. Similarly, the Library shows a different set of parts when you switch between a web
application project and a widget project.
To add a part to a widget’s or web application’s interface, drag it from the Parts Library to the widget body
or web application page on the canvas. Once a part is on the canvas, you can change its properties, as
discussed in “Changing an Element’s Properties” (page 52). If you want to know more about laying out parts
in your project’s user interface, read “Arranging and Locking Elements” (page 53).
A number of Dashcode parts can be manipulated programmatically. Read “Dashcode Parts” (page 85) to
learn more about using these parts.
Using Photos from iPhoto
You can drag any photo in your iPhoto library to the canvas to include it in a widget or web application. To
show your iPhoto library, choose Window > Show Library and click the Photos button. Once the photo is on
the canvas, you can arrange it as described in “Arranging and Locking Elements” (page 53) and adjust its
properties as discussed in “Changing an Element’s Properties” (page 52).
Note:  The iPhoto library requires iPhoto 6 or later.
Changing an Element’s Properties
The inspector window reveals information about the selected element on the canvas. In this window, you
can view and edit the element’s properties based on the inspector type you choose. Choose an inspector by
clicking its button at the top of the window. The inspector window includes the following inspectors, from
left to right:
 ■ The Attributes inspector allows you to modify the selected element’s ID (used in JavaScript to reference
the element), its CSS class, whether it’s shown in the widget or web application and in the default image,
and any parameters that are unique to the element.
 ■
If it’s appropriate for the selected element, the Fill & Stroke inspector allows you to adjust its style and
add effects. Style adjustments you can make include:
 ❏ Fill, such as solid, gradient, or image
 ❏ Corner roundness, opacity, and reflection
 ❏ Stroke color and width
Effects you can add include:
 ❏ Glass, including control over shine, tone, horizon, and curvature
 ❏ Recess, including control over depth, shadow, and highlights
52
Using Photos from iPhoto
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 5
Designing the User Interface of a Widget or Web Application
 ■ The Metrics inspector allows you to modify the selected element’s size and position, as well as its behavior
if the widget or webpage is resized. The Layout pop-up menu allows you to select whether the element
should be positioned using absolute or document-flow positioning (learn about these positioning styles
in “Absolute versus Document-Flow Positioning” (page 54)). The Autoresize settings affect how an
element behaves when the widget or webpage is resized on the canvas. Note that the values in the Size
section reflect the actual dimensions of the selected element, including borders.
 ■
If the selected element displays text, you can adjust the text’s font, style, color, size, shadow, alignment,
and spacing in the Text inspector. You can also set whether text wraps or not and how to handle text
overflow. Setting the text overflow to Clip cuts any string in the selected element at its bounds, allowing
for no overflow, whereas setting the text overflow to Ellipsis appends an ellipsis character (…) to the
selected element’s text when it reaches the element’s bounds.
Note:  If you plan to share a widget or deploy a web application, be careful to use fonts that are standard
in Mac OS X, such as Helvetica Neue, Times, and Monaco.
 ■ The Bindings inspector allows you to set and adjust bindings between a data source and specific properties
of the selected element. For each bindable property of the element, you can specify the data source to
bind to, the key path of the item in the data source, a value transformer, and placeholder values. (To
learn about value transformers, see “Adding a Value Transformer” (page 64).)
You do not have to use the Bindings inspector to create bindings. Instead, you can drag connections
from items in the data model view to elements on the canvas or listed in the navigator. (To learn how
to show the data model view, see “Viewing a Project’s Data Sources and Bindings” (page 60); to learn
how to create bindings, see “Creating Bindings” (page 63).) However, you must use the Bindings inspector
to specify a value transformer or supply placeholder values.
 ■ The Behaviors inspector allows you to assign to the selected element JavaScript handlers for various
events. For each event, you can assign an existing JavaScript function as its handler or create an empty
function that’s automatically added to the project’s JavaScript code. After you assign a handler to an
event, click the arrow next to the handler’s name to reveal the function in the source code editor.
Working with code is discussed in “Adding Source Code and Creating Bindings” (page 59).
Arranging and Locking Elements
Dashcode offers helpful options for arranging elements on the canvas. If an element is obscured by other
elements, select it and choose Arrange > Bring Forward or Arrange > Bring to Front to move it in front of
any elements currently obscuring it. Similarly, if you want to move an element behind another, select it and
choose Arrange > Send Backward or Arrange > Send to Back.
Dashcode offers alignment and distribution options for arranging multiple elements with respect to each
other. If you want to align a few items on their left edges, you select them on the canvas and choose Arrange
> Align > Left. Similar options are available to align elements by center, right, top, middle, and bottom. If
you want an equal amount of vertical space between multiple elements, choose Arrange > Distribute >
Vertically. A similar option exists to distribute elements horizontally.
If you want to lock an element so that you can no longer move it, select the element and choose Arrange >
Lock. If you change your mind and want to move it again, select it and choose Arrange > Unlock. Note that
locking an element only locks its placement on the canvas—you can still adjust its attributes in the inspector.
Arranging and Locking Elements
53
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 5
Designing the User Interface of a Widget or Web Application
Absolute versus Document-Flow Positioning
Dashcode allows you to position elements in your widget or web application using either absolute or
document-flow (that is, relative) positioning. You can change the positioning of a selected element by
switching between Absolute and Document Flow in the Layout section of the Metrics inspector.
Briefly, absolute positioning means that an element’s position within its containing element is always the
same, regardless of the positions of its sibling elements. In other words, an absolutely positioned element
retains its position within the containing element, even if the sibling elements around it expand or shrink.
Absolute positioning allows you to have precise control over complicated layouts, but does not support
dynamic resizing very well.
In contrast, document-flow positioning means that an element’s position is defined in terms of the positions
of its document-flow sibling elements. In document-flow positioning sibling elements are displayed in order,
vertically, so the position of an individual element depends on its location in the series of elements. If one
element expands downward, it pushes down all the sibling elements that come after it by the same amount,
without changing their sizes or their relative positions. Although document-flow positioning provides great
flexibility to support dynamic resizing, it does not give you fine-grained control over layouts.
Because widgets tend to stay the same size (or switch among a small number of predefined sizes), Dashcode
widget projects use absolute positioning by default. Conversely, because web applications need more
flexibility in sizing, Dashcode web application projects use document-flow positioning for most elements by
default.
The default positioning style used in a project does not mean that there are no variations, however. In the
Browser template web application project, for example, the elements in the list row (the row title and the
row arrow) are absolutely positioned to ensure a consistent layout.
When you customize a project, you should be aware of the positioning style of the element you’re changing.
This is because dragging a part into an existing container element on the canvas causes the part to adopt
the prevailing positioning style of its new siblings. If you want the new part to adopt the alternate positioning
style, hold down the Shift key while you drag the part onto the canvas.
Searching for Elements
Use the search field in the toolbar to find elements in your project’s interface and code. This particular type
of search works when you’re designing and coding a widget or web application. When Dashcode is running
a widget, the toolbar’s search field narrows results from either the run log or the Stackframe & Variables table,
depending on which is visible. This is discussed further in “The Run Log and Tracing Execution” (page 73)
and “Checking Values in Memory” (page 74).
To search for an element, type part of the element’s name in the search field. When the search results are
returned, the navigator is replaced with search results. Selecting an item in the search results either highlights
it on the canvas or shows the source code file that contains the implementation of the element.
54
Absolute versus Document-Flow Positioning
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 5
Designing the User Interface of a Widget or Web Application
Rulers and Guides
By default, the canvas displays rulers along its top and left sides. Rulers, when used with guides, help you
align elements relative to one another. To add a guide, position the pointer anywhere in a ruler and drag
towards the canvas. As you drag away from the ruler, a guide appears—it remains wherever you stop dragging.
To remove a guide, drag it back to a ruler. To hide the rulers, choose View > Hide Rulers.
Placing a Widget’s Close Box
Users click a widget’s close box to close it (web applications do not have a close box). By default, a widget’s
close box appears over the top left of a widget’s body. If necessary, move the close box so that it overlaps
the top left corner of your widget’s body. To hide the close box on the canvas, choose View > Hide Invisible
Items.
Disabling the Canvas
Because the canvas generates HTML and CSS automatically for you, you may want to turn its code generation
off if you’re tweaking elements by hand. To turn off the automatic code generator, choose View > Stop Code
Generator. When you’re finished tweaking values by hand, you can turn the code generator back on by
choosing View > Start Code Generator.
Previewing a Widget’s Default Image
The default image preview shows you a widget’s default image, which is displayed while it loads in Dashboard.
To see your widget’s default image, select Default Image in the navigator.
By default, all the elements on the front of a widget except the text parts (Text, Text area, and Text field) are
included in a widget’s default image. Other parts that display text, such as pop-up menus, are also included.
You are discouraged from leaving text in your widget’s default image because any text on your interface
may change when the widget is localized. Therefore, you should remove parts that display text from your
widget’s default image. To remove any element from your widget’s default image, follow these steps:
1.
Select the widget item in the navigator to show the canvas.
2. Select the element on the canvas that you want removed from the default image.
3. Show the Attributes inspector (as discussed in “Changing an Element’s Properties” (page 52)).
4. Deselect Show in Default Image.
The toolbar below the default image preview offers additional configuration options for default images:
Rulers and Guides
55
2009-07-24   |   © 2009 Apple Inc. All Rights Reserved.
CHAPTER 5
Designing the User Interface of a Widget or Web Application