org.symbian.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_first_steps-GUID-db42b227-1647-4020-bdb9-dacb26771779.html
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/org.symbian.wrttools.doc.WRTKit/html/WRTKit_RSS_Reader_first_steps-GUID-db42b227-1647-4020-bdb9-dacb26771779.html Thu Mar 04 15:42:37 2010 -0800
@@ -0,0 +1,236 @@
+<?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">
+<html lang="en" xml:lang="en">
+<head>
+<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
+<meta name="copyright" content="(C) Copyright 2005" />
+<meta name="DC.rights.owner" content="(C) Copyright 2005" />
+<meta content="concept" name="DC.Type" />
+<meta name="DC.Title" content="First steps" />
+<meta scheme="URI" name="DC.Relation" content="WRTKit_RSS_Reader_Tutorial-GUID-678d197f-c7b0-4e5e-85e2-f8549c75bbe8.html" />
+<meta content="XHTML" name="DC.Format" />
+<meta content="GUID-DB42B227-1647-4020-BDB9-DACB26771779" name="DC.Identifier" />
+<meta content="en" name="DC.Language" />
+<link href="commonltr.css" type="text/css" rel="stylesheet" />
+<title>
+First steps</title>
+</head>
+<body id="GUID-DB42B227-1647-4020-BDB9-DACB26771779"><a name="GUID-DB42B227-1647-4020-BDB9-DACB26771779"><!-- --></a>
+
+
+
+ <h1 class="topictitle1">
+First steps</h1>
+
+ <div>
+
+ <div class="section"><h2 class="sectiontitle">
+Preparations</h2>
+
+
+ <p>
+
+ You can find the ready made RSS Reader example in the Examples/RSSReader directory
+ in the WRTKit SDK. In there you can find the by-now familiar widget files: Info.plist
+ for the widget metadata, Icon.png for the S60 application grid icon, and the WRTKit
+ directory for the WRTKit user interface toolkit. You will also find the main HTML
+ file RSSReader.html, a CSS file called RSSReader.css and two JavaScript files
+ RSSReader.js and FeedUpdateBroker.js. As with all WRTKit -based widgets, we will
+ be focusing on the JavaScript files but before we get to those, let's see take a
+ look at the main HTML file:
+ </p>
+
+<pre>
+
+<?xml version="1.0" encoding="UTF-8"?>
+<!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></title>
+ <script type="text/javascript" src="WRTKit/WRTKit.js"></script>
+ <script type="text/javascript" src="FeedUpdateBroker.js"></script>
+ <script type="text/javascript" src="RSSReader.js"></script>
+ <style type="text/css">
+ @import url("RSSReader.css");
+ </style>
+ </head>
+ <body onload="init()">
+ </body>
+</html>
+</pre>
+
+ <p>
+
+ You probably immediately noticed that the file is almost identical to the HTML file
+ for the Hello World widget. This is despite that the RSS Reader is much more complex.
+ In fact the only differences are that we are including the two JavaScript files
+ FeedUpdateBroker.js and RSSReader.js instead of HelloWorld.js as in the Hello World
+ widget. That, and the fact that we have a CSS stylesheet file that we also import here,
+ called RSSReader.css. Like for the Hello World widget we have an onload-event handler
+ that calls a function called init() in the JavaScript to allow us to initialize the
+ widget after everything is loaded.
+ </p>
+
+ <p>
+
+ You can either examine the ready made files or create your own files as you read the
+ tutorial. The tutorial assumes that you will create your own. If you're doing that then
+ now would be a good time to create a working directory for your own widget, call it
+ RSSReader and copy the WRTKit directory, Info.plist, Icon.png and the FeedUpdateBroker.js
+ file to the your own working directory. The FeedUpdateBroker.js is an AJAX-based RSS
+ fetcher and parser that we will be using in this example. It doesn't really have anything
+ to do with the WRTKit or the user interface for the RSS Reader but we need it in order
+ to be able to fetch and parse RSS feed news items. We will not create it in this tutorial
+ and thus you should just copy it to your own widget working directory.
+ </p>
+
+ <p>
+
+ At this point you can also create an empty placeholder for the CSS stylesheet file
+ (RSSReader.css) so that you have the file ready for when we'll create some CSS rules
+ for the widget. Also create an empty placeholder for the RSSReader.js file where the
+ majority of the widget's code will go. We'll return to this in a little bit!
+ </p>
+
+ </div>
+
+ <div class="section"><h2 class="sectiontitle">
+Architecture</h2>
+
+
+ <p>
+
+ Before we write any code, let's talk about what the architecture of the RSS Reader
+ will be like. As we previously mentioned, the widget will have two views. A main
+ view for showing feed news items and a settings view to allow users to configure
+ what RSS feed to show and how often to update it. We also said that we'll have a
+ custom Options menu.
+ </p>
+
+ <p>
+
+ The entire code that implements fetching and parsing RSS feeds will be implemented
+ in the file FeedUpdateBroker.js. The widget code will use it through only one single
+ method: fetchFeed(). The way this works is that we will pass the URL of the RSS
+ feed to the method, as well as a function that will get called when the fetch has
+ been completed. Note that this call is asynchronous - it will immediately return
+ after it's called and the actual outcome of the fetch will not be known until the
+ callback method is called. As an argument to the callback we will receive an object
+ with three properties: status, lastModified and items. The status property will
+ contain a value of either "ok" or "error" depending on the outcome. The lastModified
+ will be present in case the fetch was successful and contains a timestamp that
+ indicates when the RSS feed was last updated. This will allow us to determine whether
+ there is any new news items or not so that we only update the user interface if there
+ really is something to update. Finally the third property "items" contains an array
+ of parsed RSS news items. Each of these is a JavaScript object that has four
+ properties: title for the news item headline, date to indicate when it was created,
+ description for the news item summary, and link with an URL to the full story.
+ </p>
+
+ <p>
+
+ We will setup a timer in the widget that will run a function once every second. In
+ this function we will compare the current time to a scheduled "next update" time.
+ If we have reached the next update time, we will use the feed update broker to fetch
+ the RSS news items of the feed that we're interested in. When the feed has been
+ fetched and parsed a callback method will be called and we will react to the callback
+ by either showing an error message (if the update failed), ignoring the callback (if
+ there was no new news items for us), or update the user interface (if there's new
+ news items to show).
+ </p>
+
+ <p>
+
+ We also want to be able to update the news items on request and for that we will
+ put an option in the Options menu that triggers a function that sets the next
+ scheduled update time to be immediately. That way the normal update timer will
+ immediately get triggered and cause an update.
+ </p>
+
+ <p>
+
+ We will also set the "next update" time whenever the feed update broker is used
+ to fetch new news items. That way we will get an automatic periodic update of the
+ news that will run in the background but can also be triggered to run immediately
+ if the user asks it to be.
+ </p>
+
+ <p>
+
+ In order to fetch and update news items with this mechanism we need two things:
+ the URL to the RSS feed and the interval between the automatic updates. These are
+ also the two properties that we will allow the user to configure in the settings
+ view. The properties will be stored in the widget preferences store and updated
+ there whenever the user saves the settings. The settings will be read when the
+ widget starts.
+ </p>
+
+ <p>
+
+ When the news items are fetched we will display a notification popup dialog to
+ indicate that the loading is in progress. The main reason why this is important
+ is because the loading takes some time and if we don't react immediately to the
+ user's action then the user will feel like the widget is not responsive. However
+ we don't want to popup a progress dialog every time the widget loads news in the
+ background. That would be really annoying when the user is reading news! This
+ means that we have to know whether the update was triggered manually or if it
+ was scheduled. We'll use a flag to track this and popup the dialog only if the
+ update was commanded by the user.
+ </p>
+
+ <p>
+
+ The settings view will contain four controls: a selection control to select the
+ feed URL, another selection control to select the feed update frequency, a save
+ button and a cancel button.
+ </p>
+
+ <p>
+
+ The main view in turn will contain a variable amount of controls: one for each
+ news item. The control that we will use is a ContentPanel control, which allows
+ us to collapse and expand the content so that we can display a compact list of
+ news headlines yet allow the user to open up a particular piece of news that
+ is interesting and read the summay or go to the website where the full news
+ story can be found. The news item controls will have the news headline as the
+ caption in the control. Unlike for other controls, ContentPanel captions are
+ interactive and can be clicked. When clicked they will toggle the content area
+ of the panel. We will put the actual news story summary in this content area.
+ The news story summary will be a fragment of HTML that we will construct from
+ each news story. The HTML will also include a link to the website where the
+ full story is located. The HTML will be styled by CSS rules that we will write
+ to the RSSReader.css file.
+ </p>
+
+ <p>
+
+ Because we don't know how many news stories we will have at any given time, we
+ will add and remove ContentPanel controls to the main view dynamically whenever
+ there's some update in the RSS feed. But we're environmentally conscious so
+ we'll recycle the ContentPanels. There's no need to throw them away even if they
+ are not needed. So once we have created them we will put them in a pool so that
+ we can recycle them. Later on if we need more ContentPanels will look for them
+ in the pool first and only if there are no ready ContentPanel controls for us
+ will we create more controls (and place them in the pool). Strictly speaking such
+ recycling is not necessary but it doesn't complicate the code much and it's a good
+ skill to know.
+ </p>
+
+ <p>
+
+ Finally, as we move between the main view and settings view we will need to
+ change the right softkey so that it's "Exit" in the main view and "Cancel" in
+ the settings view.
+ </p>
+
+ </div>
+
+ </div>
+
+<div>
+<div class="familylinks">
+<div class="parentlink"><strong>Parent topic:</strong> <a href="WRTKit_RSS_Reader_Tutorial-GUID-678d197f-c7b0-4e5e-85e2-f8549c75bbe8.html">RSS Reader</a></div>
+</div>
+</div>
+
+</body>
+</html>
\ No newline at end of file