Build an AudioPlayer with PhoneGap: Application Tuning

This is the third and final part of the series about Audero Audio Player. In this article, I will go over the remaining files so that you can finish the project and play around with it.

Series Overview

• Application Setup
• Application Logic
• Application Tuning

Style Tuning

jQuery Mobile does a lot of the work for you by enhancing pages’ elements for devices with smaller screens. However, there are some that I don’t care for, and we’ll adjust these in our style.css file. This is also used to style the player’s markup.

By default, even if you don’t have buttons within the header or the footer of a page, the framework still reserves some space on both side of the elements and truncates long titles. This behavior is applied to other elements as well. We can change it simply by applying the rule white-space: normal !important; to our targeted elements as .ui-title.

The source of the stylesheet is shown here:

.ui-header .ui-title,
.ui-footer .ui-title,
.ui-btn-inner *
{
  white-space: normal !important;
}
.photo
{
  text-align: center;
}
#player-play,
#player-stop
{
  display: inline-block;
  width: 48px;
  height: 48px;
}
#player-play
{
  background-image: url('../images/play.png');
}
#player-stop
{
  background-image: url('../images/stop.png');
}
#time-slider
{
  display: none;
}
div.ui-slider-track
{
  margin: 0;
  width: 100%;
}

jQuery Mobile Custom Configuration

jQuery Mobile has a default configuration that should be good enough for most projects with simple requirements. However, there will be times when you will want to modify or take control of some default behavior. You can achieve this by writing a configuration file. The file jquery.mobile.config.js is exactly where we’ll have the configuration. Please note that you must include the configuration file before the jQuery Mobile files. When jQuery Mobile starts, it fires the mobileinit event, which is the one you must bind to override the default settings.

We’ll make the change by assigning values to the properties of the $.mobile object. I won’t change a lot of properties. I’ll instead change the option to have the text shown on the page loader widget, and the theme.

The full source of the file is listed below:

$(document).on(
   'mobileinit',
   function()
   {
      // Page Loader Widget
      $.mobile.loader.prototype.options.text = 'Loading...';
      $.mobile.loader.prototype.options.textVisible = true;
      // Theme
      $.mobile.page.prototype.options.theme  = 'a';
      $.mobile.page.prototype.options.headerTheme = 'a';
      $.mobile.page.prototype.options.contentTheme = 'a';
      $.mobile.page.prototype.options.footerTheme = 'a';
      $.mobile.page.prototype.options.backBtnTheme = 'a';
   }
);

Build Configuration

The Adobe PhoneGap Build service gives you the ability to specify the metadata of an application, like author and description, by using a configuration file. This file is called config.xml. Explaining the format in depth is outside the scope of this series, but I’ll give you a brief overview. If you want to read more on this topic, take a look at the official documentation page.

The config.xml file follows the W3C widget specification and must stay inside the app’s root, at the same level of the index.html file. Its first line is the XML declaration, and the root of the document is a <widget> tag that has several possible attributes. The most important ones are id (the unique identifier for your project), and version (which specifies the version of the application). Inside the <widget> tag, you can write the metadata of your application. In our file we’ll use a lot of them, but the most important are the following:

• name (required): The name of the application. It doesn’t have to be unique.
• description (required): The description of the application. It’s particularly important because it will be shown in the app’s marketplace listing.
• icon (optional): The icon to display on the devices that will install your app. If you do not specify it, the Cordova logo will be used.
• splash (optional): This tag sets the splash screen of the application, which is the image shown during loading.
• feature (optional): Specifies the features you want to use. For example, Android, before installing any app, shows the user the permissions it requires and, if the user agrees, it goes on.
• 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: name and value. There are a lot of preferences that you can define, but the most important one in my opinion is specifying the Cordova version used.

The <access> tag is also very important because, to cite the documentation, it 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. Recalling what we discussed in the section Managing External Links from the previous post, to open the external links in the Cordova WebView, we must add them to the app whitelist. Since our application won’t retrieve links from external and unsafe sources, we can shorten the process to allow for any external resource using the * special character. For example:

<access origin="*" />

I’ve pointed out the key points of the format, and now you can understand the source of the configuration file. The complete file is below:

<?xml version="1.0" encoding="UTF-8"?><widget xmlns     = "http://www.w3.org/ns/widgets"
        xmlns:gap = "http://phonegap.com/ns/1.0"
        id        = "com.audero.free.player.auderoaudioplayer"
        version   = "1.0.0"><name>Audero Audio Player</name><description>Audero Audio Player is a basic audio player that collects the audio files and then allows the user to listen to them. This app also enables you to update the list at any time to include other files that may have been downloaded after running the operation for the first time. You can also remove any unwanted audio from the list by clicking an icon on the right side of the song's name. The sound list is ordered alphabetically with letter dividers to organize and group the list items, and has a search box to filter the files.</description><author href="http://www.audero.it" email="aurelioderosa@gmail.com">Aurelio De Rosa</author><feature name="http://api.phonegap.com/1.0/network"/><feature name="http://api.phonegap.com/1.0/media"/><feature name="http://api.phonegap.com/1.0/file"/><feature name="http://api.phonegap.com/1.0/notification"/><preference name="phonegap-version" value="2.3.0" /><preference name="target-device" value="universal" /><access origin="*" /><!-- Icons --><icon src="icon.png" width="64" height="64" gap:role="default" /><icon src="images/icon-72x72.png" width="72" height="72" gap:platform="android" gap:density="hdpi" /><icon src="images/icon-96x96.png" width="96" height="96" gap:platform="android" gap:density="xhdpi" /><icon src="images/icon-72x72.png" width="72" height="72" gap:platform="ios" /><!-- Splash Screens --><gap:splash src="splash.png" /><gap:splash src="images/splash-160x220.png" gap:platform="android" gap:density="ldpi" /><gap:splash src="splash.png" gap:platform="android" gap:density="mdpi" /><gap:splash src="images/splash-450x650.png" gap:platform="android" gap:density="hdpi" /></widget>

Running the Application

In the last section, all the business logic, HTML and CSS files for the application were built, so now it’s time to set the entry functions for the application and play. The targeted function will be the initApplication() method of the Application class. It will run once Cordova is fully loaded, ensuring that you can safely call the Cordova APIs. To do this,  we’ll set initApplication() as a callback function for the deviceready event by adding the following code to the index.html file. You can see this by looking at the next snippet:

<script>
  $(document).on('pagebeforecreate orientationchange', Application.updateIcons);
  $(document).one('deviceready', Application.initApplication);</script>

Possible Improvements

You are now at the end of the project. That being said, every project has room for improvements and new feature, so before I conclude the series, I would like to suggest some of these to you.

The first feature that you can add is the internationalization (i18n) of the application. Our player doesn’t have much text, so translating it into other languages should be very easy. To translate the application, you can use the Globalization API, an API added to the core starting from version 2.2.0. In addition, a specific jQuery library like jquery-i18n-properties or jQuery-i18n would surely be useful for this feature.

Other minor suggestions are:

• Allow the user to create playlist.
• Create a “Play All” button to play all the songs in the list.
• Create a ratings system for the audio so that the user can filter and order songs by rating.
• Add a “Repeat” button so that the user can continue listening to the current song.

These suggestions are just some of the potential improvements you can make to the Audero Audio Player. Using the information from this tutorial and your own skills, you can do much, much more.

Conclusion

As you’ve seen throughout this series, you can build powerful and useful apps using web technologies and popular frameworks. Now it’s your turn to play around with this project. Try starting your own project to test what you learned in this series!