Building a mobile RSS reader with Flash Builder "Burrito" and Packaging for Android

The following steps should take about 8-10 minutes to complete.

1. With a browser, navigate to http://rss.slashdot.org/Slashdot/slashdot. View the source of the RSS feed to inspect the complex raw source of the RSS format.

   Note: If this doesn't work for you in Internet Explorer, try another browser.

2. Copy the URL from the browser window.
3. In Flash Builder "Burrito", choose File > New > Flex Mobile Project and type RSSReader for the name. Click Next and then click Finish. Flash Builder will create and open two new files in the new project: RSSReader.mxml and RSSReaderHome.mxml.

   Note: This behavior may vary depending upon the build and Flash Builder configuration you are using.  If, for example, your RSSReader.mxml file is created with <components:MobileApplication> as the root element, you'll need to change it to <s:MobileApplication>. Similarly, any views created with <components:View> should be changed to <s:View>.

1. To begin setting up the data service, open the RSSReaderHome.MXML file and choose Data > Connect to XML.
2. In the Connect To Data/Service dialog box, ensure URL is selected as the XML Source, and then paste the Slashdot URL in the URL text box. Click Invoke.

1. After Flash Builder introspects the service, select item as the Node. You should see that Is Array? is checked and the default service and package names have been provided as shown in Figure 2.
2. Click Finish.
3. After Flash Builder creates the service, open the Data/Services view [Window > Show View > Data/Services] and locate the newly created service getData[] function. Right-click it and select Configure Return Type [see Figure 3].

1. In the Configure Return Type dialog box, ensure Auto–detect The Return Type From Sample Data is selected and click Next.
2. On the next screen, select Enter A Complete URL Including Parameters And Get It. Paste the Slashdot URL in the URL To Get box [see Figure 4] and click Next.

1. On the next screen, type Item as the name of the new data type and select item as the Root node [see Figure 5]. Note: If you are using another RSS feed, you will need to figure out which property is the root node.

1. Click Finish.
2. Back in the Data/Services view, right-click getData[] again, and this time click Generate Service Call.
3. In Source View, add a List component and with the following properties: top=”0”, left=”0”,right=”0”,bottom=”0”.
4. Alternatively, you can add the List component in Design View. Then, select it and scroll to the bottom of the Properties tab until you see the Constraints controls. Set them as shown in Figure 6.

Constraining the List control in this way ensures that the application has a consistent appearance when switching between landscape and portrait modes.

1. Inside the <list> element set the labelField value to "title". Then add

<s:AsynchListView list="{getDataResult.lastResult}" /> as shown below. 
 <s:List left="0" right="0" top="0" bottom="0" labelField="title">
    <s:AsyncListView list="{getDataResult.lastResult}" />
 </s:List>

Note: The list property of the AsyncListView instance, which holds the data to be displayed in the List, is set to the data returned from the service call.   Using lastResult will cause the list to expand to match the number of items returned.

1. Add a call to getData[] on the viewActivate event in the root element.

