Beginning Mac OS X Tiger Dashboard Widget Development (2006)

Widget Development Environment

Figure 3-16

From the break point you can step through the code — stepping into, out of, and over calls — or run to the next break point or until complete. Widgetarium also allows you to set trace points in your JavaScript.

Try It Out

Debugging Error Messages

Now that you know a little about the debugging tools that you have at your disposal, let’s use one of them to see how an error would appear. To set this up, show the package contents of the installed Fortune widget and remove the SimplePlugin.widgetplugin folder that you installed earlier. If you have the Fortune widget loaded in Dashboard, you will also need to remove it and add it again.

1.Show the JavaScript console by selecting it from Safari’s Debug menu. Position the console so you can see it and the Safari window at the same time.

2.Open the Fortune.html file in Safari. With the plugin removed, you should see only the “Click here to obtain a fortune” placeholder text.

3.Click the fortune cookie in the Safari window.

51

Chapter 3

4.Look in the console window and you’ll see the error message about the missing plugin (Figure 3-17).

Figure 3-17

How It Works

The JavaScript Console gets any JavaScript errors that are generated in Safari. But these error messages also find their way into the OS X console.log (Figure 3-18). You can see these by opening the Console application in the Utility folder in the Applications folder.

Figure 3-18

To see the console.log, you may need to click the Logs button at the top of the window and select the console.log in the list on the left. The line at the bottom of the window is the error you see in the JavaScript console.

52

Widget Development Environment

[227] file:///Users/pfterry/Projects/fortune/Fortune/Fortune.html:ReferenceError - Can’t find variable: FortunePlugin

The line in console.log gives you the file that generated the error. If you look in the Fortune.html file, you’ll see the link to the JavaScript file.

<!-- The JavaScript for this widget -->

<script type=’text/javascript’ src=’Fortune.js’ charset=’utf-8’/>

As you saw earlier, the JavaScript is supposed to get the fortune from the plugin and place it in the widget.

As you can see, the system’s console.log file contains more information about the error than the JavaScript console, so you may prefer to use it when you are trying to track down difficult problems. The downside of using the console.log is that you see information from all of the processes running on your machine. If you have enough screen real estate, you can use Tynsoe’s GeekTool preference pane to display the console.log file in your desktop to reduce the number of windows that you have open and allow you to check for problems with a glance at your desktop.

Summar y

You could purchase third-party tools for your widget development, but you don’t have to. Most of the tools that you need are freely available and ship with OS X. Third-party tools can speed your development cycles because they directly support widget development and may have features that work around system limitations.

In this chapter, you learned:

What the available programming tools are for developing widgets

How to compile a plugin

How to use a debugging tool

In Chapter 4, you create your first widget. Before you turn to Chapter 4, you may want to run through these exercises to review what you’ve learned in this chapter.

Exercises

1.How do you allow the Fortune widget to use the SimplePlugin?

2.Will the SimplePlugin display the next fortune if you are testing the Fortune widget in Safari?

3.How can you edit a widget installed in the /Macintosh HD/Library/Widgets/ folder?

53

4

Creating a Widget

In Chapter 3 you looked at the different tools available for developing Dashboard widgets and learned that you could use any text editor to create your source files and that you could use Safari for testing your widget. You also learned some strategies for testing your widget during development and how to compile a plugin. In this chapter, you create a widget from scratch, building it from the HTML and CSS through the JavaScript functionality.

By the end of this chapter, you will know:

How to begin developing a basic widget

How to use HTML and cascading styles sheets to give shape to the widget

How to incorporate JavaScript into your widget

HTML Beginnings

In the previous chapters you spent some time looking at the way widgets have been assembled, now let’s use what you’ve learned to create a widget from scratch.

You can develop a widget from any website that you visit on a regular basis or routine tasks that can be accessed through the filesystem or performed by script. Or to put it more succinctly, anything you can do in a browser can be developed into a widget.

I check the weather maps for my region of the country at least twice a day. If storms are moving into the area, I may check them once an hour. I can reduce my trips to the browser by creating a widget that displays the maps I always check. Let’s call it WeatherMaps.

Beginning the Project

Everyone starts a project from a different point. If you are working with a team of programmers developing a large and complex program for the marketplace, you typically begin with specifications and use case interviews and diagrams. Widgets lend themselves to a much smaller scope.

Chapter 4

You don’t need a specifications document, but you may want to decide on the functionality of your widget before you begin hacking HTML and JavaScript. This need not be complicated; just a listing of features that you want in the widget and how you want them to behave will suffice. This will change, of course, as you develop your widget and you spend time using it.

The real advantage of developing a list of features (or formal specifications or use case scenarios, for that matter) is that you start thinking about how to organize the development. I know I want this widget to accomplish the following tasks:

It should get the current radar.

It should get the current temps map.

It should get the overnight temps map.

It should get tomorrow’s temps map.

I may decide that this is the only way to view weather maps and add a few more to the list. When I look at the map, I’ll see that it is pretty large for my PowerBook screen, so showing multiple maps at once is probably not an option (Figure 4-1).

Figure 4-1

56

Creating a Widget

The size of the map probably won’t even allow enough space for the other widgets I normally keep open. The size of the maps also makes using them on the typical widget backgrounds not an option. As I check the maps that I want to display, I also notice that they are two different sizes. Whatever I use

as a background for the current weather map will leave a noticeable gap when I display the current temperature maps. The following questions become design considerations as I’m working on the widget:

Can the current weather map be resized so it is the same size as the current temps and overnight temperature maps?

If all of the maps won’t fit on the screen at the same time, how can switching among them be made easier?

