Video Tutorial: How to Set up PhoneGap Build in Sencha Touch

13 min read

Originally published June 24, 2014

In this video tutorial we take a look at how to set up your application for PhoneGap Build. Although this specifically focuses on Sencha Touch, this is easily adaptable to any other HTML5 mobile framework (it's pretty simple!). Enjoy!

**UPDATE: **The way in which you should include PhoneGap Build in your Sencha Touch projects has changed. You should take a look at Building Your App Remotely with PhoneGap Build and Sencha Cmd for instructions on how to implement it.

Video Transcript

Hello everyone and welcome to another video tutorial. Before I get started with this one I just wanted to acknowledge some audio problems that the past videos seem to be having. The videos were playing fine for me when I listen to them but I got a few comments saying that the audio was very low. I checked it on another computer and you could barely here the audio so I’ve changed a few settings for this one and I’m also sitting a little bit closer to the microphone on my laptop so hopefully it works a little bit better this time. Let me know how it goes for you. Hopefully sometime in the future I will invest in getting a proper microphone but right now I’m just using my webcams inbuilt microphone so hopefully it’s alright.

In this tutorial I want to look at how to set up PhoneGap Build in your project. I’m going to focus specifically on a Sencha Touch project but you could probably use this advice for different UI frameworks as well. Before I get into the code side of things, first, you are going to have to go to the PhoneGap Build website:

http://build.phonegap.com

You’ll have to create an account here to start using it. So, we just click on register and you’ll see the options available. You can do the free plan which gives you one private app. You can create as many open source apps as you want but they have to be pulled from a public GitHub repository so anybody will be able to see your application. You also have the option of paying monthly, I forget how much it cost but you get 25 private applications that you can create with that package. So, just go ahead and sign up with the free account for now and then you can jump into the next stuff. Before I get into that, I just want to explain exactly what PhoneGap Build is.

PhoneGap Build is a cloud service which essentially makes implementing PhoneGap a lot easier, rather than having to maintain it on your own computer. The PhoneGap Build service takes care of all of the compilation for you. You can essentially combine PhoneGap Build with most UI frameworks. What it does essentially is give you access to more native functionalities of a device that typically web applications wouldn’t be able to access. But even if you’re not utilising the extra functionality that PhoneGap offers, you don’t have to add in any stuff at all to your project, but at the bare minimum it allows you to install your web app onto a device. It wraps the web app up into a native package (read more about that here) and then you can install that on an iOS device or an Android device, you can distribute it through app stores like you would any other natively built application. You can also achieve the same thing through using the Sencha Touch native packager, but I tend to find PhoneGap is a lot easier to use and it’s a bit more feature rich and quick to update.

Now I’m going to look at how to go about setting this up in your application, so once you’ve signed up you can jump into your Sencha Touch application or whatever application you’re planning to use PhoneGap with. First open up the index.html file – the application I’m using here by the way is just a sliding menu application I created in the last video tutorial, I’ll link to that as well if you want to check it out after this – to get PhoneGap installed first we’re going to have to reference it inside of our index.html file. I’m just going to include this script here:


<script type="text/javascript" src="phonegap.js"></script>

So basically I need to reference the phonegap.js file, and I think this confuses a lot of people because you don’t actually need this file in your project at all. A lot of people think, and it makes sense to think, that you would have to have a phonegap.js file stored in here somewhere. But essentially all of this is handled on the PhoneGap Build servers so all you need to do is reference it and you don’t need to worry about actually including that file in your project.

As well as that you’ll also have to add a config.xml file. So I’m just going to pull up an example to get us started – I’ll just create a blank file here, save that as config.xml in the root directory of our project for now – I’m just going to pull in the default config.xml that is in the documentation provided by PhoneGap:


<?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.phonegap.example"
      versionCode = "10"
      version     = "1.0.0" >

  <!-- versionCode is optional and Android only -->

  <name>PhoneGap Example</name>

  <description>
      An example for phonegap build docs.
  </description>

  <author href="https://build.phonegap.com" email="support@phonegap.com">
      Hardeep Shoker
  </author>

</widget>

Ok, so I’ve just pulled this in from the documentation. Basically what this config file does is tell PhoneGap what we want to do when we’re building the application. This is the most basic config file you could have, you can see here we’ve got the author which obviously we would want to change to our own name, a description of the application, a title, and stuff like the version code (you probably want to keep that at 1.0 for now). You’ll also want to change the id to something unique, it usually uses this reverse domain style so you might use something like:

com.yourname.yourproject

There’s a lot of different options we can put in here, it’s probably best to take a look through the documentation which I will also link. One thing you’re probably going to want to do is include some plugins. All of the functionality provided by PhoneGap needs to be included as a plugin now, even the sort of core things that it provides. So if I wanted to pull in some device information I could include this plugin here:


<gap:plugin name="org.apache.cordova.device" />

Which is the device plugin, and there is some other plugins we could include like an In App Browser for example:


<gap:plugin name="org.apache.cordova.inappbrowser" />

That will allow us to open up a browser within our application. Try to only include the plugins that you actually want to use in here obviously.

Besides the plugins, there’s also other options we can set such as the target platform, whether we want the icon to be pre-rendered, options around the splash screen, there’s tons of different options we can have for both the iOS and Android platforms.

Perhaps most importantly we can specify all of our icons and splash screens. I’m just going to copy and paste in some code from another config file I have here – from the example application that comes with my Sencha Touch eBook – just to show you what it looks like:


<icon src="icon.png" />

<icon src="resources/icon/android/icon-36-ldpi.png"   gap:platform="android"    gap:density="ldpi" />
<icon src="resources/icon/android/icon-48-mdpi.png"   gap:platform="android"    gap:density="mdpi" />
<icon src="resources/icon/android/icon-72-hdpi.png"   gap:platform="android"    gap:density="hdpi" />
<icon src="resources/icon/android/icon-96-xhdpi.png"  gap:platform="android"    gap:density="xhdpi" />
<icon src="resources/icon/ios/icon-57.png"            gap:platform="ios"        width="57" height="57" />
<icon src="resources/icon/ios/icon-72.png"            gap:platform="ios"        width="72" height="72" />
<icon src="resources/icon/ios/icon-57-2x.png"         gap:platform="ios"        width="114" height="114" />
<icon src="resources/icon/ios/icon-120.png"           gap:platform="ios"        width="120" height="120" />
<icon src="resources/icon/ios/icon-72-2x.png"         gap:platform="ios"        width="144" height="144" />

<gap:splash src="resources/splash/ios/screen-ipad-portrait.png" gap:platform="ios" width="768" height="1024" />
<gap:splash src="resources/splash/ios/screen-ipad-landscape.png" gap:platform="ios" width="1024" height="768" />
<gap:splash src="resources/splash/ios/Default-Landscape_at_2x.png" gap:platform="ios" width="2048" height="1496" />
<gap:splash src="resources/splash/ios/Default-Portrait_at_2x.png" gap:platform="ios" width="1536" height="2008" />

<gap:splash src="resources/splash/ios/Default.png" gap:platform="ios" width="320" height="480" />
<gap:splash src="resources/splash/ios/Default@2x.png" gap:platform="ios" width="640" height="960" />
<gap:splash src="resources/splash/ios/Default-568h@2x.png" gap:platform="ios" width="640" height="1136" />

<gap:splash src="resources/splash/android/screen-ldpi-portrait.png" gap:platform="android" gap:density="ldpi" />
<gap:splash src="resources/splash/android/screen-mdpi-portrait.png" gap:platform="android" gap:density="mdpi" />
<gap:splash src="resources/splash/android/screen-hdpi-portrait.png" gap:platform="android" gap:density="hdpi" />
<gap:splash src="resources/splash/android/screen-xhdpi-portrait.png" gap:platform="android" gap:density="xhdpi" />

You can see this is referencing all the different types of splash screens and icons that are needed for the different platforms. That’s probably too big of a topic to talk about right now, so I’ll link to another blog post I’ve done where I talk about this a little bit more in depth.

I’ll leave the config file there for now – that’s all we really need to do to include PhoneGap in our project. Put that link into the index.html file and include the config file as well. Now what I’m going to do is open up the command prompt and I want to build the application now that I’m ready to upload it to PhoneGap Build. Let’s change the directory into the project:

cd c:\xampp\htdocs\SlidingMenu

And run the following command:

sencha app build production

And this will start building that minified version of the application. Now what I want to do is go to where that was just built and include that config.xml file. After that we just want to package this up into a .zip file – everything from resources to index.html. We don’t need the deltas folder.

Now that we have that ready, we want to jump back into PhoneGap Build. So now I’m going to sign in under my account, I’ve just signed up with GitHub. I already have an application in here right now this is the Touch Friends application that comes with my Sencha Touch eBook. So this is obviously going to look a little different for you, but essentially there’s not too much that’s going to be different. You’ll have some button where you can upload a .zip file, which is what I’d do here. Once you submit that it’ll go through building your application, and then you’ll come to a screen like this. Right away, you’ll see something similar to this – you’ll have your iOS version and Android version. The Android version should work for you right away, and you should have an error for the iOS version. The problem with the iOS version is that you require a provisioning profile before you can actually install it on your device. You can create these on windows as well, and again it’s a pretty big topic – quite annoying to do – so I’ll link to another article I have on how to go about building a provisioning profile and a certificate to get this sorted. But once you have that you should just be able to upload it here and rebuild the application and it should work fine like it is for me here.

The problem with the Android version for me is that my key is locked, you set a password for the keys that you add so I just have to type in the password, click rebuild and it should be fine. But you can build Android applications through PhoneGap Build without any certificates – what will happen is it will just create a debug version to use. The title of the application would be ‘MyApp-debug.apk’. This will allow you to install the application on your device but it won’t allow you to submit it to the app store. It’s a nice and easy way to test it but there is a little bit of extra work you need to do before you go live with it.

I hope you enjoyed the video tutorial, hopefully it was clear enough. I’ll probably do some more indepth stuff with PhoneGap Build in the future but this is my first video on the topic so again starting out with the easy stuff. And hopefully the audio wasn’t too much of a problem, let me know if the audio is still too soft and I’ll continue messing with my settings until I get it right. Thanks for watching, see you next time.