1. In Design View, change the Chrome [#666666] and Content Background [#336666] colors to match the Slashdot home page.
2. Test your application by running it!  Right-click the project in the Package Explorer and select Run > Run As > Mobile Application. When you first run it, you will be asked if you want to launch it in an emulator or on a remote device. Use the emulator for now.

In Figure 7, note the entity reference [&mdash;] that appears in the third element in the list. To get rid of this you'll have to write some code to handle entity references, which is explained in the next section.

In this section, you will learn how to:

• Set up an event handler for a CollectionChange event and pass the event in
• Use labelFunction to call a special function that accepts a custom data type [Item[]] and returns a String.
• Set up a regular expression variable
• Use the String replace[] method to replace an entity reference with another character

This section should take about 10 minutes to complete.

1. If it's not already open, open the RSSReaderHome.mxml file.
2. In Source View, set the List control's id to myList.
3. Position the cursor within the <s:AsynchListView> element. Add an event handler for the collectionChange event that invokes a function named fixEntityReferences[] when the list values change.
   

   <s:List id="myList" left="0" right="0" top="0" bottom="0"  
                  labelField="title">
      <s:AsyncListView list="{getDataResult.lastResult}"
         collectionChange="fixEntityReferences(event)" /> 
   </s:List>

1. Next, add the following code to the <fx:Script> tag to implement the event handler:

The event handler function accepts the event of type CollectionEvent. It adds a labelFunction to the list. Named replaceEntity[], this function accepts an object of type Item. [Item[] is the array that is returned from the getData[] service.]

The replaceEntity[] function sets up a regular expression variable [p1] that detects the entity reference &mdash;. After creating a String variable named thisString, it calls the replace[] method on the item.title, substituting a dash [-] for the entity reference &mdash;. Lastly, it returns the string thisString, which will be reflected as the new item label.

1. Run the program and you will see that any &mdash;entity references no longer exist [see Figure 8].

Note: The technique used in this section to remedy the entity reference problem is a quick hack, not a best practice. The best practice would be to handle this in the value objects.

In this section you will learn how to work with views and the ViewNavigator component, which manages the views in your application as the user navigates through it. Specifically, you will create a new view that shows the details for a single RSS item. This section should take around 20 minutes to complete.

1. To add a new view, right-click the Views package in the Package Explorer and select New > MXML Component. Type DetailsView as the Name, leave the other settings at their default values, and click Finish.
2. Back in RSSReaderHome.mxml, position the cursor just inside the end of the <s:List> element in Source View and start typing change. When Content Assist highlights the change event, select it and then select Generate Change Handler [see Figure 9]. This will set up your event handler.

The newly created change handler function will push a new view that shows a detailed view of the specific item that the user clicked in the list. In Flex mobile projects, views can be pushed and then popped [see Figure 10].

1. Update the list change event handler code as shown below.

The pushView[] method takes two parameters: the view you want to push and a data object to pass to the view. In this case, the RSSItem variable is the data that will be passed to the DetailsView view.

1. Run the application. When you click on an RSS item, the new [and currently empty] details view will be displayed.

In this section you will learn how to access the data object passed when the Details view is pushed by the Home view and display various attributes of the RSS item.

This section should take about 20 minutes to complete.

1. Open the DetailsView.mxml file in Source View.
2. Create an <fx:Script> block and add variables for the title, date, creator, link, and description of the selected RSS item.

1. Switch to Design View, and ensure the details view colors are the same as the home view colors. Use #336666 as the Content Background color and #666666 as the Chrome color to match the Slashdot.org colors.
2. Back in Source View, set up the Details view by adding the following MXML to the content area of the view [below the </fx:Declarations> tag].

In addition to several Label elements that display the RSS item details, this view includes a button that loads the full RSS item URL in a browser when clicked. This is done using click="navigateToURL[new URLRequest[rlink]]".

1. Switch to Design View. In portrait mode, the components fit nicely in the view [see Figure 11]. Change to landscape mode. The components adjust to a new layout.

Since raw RSS feeds often have HTML markup and entity references, the application will have to replace some characters in the RSS feed data. Architecturally, it would be better to handle these substitutions in the value objects package. However, for this application it will be done in the view, even though it is not a best practice.

1. Create a new function called getDetails[] and add the following code.

The keyword data is a variable reference to the data passed to this view.

The title, dc_date, dc_creator, link, and description attributes of the RSS Item object are used to set the variables. The calls to replace[] use the regular expressions to replace entity references in the title and the description, as well as to eliminate HTML markup in the description.

1. Add viewActivate="getDetails[]" to the root <s:View> element. This will invoke getDetails[] when the view is activated. While you're there, insert a space between "Details" and "View" in the title attribute.
2. Run your application. Click on an item to see the Details view [see Figure 12]. Click the button to launch the Slashdot story in a browser.

In this section you will learn a best practice for mobile development. This section should take around 10 minutes to complete.

Although you may not have noticed it as you used the application in the emulator, each time the home view is shown, a new call is made to the RSS service. This consumes CPU cycles [and battery charge] and also incurs unnecessary data bandwidth charges for the user. Needless to say, this is not the best way for the application to behave.

To get a better understanding of this architectural mistake, it helps to enable the network monitor.

1. In Flash Builder, choose Window > Show View > Other and then select Flash Builder > Network Monitor to open the Network Monitor view.
2. Enable the Network Monitor by clicking the Enable Monitor button [see Figure 13]. [It is disabled by default.]

1. Run your application again in the emulator and watch the network calls as you navigate between the Home view and the Details view. [To return to the Home view from the Details view in the emulator, choose Device > Back or press Control+B.]

As you can see, there is a service call each time the Home view is displayed. Luckily, this is easy to fix.

1. Open the RSSReaderHome.mxml MXML file.
2. In the root element, remove the call to getData[] on the viewActivate event [see Figure 14]. Set the destructionPolicy attribute to "none". While you're there, set the title attribute to "Slashdot RSS".

The destruction policy defines the policy that the view's navigator will use when this view is removed. If set to "auto", the ViewNavigator component will destroy the view when it isn't active. If set to "none", the view will be cached in memory. For items such as an RSS feed that do not update very often, it is best to allow the user to manually refresh the list or to update the list periodically.

You still need to call getData[] at the launch of the application. This can be done from the main application file.

1. Open RSSReader.mxml, the file for the main entry point into the application. This is located in the project's default package. In the Package Explorer it has a blue dot and green triangle beside it [see Figure 15].

1. Add applicationComplete="getRSS[]" to the root element of the application [<s:MobileApplication>]. After the application has been initialized, the applicationComplete event is dispatched and getRSS[] will be invoked.
   

   <s:MobileApplication xmlns:fx=http://ns.adobe.com/mxml/2009                          xmlns:s="library://ns.adobe.com/flex/spark" 
             firstView="views.RSSReaderHome"
             applicationComplete="getRSS()">

2. Now create the function that will make the initial service call to get the RSS items. After deleting the empty <fx:Declarations> element, add the following code:

Since the first view to be used will be views.RSSReaderHome, the code can reference it directly and make a call to any of its public functions. The call to Object[] converts the active view into an object, and then the getData[] function is called.

1. Back in the RSSReaderHome.mxml file, change the access modifier for the getData[] function from protected to public as shown below.

Run your application. Verify that getData[] still works, but that it is not getting called every time the Home view is displayed.

Now that you have removed the service call that was invoked each time the Home view was shown, it's a good idea to give the user a way to refresh the list of RSS items manually. In this section you will learn about:

• Action content
• Making calls from the application to functions contained in views
• How to embed icons within buttons

There are basically four main areas for a Flex mobile application built for the Android OS: navigation content, title content, action content, and the view [see Figure 16]. Action content is usually on the right-hand side, and that is where you'll position the icon that will be used to refresh the list.

1. To create a refresh icon, you will need an icon approximately 48 x 48 pixels with a transparent background in PNG format. Locate the refresh48x48.png and info48x48.png files in the icons package of the starter project for this tutorial.
2. Right-click the src folder of your application and select New > Package. Type icons as the package name and click Finish. This will set up a folder for your icon images.
3. Copy the refresh48x48.png and info48x48.png icon files into the new package.
4. Open RSSReaderHome.mxml and insert the following code, which adds an action content area to the Home view with a button that embeds the refresh icon image.

1. Run the application to verify that the button is displayed [see Figure 17].

1. Switch back to Source View and add the following function:

1. With the Network Monitor on, run the application. Each time you click the refresh button it should invoke another service call.

The application no longer automatically refreshes. Instead, the addition of a user controlled Refresh button places the power into your users' hands, which is a best practice. They know their data plan and battery life, and it is a good idea to enable them to control this functionality.

Now that the architecture is solid, it is time to add another view to allow users to see information about the application. The Info view will be relatively simple to add, and it will give users information about getting the source code for the application [pay it forward!].

This section will take about eight minutes to complete.

1. If you have not already done so, copy info48x48.PNG from the starter project to the icons package of your project.
2. Since this icon should be visible from all views in the application, it can be added to the entry point into the application, in this case the RSSReader.mxml file. Add the following code to set up the button and a click event handler named showInfoView[] [yet to be written].

1. To create the new view, right-click the views package in the Package Explorer and select New > MXML Component.
2. In the New MXML Component dialog box, type views as the Package and InfoView as the Name. Make sure that the new component is based on spark.components.view [see Figure 18] and click Finish.

1. Open InfoView.mxml in Source View and change the title attribute in the <s:View> element to "About RSS Reader". Then add the following code.

Note: The text and navigateToURL link can be changed for each project.

1. Open the Home view file [RSSReaderHome.mxml] and add a function named showInfo[] in the <fx:Script> block that will push this view.

1. Repeat the previous step for DetailsView.mxml. Note that InfoView.mxml does not need a showInfo[] instance because the user will not be allowed to click the Info button from that view.
2. Open the RSSReader.mxml file [the entry point into the application] and add the showInfoView[] function, which calls the showInfo[] function from the active view.

If you run your application now, you'll notice two problems. First, there is no Info button in the Home view, where one is needed. Second, there is an Info button in the Info view, where it is not needed.

The button is missing from the Home view because that view already contains an <s:actionContent> element for the Refresh button. The view's <s:actionContent> element overrides the one in RSSReader.mxml.

1. To add the Info button to the Home view, open RSSReaderHome.mxml and add <s:Button icon="@Embed[source='icons/info48x48.png']" click="showInfo[]" /> to the <s:actionContent> element.

This adds a button that calls the view's instance of showInfo[] when clicked.

1. To remove the Info button from the Info view, open InfoView.mxml and add an empty <s:actionContent> element.

Note: There are other ways to implement the Info button. For example, instead of including it in the main application file, it could be implemented in each view that needed it. In general, however, if a button is to be made available to every view [or almost every view] then it makes sense to implement it as done here. The approach taken may vary from project to project.

You're almost done building this Flex mobile application. One final thought is that on some devices it might take the application a while to load. A splash screen will let the user know something is happening as the application starts up.

In this section you will learn:

• What a splash screen does and why it is a good idea
• How to add a splash screen

Mobile applications must always strive for efficient use of the CPU and battery. When an application takes time to load, it can give the user the impression that the entire application is sluggish. One way to show the user that the application is reacting quickly to user actions is via the view [in this context, view refers to the MVC pattern concept of view]. Adding a splash screen is fortunately quite easy. The splash screen is shown while the main parts of the application load and disappears as the main application has finished initializing.

This section will take less than five minutes to complete.

1. Create a new package under the src folder of your project and name it splash.
2. Copy the splashscreen.png file from the starter project into the splash package [see Figure 19].

Keep in mind that a user might open your application in landscape mode. To account for this, you can either restrict the application to open only in portrait mode, or set the width and height of your splash screen image so it will not matter; for example, use 400 x 400 pixels [see Figure 20].

1. Open RSSReader.mxml and add splashScreenImage="@Embed['splash/splashscreen.png']" to the root <s:MobileApplication> element of the application, as shown below.

1. Run your application. The splash screen image will appear momentarily while the application is loading.

Now that you have a fully functioning application, there are a few remaining tasks to complete before you can publish your application to the Android Market. If this is your first time publishing an application, visit http://market.android.com/publish/signup to set up an account.

After you register, you will find list of requirements for publishing your application. Complying with these requirements will help your application look more professional and will also allow people to find it easier. Among the most important requirements are the icons, which are required in multiple sizes from 512 x 512 pixels to 16 x 16 pixels. It is best to develop the largest size first, and then scale down the rest.

Once you have developed a base icon, save it in the following sizes under the /src/icons/ folder in your project:

• icon32x32.png
• icon36x36.png
• icon48x48.png
• icon72x72.png
• icon128x128.png

Ensure you keep the 512 x 512 pixel PNG original as you will need it for the Android Market. Example versions of these icons can be found in the starter project.

Additionally, you will need a PKCS12 digital certificate that is valid until after October 22, 2033. This may surprise you, but it's not hard to create one. For details on creating your own digital certificate, see Generating a PKCS12 certificate for Android Market.

Follow these steps to place your application in the Android Market.

1. Locate the application descriptor file, which you will find in the project's src folder [see Figure 21]. For this project, it is named RSSReader-app.xml. This XML file specifies parameters for identifying, installing, and launching AIR applications. You will need to make a few modifications to this file.

1. Do not open the file by double-clicking, that would open it with the XML editor. Instead, right-click the file and select Open With > Text Editor.
2. Provide a valid name and version for your application. The name can be changed by editing the <name> element near line 25.
3. Type some descriptive text that identifies your application. For example, you might type Slashdot RSS Monitor or something similar [see Figure 22]. Note: The exact line number and comment text may differ from those shown.

Next set the version number for your application. If you decide you are a great coder and there is no chance of any bugs, you might choose version 1.0. Set this value in the <versionNumber> element near line 30 [see Figure 23].

1. Next, you'll want to define where the main application can locate the proper PNG application icons. Near line 109, find the <image16x16> element, which begins a set of six similar elements [see Figure 24].

1. Insert the name of the appropriate icon file in each element [see Figure 25].

There are many other items that may be set in the application descriptor file including descriptions, copyright, and more. For more information, refer to the Adobe AIR documentation.

1. Save your changes.
2. If you have not already done so, copy the necessary icon PNG files from the starter project into your project's src/icons folder.
3. Right-click the project in the Package Explorer and select Export.
4. In the Export dialog box, select Flash Builder > Release Build [see Figure 26].

1. Click Next.
2. On the next screen, ensure you're exporting the correct project and leave the other options at their default values [see Figure 27]. Click Next.

1. On the next screen, specify the location of your digital certificate and type the password. Make sure that the certificate you created complies with the requirements of the Android Market. Again, for instructions on creating such a certificate, see Generating a PKCS12 certificate for Android Market.
2. Click Finish.

   That's it! When you see the success confirmation [see Figure 28] you will have a new *.apk file [which is the native installer package for Google Android devices].