What can I use as a widget background?

If the widget is going to be shared, how can others set the maps they want to view?

You may be able to think of several or a dozen additional things to consider, but you get the idea. By making a list of the features you want your widget to have and then thinking about their uses, you will be able to come up with a list of items to consider as the widget takes shape. You can keep the list on paper or in a text editor file, but keep it nearby while you are developing the widget so you can review and add to it.

Begin with HTML

Because Dashboard widgets are essentially web pages, the best place to begin is with the HTML that you will use to retrieve the maps.

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>

<html xmlns=”http://www.w3.org/1999/xhtml”> <head>

<title>WeatherMaps</title>

</head>

<body>

<img src=”http://image.weather.com/web/radar/us_mkc_closeradar_large_usen.jpg”> <!--

http://image.weather.com/web/radar/us_mkc_closeradar_medium_usen.jpg http://image.weather.com/images/maps/current/cen_curtemp_720x486.jpg http://image.weather.com/images/maps/forecast/map_lotmpf_night1_3usc_enus_600x405.j pg http://image.weather.com/images/maps/forecast/map_hitmpf_day2_3usc_enus_600x405.jpg -->

</body>

</html>

This is a bit of straightforward HTML wrapped around the radar map. This widget allows you to check the current radar map without loading all of the ads and content on the web page that you aren’t interested in at the moment. You can find the URL of the radar map by right-clicking it and selecting the Open Image in New Window or Open Image in New Tab options. When you do this, the map loads in a separate page with the URL of the map itself in the location window.

57

Chapter 4

You can gather the URLs of the other maps that you want to retrieve and include them in a comment at the bottom of the page. This makes it easier for you to check the sizes of the other maps as you begin to develop your widget.

The link to this radar map and the temperature maps discussed later in this chapter were obtained by Control-clicking the map at weather.com’s website. You may want to insert maps for your region or part of the world.

If you look back to your list of design considerations, you’ll see that the size of the maps is the first thing you’re thinking about. HTML has a way of resizing images as they are loaded that may work for your widget. You do this by setting the height and width of the image in the source line like so:

<img src=”http://image.weather.com/web/radar/us_mkc_closeradar_large_usen.jpg” width=”432” height=”290”>

Setting the height and width of the image in the source line results in a weather map that is a size more conducive to display on screen (Figure 4-2).

Figure 4-2

58

Creating a Widget

Setting the height and width of the image in the source line solves two design considerations at once: the large size of the maps and making the maps the same size. The trick is to display the resized maps with the same proportions as the original ones. If you just type in any numbers, you could have an elongated mess. You can try trial and error until the maps look right, but you can’t automate that process very well in the future if the map sizes change. You can start with the current temps map because it tells you the image size is 720 × 486 in the name of the map. Multiply these numbers by .60 to reduce the size of the maps by 60 percent. This calculation returns an image size of 432 × 290, which — as you can see in Figure 4-2 — is proportional.

As a test that all of the images look good with their new sizes, you can move all of the commented URLs into the body of the HTML so they are all displayed together in the web page. Once you are satisfied that the maps are the same size and can be swapped without leaving any space around them, you can work on putting together the remaining portions of the widget.

You now have the basic HTML document that you can use for your widget. You are ready to create a background that will serve as the user interface as you add more functionality.

Adding a Background

If you look at the backgrounds of different widgets, you’ll see that they can be very elaborate or quite simple. As you noticed in Chapter 2, the Weather widget has a simple background, and the weather information comes from the graphics representing day and night and the different weather conditions placed on top of it. The Stocks widget is also based on a simple rectangle with the information provided through the share price and charts.

Because one of the design considerations is how to switch among the different maps, you know that you may want to add controls along the top or bottom of the widget. For the moment, however, you’ll just need to create a background on which to display your maps.

You can create your background image in any graphics application that you prefer. The only requirement is that the application should be able to save your background as a PNG file. Graphics Converter, a shareware graphics application, can save files in this format. If you have a copy of Widgetarium, it can export your background image as PNG and will even name it Default.png. In Widgetarium, you can open the Panel Maker window and enter the width and height values of your background as well as the style and color of the background (Figure 4-3).

When you have your background the size and color that you want, you can save it using the Export Graphic command. If you do this inside of a Widgetarium project, saving the background is done for you automatically and the back side and icon images are created for you at the same time.

When you assemble all of the pieces in your widget directory, Dashboard automatically picks up the PNG file named Default.png that is in the widget directory. If you want to test the background image in Safari with your maps before you install the widget in Dashboard, you need to add the Default.png to your HTML file.

<!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Strict//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd”>

<html xmlns=”http://www.w3.org/1999/xhtml”>

59

Chapter 4

<head>

<title>weathermaps</title> </head> <body>

<img src=”Default.png”>

<img src=”http://image.weather.com/web/radar/us_mkc_closeradar_large_usen.jpg” width=”432” height=”290”>

<!-- http://image.weather.com/web/radar/us_mkc_closeradar_medium_usen.jpg http://image.weather.com/images/maps/current/cen_curtemp_720x486.jpg

http://image.weather.com/images/maps/forecast/map_lotmpf_night1_3usc_enus_600x405.j pg http://image.weather.com/images/maps/forecast/map_hitmpf_day2_3usc_enus_600x405.jpg -->

</body>

</html>

When you have done this, you can open your widget’s HTML file in Safari to preview what it will look like. Though the map isn’t overlaid on your background, you can see that the map will fit inside of the background image you’ve created for the widget (Figure 4-4).

Figure 4-3

60