Adding Source Code and Creating Bindings
After you’ve started a project and designed the user interface, you may need to customize the implementation by adding code, data sources, or bindings to your widget or web application. This chapter describes how to:
View the files and data sources that make up your project
Write custom code to perform tasks that aren’t automatically provided by the template
Add data sources and bind them to elements in the user interface
Write a value transformer that converts the value of a property to a version that’s appropriate for display
This chapter also shows you how to turn on access to resources, such as files outside of the project and the network. Finally, it covers the application preferences that affect your code editing experience in Dashcode.
Viewing a Project’s Source Code
Above the text view portion of the source code editor are two pop-up menus, a file history menu on the left and, in some cases, a function menu to the right of that. The file history menu lists the text files and data sources that you've recently edited or viewed in the source code editor. When you select a file or data source in the file history menu, it’s displayed in the source code editor. When you first open a project, the file history menu contains the files you’re most likely to open, such as
One common way to add code is to add an event handler to an element in the user interface. You do this using the Behaviors inspector, as discussed in “Adding a Handler for an Event.” If you’re using Dashcode version 3.0 and later, a common reason to add code is when you need a value transformer to provide an appropriate value to display, based on other information in your project. You do this using the Bindings inspector, as discussed in “Adding a Value Transformer.”
When working with resources originating outside a widget or web application—
XMLHttpRequest, command-line tools, Java applets, and such—you need to explicitly turn on access to these items. To learn more about resource access and what elements need activation, read “Resource Access.”
You can also modify how the source code editor looks and behaves, as described in “Code Editing Preferences.”
Viewing a Project’s Data Sources and Bindings
Dashcode supports the use of data sources and bindings to give you an easy, efficient way to get source data into the user interface and keep the display in sync with the data. A data source represents data from a source that can be remote, such as an RSS feed, or a local object, such as a list. A binding is a connection between a specific property or attribute in the data source and a property of an element on the canvas.
To show the data sources in your project click the data source button at the bottom of the navigator (the button looks like a circle with a square inside it). This reveals the Data Sources list in the navigator. In this list you can add, remove, and rename data sources, as described in “Adding or Changing a Data Source.”
Select a data source in the Data Sources list to see a graphical representation of its layout in the source code editor below the canvas. This representation is called the data model and it shows you the structure of the data source, the data types of the properties in it, and, when possible, a preview of the data. You can use the data model view to create bindings and to see at a glance which user interface elements have bindings to properties in the data source. To learn how to create bindings, see “Creating Bindings.” To see which elements have bindings to properties in the selected data source, move the pointer over an existing binding in the data model: Dashcode flashes the connected element on the canvas.
In the data model view, Dashcode displays the hierarchical organization of the data source, using disclosure triangles to indicate properties that contain children. Open a disclosure triangle to reveal a box containing a list of child properties. When you move the pointer over a child property, Dashcode highlights all its ancestor properties.
Each property is accompanied by an icon that indicates its data type:
When a data source contains an array of properties of the same type, the array is represented by an icon that looks like a stack of data type icons. For example, an array of strings is represented by this icon:
If a data source has access to actual data (when, for example, you’ve specified a feed URL or you supply static data), data is displayed to the right of a property’s name. When the property value is an array, Dashcode displays the total number of array members and provides arrow controls you can use to step through the array. One array member at a time is displayed in a box revealed by a disclosure triangle.
When you hover over a property name, Dashcode displays a help tag that provides the key path of the property and its data type. The key path represents the property’s position in the hierarchy. A key path for a property named property_n is of the form property_1.property_2.[...].property_n, where property_1 is the root-level ancestor. For example, the Podcast template contains a data source that represents podcast data. The key path that locates the podcast title property in the data hierarchy is
Dashcode displays all existing bindings to the far right of a data source property. When no binding yet exists, Dashcode displays a binding control (a small circle) when you move the pointer over a property’s row. When you position the pointer over the binding control itself, it displays a plus symbol (+).
Existing bindings are displayed in a capsule to the right of a property; the capsule is visible until you remove the binding. Usually, the binding capsule contains a delete control on the left (it looks like an X), the property of the user interface element to which the item is bound, and a binding control on the right. However, if a single data source property has multiple bindings the capsule displays a disclosure triangle on the left and the word “Multiple” in place of the user interface property. Open the disclosure triangle in the capsule to reveal the set of bindings for that data source property.
A good example of a property with multiple bindings is the
queryInProgress property of the feed data source in the RSS template for web applications. This data source property is bound to both the visible and animating properties of the activity indicator part on the canvas. This ensures that when the application runs, the activity indicator is visible only while a query is in progress and that it spins until the query is finished.
As mentioned in “Changing an Element’s Properties,” you can also view and change bindings in the Bindings inspector. Whereas the data model view gives you a bindings-centric perspective on these connections, the Bindings inspector gives you an element-centric perspective. The Bindings inspector displays the bindable properties of the currently selected element and provides controls to create and change bindings. If a binding already exists on a property, the Bindings inspector displays the data source name and the complete key path of the bound property in the data source.
Safari HTML Reference
WebKit DOM Reference
To learn more about creating a webpage or web application optimized to run in Safari on iPhone, see Safari Web Content Guide.
Adding a Data Source
All Dashcode templates support data sources to represent the data provided to the widget or web application. Data sources and bindings work together to dispense data to user interface elements and allow them to stay in sync when the data changes. (See “Creating Bindings” to learn how to create bindings.)
To add a new data source, reveal the Data Sources list in the navigator (as described in “Viewing a Project’s Data Sources and Bindings”) and select New Data Source in the action menu below the list. Or, select File > New > Data Source. When you do this, the new data source appears in the list. (If you have a dual-product project, the new data source is automatically available in both products.)
To specify the location of a data source, you supply a URL for a JSON or XML feed. Note that you can also supply the local path of a file of static data to serve as the data source. You do not need to specify a location for a data source that represents a list or grid part.
There are two ways to supply the location of a data source, depending on the template your project uses. For all projects, you can enter a URL in the data model view of the new data source (you reveal the data model view when you select the data source in the Data Sources list). For projects based on RSS, Podcast, Maps, Photocast, Video Podcast, or Daily Feed templates, you can also enter a URL in the Properties section of the widget attributes or application attributes pane.
If you’ve entered a valid URL, Dashcode updates the data model view to display the available properties and attributes of the data, along with some actual data when possible.
All Dashcode templates support bindings, which allow a user interface element to get specific items of data from a data source and automatically update its display when that data changes.
Dashcode offers an easy way to create bindings in the data model view. To find out how to reveal this view and for a description of its contents, see “Viewing a Project’s Data Sources and Bindings.”
To create a binding between a data source property and an element on the canvas:
Press and hold the mouse button on the circular binding control next to the data source property, and drag the pointer to the element on the canvas that you want to bind to.
As you drag, a connection line extends from the binding control, and each element on the canvas highlights as you pass the pointer over it. (You can see an example of how this looks in Figure 3-8.)
Release the mouse button when the element you want to bind to is highlighted.
As soon as you stop dragging, Dashcode displays a contextual menu that lists the bindable properties of the selected element.
Choose the appropriate property to complete the binding.
If you choose not to complete the binding after you stop dragging, simply click outside of the contextual menu and the binding is not created.
If the Bindings inspector wasn’t visible before, it opens when you complete a binding, allowing you to specify a value transformer and placeholder text or values.
You can also create bindings in the Bindings inspector, without dragging from the data model view. To do this, follow these steps:
Select the element you want to bind to on the canvas or in the navigator.
When you do this, the Bindings inspector displays the bindable properties of the element.
In the Bindings inspector, open the disclosure triangle to the left of the element property you want to bind to.
Select the “Bind to” checkbox and choose a data source from the pop-up menu.
Open the Key Path pop-down menu to reveal the top-level properties of the selected data source.
Choose a data source property in the Key Path menu.
If the data source property you’re interested in is a child of a top-level property, click the pop-down control again to see a list of the current property’s children. Continue choosing child properties until you reach the one you want.
Because bindings are tightly integrated with user interface objects, you must create bindings separately in both products of a dual-product project. This is because each product uses different parts to display data, even though they can share a single data source.
Adding a Value Transformer
A value transformer is a function that takes a data source value and returns an appropriate display value, based on other information in the data source or contextual information in your code. For example, you might want to transform a temperature value from Fahrenheit to Celsius, or format a numerical value as a currency value.
Because a value transformer may need to interpret the data model and make decisions based on context, you must usually write it yourself. That said, Dashcode includes a few generic value transformers you can use, such as a reverse-value function. To specify a value transformer open the Bindings inspector and:
Select the user interface element that is bound to the data source item you want to transform.
Click the Value Transformer text field.
Dashcode displays the generic value transformers, along with any value transformers you’ve already included in your project, in a pop-down list.
Select an existing function or type the name of the function you plan to write and press Return.
If you select an existing value transformer, Dashcode displays an arrow control that you can click to see the function in the source code editor.
Dashcode includes several built-in value transformers in the
transformers.js file. You can customize some of these transformers by changing the default parameters. For example, the truncation value transformer (
DC.transformer.Truncated) automatically truncates the passed-in string to 10 characters, but you can change this by editing the transformer function. The
transformers.js file contains the following value transformers:
DC.transformer.Booleanreturns the Boolean value
TRUEif the passed-in value is equal to a value you supply as the “true value.” For example, you might designate the string “red” as the true value. Changing the Boolean value transformer to use this string, this value transformer returns
TRUEwhen the passed-in value is “red.”
You can also specify a reverse transformation for this function. If you want to do this, you also need to supply a “false value” that the function can use to test the passed-in value against. In this case, the transformer returns either the true or false value that you supplied, depending on which one the passed-in value matches.
DC.transformer.FirstObjectreturns the first object in an array.
DC.transformer.Matchesreturns the Boolean value
TRUEif the passed-in value matches a regular expression you define.
DC.transformer.Notreturns the opposite Boolean value of the passed-in value (that is, it returns
TRUEfor a value whose Boolean value is
DC.transformer.Truncatedtruncates the passed-in string to a number of characters that you define (or 10, by default), and adds an ellipsis.
Adding a Handler for an Event
Supporting Offline Usage of a Web Application
You might want to allow users to run your web application even if they lose their network connection. You can do this by taking advantage of the
manifest attribute available in the HTML 5 specification. The value of the
manifest attribute is the URL of a file that contains the resources your web application needs to have cached in order to run offline.
To enable offline usage of your web application, select the Offline Viewing checkbox in the General section of the application attributes pane. Dashcode adds the
manifest attribute to the
HTML element in the
Dashcode helps you support offline usage of your web application by providing some code snippets you can use to query and respond to changes in online status. You can elect to receive these events when the user goes online or offline, and you can write code to update the user interface or access different resources, as necessary.
Adding or Removing a Web Application Product
By default, Dashcode creates two products in a web application project: a mobile Safari web application (a web application optimized to run in Safari on iPhone) and a Safari web application. As described in “Creating a Project from a Template,” after you select a template to start your project, you choose whether you want to create both products, or only one.
Before you add or remove a product from your existing project, it’s important to understand how Dashcode organizes the files in your project. In a dual-product project, you see the following files and folders at the root level of the Files list (among other, optional files and folders):
The safari folder contains all the files and parts that are unique to the Safari web application.
The Images folder contains all the images that are common to both products.
index.htmlfile is the main HTML file for the project.
The mobile folder contains all the files and parts that are unique to the mobile Safari web application.
The Parts folder contains Dashcode parts and other code files that are common to both products.
As you can imagine, a project that creates only a mobile Safari web application does not contain a safari folder, and a project that creates only a Safari web application does not contain a mobile folder.
If you have a dual-product project, you can remove a product by choosing File > Delete Current Product, where Current is “Safari” or “Mobile Safari,” depending on which product is currently selected.
If you want to add a product to a single-destination project, choose File > Add Other Product, where Other is “Safari” or “Mobile Safari,” and represents the product you want to add.
Adding Code for Custom Controllers
If you add a list or grid part, you can write a controller for it that supplies data dynamically or you can bind the list to an array property in a data source. Or, you can combine these approaches and use bindings to get the number of rows and the data for each row, and a controller to configure each row.
Code Completion Using Code Sense
Dashcode’s source code editor includes a code completion feature that suggests possible variable and function names based on partially entered text. When Code Sense has a suggestion, it underlines the text you’re typing. To see the list of suggestions, press the Option and Escape keys. Use the Up and Down Arrow keys to select the symbol you want. To add the symbol, press the Tab key. To dismiss the suggestion list, press the Escape key.
See “Code Editing Preferences” for more information on how to set Code Sense preferences.
Dashcode includes a set of reusable code snippets. Each code snippet provides a bit of functionality that you can use to enhance your widget or web application. To show the code snippets, choose Window > Show Library and click the Code button. To add a code snippet to your project, drag it from the Code Library to the source code editor.
In addition to the code snippets included with Dashcode, you can save your own snippets for later use by dragging them from the source code editor to a group you create in the Code Library. To create a new group, choose New Group from the action menu under the listings in the Code Library.
Adding and Moving Files and Folders
To add a folder to your project, choose File > New > Folder. To add items to the folder, drag them on to its icon.
In the Files list, you can rename, duplicate, move, and delete files and folders. To rename an item, select it in the Files list and choose Rename from the action menu (the gear icon beneath the Files list). To duplicate an item, choose Duplicate from the action menu. To remove an item, choose Move to Trash from the action menu. To move an item, drag its icon to another folder’s icon.
Resource Access for Widgets
If you intend to use any of the following resources in your widget, you need to turn on access to them first:
Network resources (including
Internet plug-ins, such as QuickTime and Quartz Composer
Turn on access to these resources, select Widget Attributes in the navigator. Then select the option for the resource you want to use. Options include:
- Network / Disk Access
If your widget requires access to network resources or files on disk, select the appropriate item. Unless your template already needs access to network resources (such as
XMLHttpRequest) and files on disk outside of your widget bundle, these resources are turned off.
If your widget uses content provided through an Internet plug-in or a Java applet, or uses a command-line utility via
widget.system, select the appropriate option. Unless your template already needs access to plug-ins (such as QuickTime), Java, and command-line utilities, these resources are turned off.
Code Editing Preferences
The source code editor has a number of preferences you can set to change its behavior to better suit your tastes. To show these preferences, choose Dashcode > Preferences. The Preferences window includes the following items:
General preferences include an option for opening source code files in Dashcode or in a helper application.
The source code editor has various visibility and behavior preferences, including the visibility of the gutter and line number next to your source code, the source code editor’s line wrapping, and the Tab key’s indentation behavior. You can set these preferences in Editing preferences.
Your source code can be colored based on the code’s syntax. You can adjust text font, size, and color in Formatting preferences.
Dashcode offers a code completion feature called Code Sense (as described in “Code Completion Using Code Sense”). At the top of the source code editor, a pop-up menu shows the symbols in a file. Code Sense preferences include a setting for how these symbols are organized. This pane also includes settings for code completion.