This is the third and final part of the series about Audero Feed Reader. In this article, you’ll learn how to create the configuration file and complete the project we started in a prior lesson.
1. Finishing the App
A Better Responsive Layout
In the first part of this series I wrote about the importance of the data-iconpos attribute for the links in the header and the footer. In this section, you’ll learn about why we use them. I’m using it, with a bit of JavaScript, to create a better responsive effect. I use it to hide the text of the links where it’s applied. The purpose of this is to save space, which is important, especially for smaller screens. But what if the screen is large enough, say larger than 480 pixels, to display the text? For this, we’ll listen for the pagebeforecreate event, and attach a handler, the updateIcons() method of the Application class, to react once it’s fired. As the names indicate, the event is triggered before the page and its widgets are initialized. Our handler, will first test if the page is larger than 480px and, if so, it’ll remove the data-iconpos attribute, so the link text will be shown.
The code that implements this method is the following:
updateIcons: function () {
var $buttons = $('a[data-icon], button[data-icon]');
var isMobileWidth = ($(window).width() <= 480);
isMobileWidth ? $buttons.attr('data-iconpos', 'notext') : $buttons.removeAttr('data-iconpos');
}2. Build Configuration
The Adobe PhoneGap Build service allows you to specify the metadata of your project with a configuration file called config.xml. It follows the W3C widget specification and must stay inside the app’s root, at the same level of index.html. The first line is the XML declaration and the root of the document is a <widget> tag that has several attributes available. The most important ones are id, the unique identifier of the application, and version, which specifies the version of the application. Inside the <widget> tag, you can write the metadata.
If you’ve followed the tutorial so far, you’ll recall that when we initialized the application using the PhoneGap CLI, it created a default configuration file. The generated configuration specifies too many settings for each platform compared to our needs. In fact, we’ll use several settings, but since this is a tutorial, we’ll focus on a few platforms. However, you’re absolutely free to expand to fit your individual needs.
In the configuration file, we have:
- Name (required): This is the app’s name. It doesn’t have to be unique.
- Description (required): Text specifying what your app is for. This is very important because it’ll appear as the description of your app in the marketplaces.
- Author (optional): The app’s author. It has two optional properties: href, a URL to the developer or company homepage, and email, the email address of the developer or the company. Unfortunately, you can only specify one author, so you cannot have details for multiple authors here.
- Icon (optional): This will be the icon that will display on the devices that install your app. If it is not specified then the Cordova logo will be used.
- Splash (optional): It sets the splash screen of the application, this is the image that’s showed while loading.
- Preference (optional): A set of preferences you want to apply to your app. It’s a closed tag and you can have zero or more
<preference>tags inside the file. It has two attributes and both are required:nameandvalue. There are several preferences you can define, but the most important one to use in my opinion is the Cordova version. - Access (optional): Provides your app with access to resources on other domains – in particular, it allows your app to load pages from external domains that can take over your entire webview. Keep in mind what I explained earlier in the section titled “The InAppBrowser Plugin”- that to open the external links in the Cordova WebView, you must add them to the app whitelist. For brevity, we’ll allow for any external resource using the
*special character. - Gap:plugin (optional): Specifies the features you want to use. For example, Android before installing any app, shows to the user the permissions it requires and if the user agrees, it continues.
If you’ve read carefully the list above and have used PhoneGap in the past, you probably noticed the introduction, in version 3.0.0, of a new setting called gap:plugin. The latter has replaced the feature setting but, apart from the name, the concept is exactly the same.
Now that I’ve noted the key points of the format, you can understand the source of the configuration file of our project. However, if you want to read more on this topic, take a look at the official documentation page. The complete file is below.
<?xml version="1.0" encoding="utf-8"?><widget id="com.audero.free.utility.auderofeedreader" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:gap="http://phonegap.com/ns/1.0"><name>Audero Feed Reader</name><description>
Audero Feed Reader is a very basic feed aggregator to keep in one place all the news and the articles you care about.</description><author email="a.derosa@gmail.com" href="http://www.audero.it">
Aurelio De Rosa</author><gap:plugin name="org.apache.cordova.core.network-information" /><gap:plugin name="org.apache.cordova.core.dialogs" /><gap:plugin name="org.apache.cordova.core.inappbrowser" /><preference name="permissions" value="none" /><preference name="phonegap-version" value="3.0.0" /><preference name="orientation" value="default" /><preference name="target-device" value="universal" /><preference name="fullscreen" value="true" /><preference name="webviewbounce" value="true" /><preference name="prerendered-icon" value="true" /><preference name="stay-in-webview" value="false" /><preference name="ios-statusbarstyle" value="black-opaque" /><preference name="detect-data-types" value="true" /><preference name="exit-on-suspend" value="false" /><preference name="show-splash-screen-spinner" value="true" /><preference name="auto-hide-splash-screen" value="true" /><preference name="disable-cursor" value="false" /><preference name="android-minSdkVersion" value="7" /><preference name="android-installLocation" value="auto" /><icon src="icon.png" /><icon gap:density="ldpi" gap:platform="android" src="res/icon/android/icon-36-ldpi.png" /><icon gap:density="mdpi" gap:platform="android" src="res/icon/android/icon-48-mdpi.png" /><icon gap:density="hdpi" gap:platform="android" src="res/icon/android/icon-72-hdpi.png" /><icon gap:density="xhdpi" gap:platform="android" src="res/icon/android/icon-96-xhdpi.png" /><gap:splash src="splash.png" /><gap:splash gap:density="ldpi" gap:platform="android" src="res/screen/android/screen-ldpi-portrait.png" /><gap:splash gap:density="mdpi" gap:platform="android" src="res/screen/android/screen-mdpi-portrait.png" /><gap:splash gap:density="hdpi" gap:platform="android" src="res/screen/android/screen-hdpi-portrait.png" /><access origin="*" /></widget>3. Enabling the Application to Run
At this point we’ve reached the end of this series. Its purpose has been to demonstrate how we can start the app safely with all the files we’ve built so far. Our handlers and methods can be safely executed once Cordova is fully loaded, ensuring that you can call the Cordova APIs. But wait…When is Cordova ready? I’m glad you asked! The framework provides an event called deviceready that you can listen to. Given that, in the index.html file (the entry point of the application), we’ll listen to the event and attach as a handler our initApplication() method of the Application class. It will be executed once the event is fired.
The code that implements this is shown below.
<script>
$(document)
.on('pagebeforecreate', Application.updateIcons)
.one('deviceready', Application.initApplication);</script>4. Building and Testing the Application
Our app is now complete. All that’s left to do is to build and test it on an emulator or a real device. To build the app you have two possibilities: your computer or the Adobe cloud service, called Adobe PhoneGap Build. Remember that if you want to use your computer, you must install the SDK for each platform you want to target. The PhoneGap CLI has a command to build the app (build), to test it (install), and to perform both tasks (run). So, let’s say that you want to build and test Audero Feed Reader on Android, you have to type the following command:
phonegap run android
Please note that if you have an Android device connected and properly configured to the computer, the application will run on it by default. Otherwise it’ll run on the SDK emulator.
In case you want to use Adobe PhoneGap Build to generate the installable files, you can use the CLI as well, just by using the remote command as shown below:
phonegap remote build android
Keep in mind that since the remote build environment doesn’t have an emulator, the install and run commands simply generate a QR code in the PhoneGap Build interface. In addition, to use the service you need to have an Adobe account. This means that (unfortunately) you cannot use the GitHub credentials.
Conclusion
As you’ve seen throughout this series, creating a Feed Reader can be very easy thanks to frameworks such as jQuery Mobile and Cordova, and to some APIs like the Google Feed API. I hope you enjoyed this tutorial and if you’d like to improve the project further, consider adding some features you feel I missed and use it on your own mobile devices.