|
1 <?xml version="1.0" encoding="UTF-8"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|
2 <html lang="en" xml:lang="en"> |
|
3 <head> |
|
4 <meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> |
|
5 <meta name="copyright" content="(C) Copyright 2005" /> |
|
6 <meta name="DC.rights.owner" content="(C) Copyright 2005" /> |
|
7 <meta content="concept" name="DC.Type" /> |
|
8 <meta name="DC.Title" content="Planning the widget" /> |
|
9 <meta scheme="URI" name="DC.Relation" content="WRTKit_Travel_Companion_Tutorial-GUID-be79ba64-fa03-4968-964e-d7dcc42d7053.html" /> |
|
10 <meta content="XHTML" name="DC.Format" /> |
|
11 <meta content="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB" name="DC.Identifier" /> |
|
12 <meta content="en" name="DC.Language" /> |
|
13 <link href="commonltr.css" type="text/css" rel="stylesheet" /> |
|
14 <title> |
|
15 Planning the widget</title> |
|
16 </head> |
|
17 <body id="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB"><a name="GUID-891068C7-C802-4DA7-8674-8E8292AEF7EB"><!-- --></a> |
|
18 |
|
19 |
|
20 |
|
21 <h1 class="topictitle1"> |
|
22 Planning the widget</h1> |
|
23 |
|
24 <div> |
|
25 |
|
26 <div class="section"><h2 class="sectiontitle"> |
|
27 Designing the user interface</h2> |
|
28 |
|
29 |
|
30 <p> |
|
31 |
|
32 Because the Travel Companion is such a complex widget it is important to plan |
|
33 both the user interface and implementation carefully before starting to write |
|
34 any code. What are the most common use cases that we want to address with this |
|
35 widget? How will typical users be using the widget? What kind of future features |
|
36 might there be and can we plan for those already? |
|
37 </p> |
|
38 |
|
39 <p> |
|
40 |
|
41 Because the Travel Companion widget offers so much functionality and information |
|
42 it is important to present it in such a way that it doesn't overwhelm the user. |
|
43 To give the user a better idea of what is available and how to get to everything, |
|
44 we'll have a main view with nothing but navigation buttons to the other views in |
|
45 the widget. We'll implement this view using WRTKit NavigationButton controls and |
|
46 we will give each button its own icon so that the user can quickly see what the |
|
47 view is about. |
|
48 </p> |
|
49 |
|
50 <p> |
|
51 |
|
52 After some planning and talking to potential users we have decided to create |
|
53 a summary view that we will call "information view". This view will include the |
|
54 most important information in a single place so that the user can view it quickly |
|
55 without having to press any buttons to navigate around the widget. We'll put a |
|
56 world clock here, the current weather at home and at the local destination, and |
|
57 the latest news headlines. The information view will be entirely composed from |
|
58 WRTKit ContentPanel controls. |
|
59 </p> |
|
60 |
|
61 <p> |
|
62 |
|
63 In addition to the information view we'll have two more specialized views. We'll |
|
64 have a currency converter with two TextField controls (one for the home currency |
|
65 and one for the local) and two FormButton controls. One button will convert |
|
66 from the home currency to local currency and the other button will convert in the |
|
67 other direction. The second specialized view is a five day weather forecast. Like |
|
68 the information view this will be using ContentPanel controls and we will share |
|
69 the weather content used for the information view for this view. |
|
70 </p> |
|
71 |
|
72 <p> |
|
73 |
|
74 Finally we'll have a settings view that is accessible from the main view just like |
|
75 the other views in the widget. In many other widgets we might want to hide access |
|
76 to the settings view to the Options menu but in this case one of the common use |
|
77 cases is to configure where in the world you are so rather than hiding access to |
|
78 the view we want to present it clearly in the main view. The settings view will |
|
79 use SelectionMenu controls to allow users to select their home and local cities, |
|
80 SelectionList controls with a single option that will be presented as a checkbox |
|
81 to configure whether the cities are in daylight saving time or not, and a |
|
82 SelectionList control that lets the user select the temperature unit to use in |
|
83 the weather forecasts. Finally there will be two FormButton controls to let the |
|
84 user save or cancel any settings changes. |
|
85 </p> |
|
86 |
|
87 <p> |
|
88 |
|
89 When the widget starts will setup a timer that will call a timer callback function |
|
90 once every second. In the callback function we will check what view is currently |
|
91 active and we'll update the views (e.g. clock) so that the views stays up to date |
|
92 even if the user doesn't do anything. After all, the most common use case is to |
|
93 just have the information view open and not do anything other than glance at the |
|
94 information that is displayed. |
|
95 </p> |
|
96 |
|
97 </div> |
|
98 |
|
99 <div class="section"><h2 class="sectiontitle"> |
|
100 Travel Companion widget files</h2> |
|
101 |
|
102 |
|
103 <p> |
|
104 |
|
105 All the files - HTML, CSS, JavaScript and images - have been created for you. |
|
106 You can find the completed widget with all its files in the Examples/TravelCompanion |
|
107 directory in the WRTKit SDK. The tutorial will assume that you will create your |
|
108 own Travel Companion widget by following the instructions but if you prefer you can |
|
109 just open up the ready made files and examine them as you read the tutorial. If you |
|
110 are creating the widget from scratch by following the tutorial's instructions then |
|
111 we suggest that you create a working directory for the new widget and copy over all |
|
112 other ready made files except TravelCompanion.js. All of our work will be on this |
|
113 file, but before we move on to that file we'll take a look at what other files the |
|
114 widget is using. |
|
115 </p> |
|
116 |
|
117 <p> |
|
118 |
|
119 Since we're using the WRTKit to implement our user interface we have the WRTKit |
|
120 library with all its files in a directory called "WRTKit". |
|
121 </p> |
|
122 |
|
123 <p> |
|
124 |
|
125 Like all widgets the Travel Companion has an Info.plist widget metadata file and an |
|
126 icon in a file called Icon.png. You'll also notice that there's a bunch of png |
|
127 image files in the widget directory. There's a file called ListViewCaptionLogo.png |
|
128 that we will use as a custom graphical element in the view caption in all of our |
|
129 views. Four png files have names starting with "Nav" and the rest start with |
|
130 "Weather". The image files that have names starting with "Nav" are icons for the |
|
131 NavigationButton controls for the main view. They are simply images that are |
|
132 30 by 30 pixels in size and have some graphical motif that captures what the button |
|
133 does. Note that the size of images used for navigation buttons doesn't have to be |
|
134 exactly 30 by 30 pixels - you can use any size you like. The images with names |
|
135 starting with "Weather" are images used in the weather forecasts. There is one image |
|
136 for each kind of weather that can be forecasted: rain, snow, sunshine, clouds, etc. |
|
137 </p> |
|
138 |
|
139 <p> |
|
140 |
|
141 You'll find two JavaScript files: Engine.js and TravelCompanion.js. The Engine.js |
|
142 file has the implementation of the business logic and the TravelCompanion.js file |
|
143 implements the widget and its user interface. Finally there is the main widget HTML |
|
144 file called TravelCompanion.html and a CSS file called TravelCompanion.css that |
|
145 contains all the style rules used in the widget - above that what the WRTKit defines |
|
146 by default, which is actually nearly everything! |
|
147 </p> |
|
148 |
|
149 <p> |
|
150 |
|
151 Let's take a quick peek at TravelCompanion.html: |
|
152 </p> |
|
153 |
|
154 <pre> |
|
155 |
|
156 <?xml version="1.0" encoding="UTF-8"?> |
|
157 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
|
158 <html xmlns="http://www.w3.org/1999/xhtml"> |
|
159 <head> |
|
160 <title></title> |
|
161 <script type="text/javascript" src="WRTKit/WRTKit.js"></script> |
|
162 <script type="text/javascript" src="Engine.js"></script> |
|
163 <script type="text/javascript" src="TravelCompanion.js"></script> |
|
164 <style type="text/css"> |
|
165 @import url("TravelCompanion.css"); |
|
166 </style> |
|
167 </head> |
|
168 <body onload="init()"> |
|
169 </body> |
|
170 </html> |
|
171 </pre> |
|
172 |
|
173 <p> |
|
174 |
|
175 If you've gone through the Hello World and/or RSS Reader tutorials then this should |
|
176 look very familiar. The file has no content, includes the WRTKit.js file from the |
|
177 WRTKit library directory, includes the JavaScript files that we are using to implement |
|
178 the Travel Companion widget, includes the TravelCompanion.css stylesheet file, and |
|
179 finally calls a function called init() when the widget has loaded everything. |
|
180 </p> |
|
181 |
|
182 </div> |
|
183 |
|
184 <div class="section"><h2 class="sectiontitle"> |
|
185 The Travel Companion Engine</h2> |
|
186 |
|
187 |
|
188 <p> |
|
189 |
|
190 Following good software engineering principles, we are implementing the Travel Companion |
|
191 widget so that the user interface is decoupled from the implementation of the actual |
|
192 business logic that knows weather forecasts, calculates currency conversions, etc. The |
|
193 logic is outside of the scope for this tutorial since we're interested in learning about |
|
194 how to use the WRTKit - not how to convert euros to dollars. Because of this we will not |
|
195 look at all at how the business logic is implemented but we will take a close look at |
|
196 the interface between the user interface and the business logic engine. In fact, the |
|
197 implementation of the engine for this example is a mock implementation and only mimics |
|
198 what a real engine would do. But since this is only an example that's quite alright. |
|
199 The engine interface, however, is identical to what it would be even if the engine would |
|
200 have a real implementation. |
|
201 </p> |
|
202 |
|
203 <p> |
|
204 |
|
205 The engine is implemented as a JavaScript class that you instantiate before using. |
|
206 The reason for being implemented as a class is simply so that the engine can better |
|
207 encapsulate its internal data and provide a kind of name space for its methods. |
|
208 </p> |
|
209 |
|
210 <p> |
|
211 |
|
212 The core concept in the Travel Companion engine is that of cities. The engine supports |
|
213 a list of cities and one will always be a "home city" and one a "local city". The |
|
214 same city can be both home and local. Home refers to the city where the user lives |
|
215 and local refers to the city where the user is currently located. The engine doesn't |
|
216 know the daylight saving time schedules for cities so this is configured manually by |
|
217 the user: one setting for the home city and one for the local city. The engine handles |
|
218 all preferences but the user interface must tell it to save preferences if some |
|
219 preference is modified. Preferences are automatically loaded when the engine is |
|
220 created, which should happen when the widget starts so that all the settings are |
|
221 available immediately. |
|
222 </p> |
|
223 |
|
224 <p> |
|
225 |
|
226 A city in the engine is a JavaScript object. A city object has the following public |
|
227 properties: name for the city name, currency for the three-letter currency abbreviation, |
|
228 and timezone for the timezone code (e.g. GMT). Cities are created and managed entirely |
|
229 by the engine. |
|
230 </p> |
|
231 |
|
232 <p> |
|
233 |
|
234 Below is a complete list of the public engine APIs that are related to preferences and |
|
235 cities: |
|
236 </p> |
|
237 |
|
238 <p> |
|
239 |
|
240 Loading and saving preferences: |
|
241 </p> |
|
242 |
|
243 <pre> |
|
244 |
|
245 [void] Engine.loadPreferences(void) |
|
246 [void] Engine.savePreferences(void) |
|
247 </pre> |
|
248 |
|
249 <p> |
|
250 |
|
251 Retrieving all cities supported by the engine: |
|
252 </p> |
|
253 |
|
254 <pre> |
|
255 |
|
256 [Array] Engine.getCities(void) |
|
257 </pre> |
|
258 |
|
259 <p> |
|
260 |
|
261 Retrieving a city based on its name: |
|
262 </p> |
|
263 |
|
264 <pre> |
|
265 |
|
266 [City] Engine.getCityByName(String name) |
|
267 </pre> |
|
268 |
|
269 <p> |
|
270 |
|
271 Retrieving and settting the home city: |
|
272 </p> |
|
273 |
|
274 <pre> |
|
275 |
|
276 [City] Engine.getHomeCity(void) |
|
277 [void] Engine.setHomeCity(City city) |
|
278 </pre> |
|
279 |
|
280 <p> |
|
281 |
|
282 Retrieving and settting the home city daylight saving time setting: |
|
283 </p> |
|
284 |
|
285 <pre> |
|
286 |
|
287 [Boolean] Engine.getHomeCityDST(void) |
|
288 [void] Engine.setHomeCityDST(Boolean dst) |
|
289 </pre> |
|
290 |
|
291 <p> |
|
292 |
|
293 Retrieving and settting the local city: |
|
294 </p> |
|
295 |
|
296 <pre> |
|
297 |
|
298 [City] Engine.getLocalCity(void) |
|
299 [void] Engine.setLocalCity(City city) |
|
300 </pre> |
|
301 |
|
302 <p> |
|
303 |
|
304 Retrieving and settting the local city daylight saving time setting: |
|
305 </p> |
|
306 |
|
307 <pre> |
|
308 |
|
309 [Boolean] Engine.getLocalCityDST(void) |
|
310 [void] Engine.setLocalCityDST(Boolean dst) |
|
311 </pre> |
|
312 |
|
313 <p> |
|
314 |
|
315 Retrieving and setting the preferred temperature unit: |
|
316 </p> |
|
317 |
|
318 <pre> |
|
319 |
|
320 [String] Engine.getTemperatureUnit(void) |
|
321 [void] Engine.setTemperatureUnit(String unit) |
|
322 </pre> |
|
323 |
|
324 <p> |
|
325 |
|
326 Of course the engine isn't just about preferences. Its actual purpose is to perform |
|
327 various operations related to these cities, such as converting currencies, figuring |
|
328 out what the time is in a foreign city, etc. To simplify the usage of the engine, |
|
329 the public methods related to these operations are defined in terms of the home and |
|
330 local city as it is configured at the time when the method is called. |
|
331 </p> |
|
332 |
|
333 <p> |
|
334 |
|
335 Here's the full list of the actual operation methods that the engine supports: |
|
336 </p> |
|
337 |
|
338 <p> |
|
339 |
|
340 Currency conversions between home and local: |
|
341 </p> |
|
342 |
|
343 <pre> |
|
344 |
|
345 [Float] Engine.convertHomeToLocalMoney(Float amount) |
|
346 [Float] Engine.convertLocalToHomeMoney(Float amount) |
|
347 </pre> |
|
348 |
|
349 <p> |
|
350 |
|
351 Retrieving the current time in the home and local cities: |
|
352 </p> |
|
353 |
|
354 <pre> |
|
355 |
|
356 [DateTime] Engine.getHomeTime(void) |
|
357 [DateTime] Engine.getLocalTime(void) |
|
358 </pre> |
|
359 |
|
360 <p> |
|
361 |
|
362 The DateTime object returned by getHomeTime() and getLocalTime() is a JavaScript |
|
363 object that contains the following properties: year, month, date, day, hours, minutes, |
|
364 seconds, timezone. All properties are integers except the timezone, which is a string |
|
365 that represents the timezone code, e.g. "EET" for "Eastern European Time". Month and |
|
366 day are zero-based to simplify their use as indexes in arrays that contains the month |
|
367 and week day names. These arrays can be found in the DateTime object. The array for |
|
368 week day names is called dayNames and the array for month names is called monthNames. |
|
369 Day 0 is Sunday and month 0 is January. To find out the name of the day represented |
|
370 by a DateTime object you would do the following: |
|
371 </p> |
|
372 |
|
373 <pre> |
|
374 |
|
375 var homeTime = engine.getHomeTime(); |
|
376 var dayOfWeekName = homeTime.dayNames[homeTime.day]; |
|
377 </pre> |
|
378 |
|
379 <p> |
|
380 |
|
381 Note that the default JavaScript Date object is not used because of its timezone- |
|
382 related limitations. |
|
383 </p> |
|
384 |
|
385 <p> |
|
386 |
|
387 Retrieving 5-day forecasts for the home and local cities: |
|
388 </p> |
|
389 |
|
390 <pre> |
|
391 |
|
392 [Array] Engine.getHomeWeather(void) |
|
393 [Array] Engine.getLocalWeather(void) |
|
394 </pre> |
|
395 |
|
396 <p> |
|
397 |
|
398 The array returned by the getHomeWeather() and getLocalWeather() methods contains |
|
399 the weather for the next five days so that the first element is the weather today, |
|
400 the second is the weather tomorrow, etc. Each item is a JavaScript object that |
|
401 has two properties: temperature, which is an integer in the preferred temperature |
|
402 unit, and type, which is a string that describes the weather. The type string is |
|
403 one of the following: "Sunny", "PartlyCloudy", "Cloudy", "Rain", "Sleet" or Snow". |
|
404 There is a weather type image for each of these, named so that there is a "Weather" |
|
405 prefix in front of the weather type and a ".png" suffix after it, e.g. "WeatherSunny.png". |
|
406 </p> |
|
407 |
|
408 <p> |
|
409 |
|
410 Retrieving an array of the latest news headlines: |
|
411 </p> |
|
412 |
|
413 <pre> |
|
414 |
|
415 [Array] Engine.getNewsHeadlines(void) |
|
416 </pre> |
|
417 |
|
418 <p> |
|
419 |
|
420 Each item in the array that the getNewsHeadlines() method returns is a JavaScript |
|
421 object that describes one news headline. Each news headline object has two |
|
422 properties: headline for the actual news headline text and url for the website |
|
423 address where the full news article is located. |
|
424 </p> |
|
425 |
|
426 </div> |
|
427 |
|
428 </div> |
|
429 |
|
430 <div> |
|
431 <div class="familylinks"> |
|
432 <div class="parentlink"><strong>Parent topic:</strong> <a href="WRTKit_Travel_Companion_Tutorial-GUID-be79ba64-fa03-4968-964e-d7dcc42d7053.html">Travel Companion</a></div> |
|
433 </div> |
|
434 </div> |
|
435 |
|
436 </body> |
|
437 </html> |