Converting PhoneGap/Cordova Projects to AppBuilder

Inevitably, when explaining AppBuilder to other developers, the question arises:

If I have an existing PhoneGap/Cordova project, can I convert it to use with AppBuilder?

The short answer is....yes! The long answer is "yes, after copying your original project's assets to the correct location(s) in a fresh AppBuilder repository." This process isn't hard - but it does require a few steps to get everything moved over.

So - let's see how this can be done.

Step 1 - Create a New "Blank" AppBuilder Project

Let's assume you're starting from scratch. When you log into the Telerik Platform, on the "Workspaces" landing page, click "Create Workspace":

Enter a workspace name & description:

Now that we've got a workspace ready, let's create our AppBuilder project. In the AppBuilder section, click "Create AppBuilder Project":

We want to create a minimal project, so the best option is to use the "Blank" project template (be sure to scroll down and give your AppBuilder project a name, too):

Great - now we're ready for step 2.

Step 2 - Connect Your Blank AppBuilder Project to a Git Repository

AppBuilder supports connecting to external git repositories - for example, Github or BitBucket (yes you can connect to private repositories!). You can even connect to your own hosted git, as long as the host is accessible over the internet.

In AppBuilder, use the "Version Control" menu to select "Configure Remote Repository":

Enter the URL to your git repository and click "Connect", then click "Done" at the bottom right:

You will likely be prompted for your credentials to the git provider (I used Github, in this case). Once authenticated, AppBuilder will push the current project to the repo. A glance at Github will show that your project's current state has been pushed:

Step 3 - Remove the "Default Boilerplate" From the Project

The "Blank" Project template includes a few basic assets: an index.html, as well as js, css and img folders. We're going to remove all of them by right-clicking and choosing "Delete". Our Project Navigator will look like this once we've removed those assets:

Step 4 - Push Your Changes to the Connected Git Repo

Now that we've removed the default boilerplate, we just need to push our changes to the remote git repository we connected in step 2. First we need to commit our changes. On the "Version Control" menu, choose "Commit". Enter a description of the changes and then click "Commit":

To leave the "Commit" UI, click the "breadcrumb" next to "Version Control" at the top:

Finally, click the "Version Control" menu and choose "Push":

Step 5 - Clone the AppBuilder Repo to Your Local Machine

Using the Git tool of your choice (for me - it's a terminal), clone the AppBuilder repository to your local machine:

Step 6 - Copy the Assets From Your PhoneGap/Cordova Project

When you work with AppBuilder, the files/content you see in the Project Navigator correspond (mostly) with what normally goes in the www/ folder in a Cordova/PhoneGap project. Here's what I see in my www/ folder in my PhoneGap project:

In this case, we need to copy the js, css and kendo folders as well as the index.html file to our AppBuilder repository. (The specific files and folders you need to copy will depend on your project.) A look at the top-level directory structure of the AppBuilder repository will show you that what you see in the Project Navigator in AppBuilder appears in the PG-to-AB folder at the root of the repo:

└── PG-to-AB
    ├── App_Resources
    │   ├── Android
    │   │   ├── drawable-hdpi
    │   │   │   └── icon.png
    │   │   ├── drawable-ldpi
    │   │   │   └── icon.png
    │   │   ├── drawable-mdpi
    │   │   │   └── icon.png
    │   │   └── drawable-nodpi
    │   │       └── splashscreen.9.png
    │   └── iOS
    │       ├── Default-568h@2x.png
    │       ├── Default-Landscape.png
    │       ├── Default-Landscape@2x.png
    │       ├── Default-Portrait.png
    │       ├── Default-Portrait@2x.png
    │       ├── Default.png
    │       ├── Default@2x.png
    │       ├── Icon-Small-50.png
    │       ├── Icon-Small-50@2x.png
    │       ├── Icon-Small.png
    │       ├── Icon-Small@2x.png
    │       ├── icon-40.png
    │       ├── icon-40@2x.png
    │       ├── icon-60.png
    │       ├── icon-60@2x.png
    │       ├── icon-72.png
    │       ├── icon-72@2x.png
    │       ├── icon-76.png
    │       ├── icon-76@2x.png
    │       ├── icon.png
    │       └── icon@2x.png
    ├── PG-to-AB.proj
    ├── cordova.android.js
    └── cordova.ios.js

Use your command prompt or file explorer to copy the web assets (your CSS, JavaScript, HTML and anything else used by those files) to the project directory (PG-to-AB, in my case) at the root of your AppBuilder repository.

NOTE: My PhoneGap project is using custom icons and splash screens for the app. Those images fall under the res directory you saw in the earlier screenshot of what's in my www/ directory. I don't need to copy those to the AppBuilder project, since AppBuilder provides a UI to help me upload custom icons. We'll get to that step in a minute.

Step 7 - Commit, Push, then Pull

Use your favorite Git client to commit your changes to the cloned AppBuilder repo and push them up to the remote repository. Then, in AppBuilder, choose "Pull" from the "Version Control" menu. Now the files you copied from your PhoneGap/Cordova project's www/ directory will appear in AppBuilder's Project Navigator:

Step 8 - Make Any Necessary Edits

Changing the phonegap.js Reference to cordova.js

Now you can tweak the content of any of your newly-copied files to work with AppBuilder. For example, my index.html references phonegap.js, this needs to be changed to cordova.js (since AppBuilder projects point to cordova.js):

Transferring config.xml Data

My PhoneGap project also had custom configuration data in its config.xml - which I need to transfer over. For example, I added an access element specifying a remote endpoint the app should be allowed to send requests to: <access origin="http://facts.azurewebsites.net" />. My app should work on both iOS and Android, so I need to tell AppBuilder to add this allowed origin to the builds for both platforms.

Editing Android's config.xml in AppBuilder

In AppBuilder, we need to right-click the project, choose "Edit Configuration" and then select "Android Config.xml":

This will open up a config.xml which will be used for the Android build in AppBuilder. Near the top you'll see the default access elements:

<access origin="http://127.0.0.1*"/> <!-- allow local pages -->
<access origin="*"/>

Let's replace the wildcard origin with our app-specific origin:

<access origin="http://127.0.0.1*"/> <!-- allow local pages -->
<access origin="http://facts.azurewebsites.net" />

After we've transferred any additional configuration settings, we need to save and close our Android config.xml.

Editing iOS's config.xml in AppBuilder

Now let's do the same thing for the iOS configuration. Right-click the project, choose "Edit Configuration" and select "iOS Config.xml":

Towards the bottom of our iOS-specific config.xml, we'll see the default access element: <access origin="*" />. We can change that to our app-specific origin: <access origin="http://facts.azurewebsites.net" />.

NOTE: One other setting that might be important to transfer would be the content element. Both AppBuilder and PhoneGap/Cordova apps default to <content src="index.html" />. However, if your main page is something other than index.html, be sure to change this value as well.

Step 9 - Uploading Custom Images for Icon/Splash Screen

Not that Chuck Norris needs custom icons, but if he had them, they'd be this awesome. So let's transfer the custom images my PhoneGap project used for icons and the splash screen to our AppBuilder project.

Applying Custom Icons for Android

Right-click the Project in the Project Navigator and select "Properties". Click the "Android" tab on the left:

On the right, you'll see something similar to this:

Click on any of the icons to upload a replacement. We can browse to the res directory to grab the Android images from my original PhoneGap project. Once we've uploaded our custom icons and splash, the screen will look similar to this:

Applying Custom Icons for iOS

Since we have our project Properties window open, we can click on the "icons" tab, under "iOS" on the left:

Our custom icon options for iOS look like this:

We can use the images in the PhoneGap app's res directory. After customizing, we should see something similar to this (you get the idea):

To change the splash screen for iOS, click on the "Splash Screens" tab below "iOS" on the left. The process of uploading custom splash screens is the same as the others. Once we've uploaded custom screens, we'll see something like this:

Step 10 - Run Your App!

I could run this in AppBuilder's browser-based simulator, but we'd run into CORS restrictions, since the app needs to talk to our Azure-based endpoints. No problem - we could use the AppBuilder Windows Client (which won't run into cross-origin restrictions), or we could deploy it to a device. Let's deploy it to an Android device.

On the "Run" menu, choose "Build":

Next, click "Android", then "Next":

Once the build is complete, we get a QR code which we can scan from an Android device, resulting in the .apk (Android installer) file being downloaded for us to install. Here's a screen capture of this in action:

Success!

Where To Go From Here

I hope my own journey converting a PhoneGap project to AppBuilder helps you in yours! A more advanced topic (which we don't have space to go into here) would be if your PhoneGap/Cordova project makes use of custom plugins. As long as your plugin(s) follow the plugman spec, they will work with AppBuilder. Be sure to read How to Make Your Apache Cordova Plugins Plugman-Compatible to learn more.