Adding Icons and Splash Screens To Your PhoneGap / Icenium Projects

Adding icons and splash screens to a PhoneGap/Cordova project has always been a bit tricky for developers. Each platform has its own file formats, image dimensions, and conventions - such as how the files are named.

In this article I'll attempt to demystify how to create and add images to your projects. We'll look both at how to add images to PhoneGap applications created through its CLI, as well as how to add images to Icenium projects.

Let's get started.

Icons and Splash Screens

There are two types of image assets associated with new PhoneGap projects: icons and splash screens.

After creating a new PhoneGap project, a default set of each are placed in the project's www/res/icon and www/res/screen directories respectively. Within these, there is an additional directory for each platform the project supports. The image below shows the directory structure for a newly created PhoneGap project.

Despite being in sister directories, icons and splash screens use completely separate sets of images; therefore we'll tackle each individually - starting with icons.

Adding Icons

Here's what we see if we expand our new project's www/res/icon/android and www/res/icon/ios directories.

As you can see, each platform has its own naming conventions for the icons it expects.

Android Icons

Android expects four images named icon-36-ldpi.png, icon-48-mdpi.png, icon-72-hdpi.png, and icon-96-xhdpi.png. The number in the file name refers to the expected dimensions of the image. For instance, the first image should be 36 pixels by 36 pixels. The second part of the file name is just an abbreviation for the different device resolutions. ldpi = low dpi (dots per inch), mdpi = medium dpi, hdpi = high dpi, and xhdpi = extra-high dpi.

iOS Icons

iOS has two different types of icons: 57x57 icons for iPods and iPhones, and 72x72 icons for iPads. Each type has a 2x version for retina screens. These images are expected to be twice the dimensions - e.g. 114x114 and 144x144.

Note: To complicate things further, these icon sizes are actually now out of date as iOS7 now requires 60x60 and 76x76 images (and their 2x equivalents). We'll get to dealing with that momentarily.

Creating Icons

So how do you actually create these images? If you're a designer - or your company has a designer - you may want to take advantage of each pixel in these images to create the perfect visual experience for users on all devices.

If that's you, great! If you're like most people and just want functioning icons, create a big square image; then use your image editor of choice to resize it into the various dimensions needed for each of these icons - just make sure that you use the appropriate naming conventions on the outputted images.

That covers how to add icons to PhoneGap; let's see how Icenium makes this process easier.

Adding Icons in Icenium

To demonstrate adding icons to an Icenium project, I'm going to be using a project I recently built to create animated gifs from a device's camera: GifThyself. You can clone the project in Icenium's in-browser editor if you'd like to follow along.

Within an Icenium project, if you open the project's properties from the Project Navigator, you'll see a number of configuration settings. Among these settings is a place to upload icon images for both iOS and Android. The image below shows the properties view with the iOS images loaded.

As you can see, Icenium gives you a lot of icons to configure - including separate icon sets for iOS <= 6 and iOS7. Icenium takes care of naming the images correctly and packing them into the app when it is built.

There's one other cool feature that is less obvious: if the image you upload is not the appropriate dimensions, Icenium will automatically resize it for you. This means if you're like me, and have design skills that match the average five year old with a box of crayons, you can take the same square image and upload it into each slot.

In my case I used my "amazing" design skills to create this beautiful icon.

I then uploaded this image for every iOS and Android icon option in Icenium. When I build my iOS project my custom icon appears on my home screen.

Icenium tries to give you the best of both worlds. Designers can create a highly customized suite of images without having to worry about naming conventions. Developers can upload a single image and move onto other things.

Now that we've looked at icons, let's look at the other type of image we need for a PhoneGap/Icenium project: splash screens.

Note: While these images show the Icenium in-browser client, the same functionality is also available in the Icenium Windows client.

Splash Screens

While icons determine how your app look on a user's home screen, splash screen images determine what the user sees while your app loads.

Like icons, both PhoneGap and Icenium supply default images to use as the app's splash screen. PhoneGap's default images are in the www/res/screen/android and www/res/screen/ios directories and are shown below.

As you can see, we again have platform differences and crazy naming conventions. A couple of notes on these files names:

• Both platforms use different image sets for portrait and landscape.
• As it did with icons, Android uses l/m/h/xh dpi to designate low/medium/high and extra high resolutions.
• As it did with icons, iOS includes 2x versions of each image, but this time it uses "ipad" and "iphone" in the file names. The "568h" image is specifically for the iPhone5 - which has a slightly taller screen than earlier models.

To help simplify this, here are the required resolutions of each of these images:

Unfortunately, there are a crazy number of combinations of images you need to create to cover your bases. And unlike icons - where all images were squares - here we cannot just take a single image and output it in multiple sizes. Therefore you unfortunately need to create an image for all of these resolutions.

Let's see what Icenium can do to help with this.

Note: There is at least one free tool that can help you generate these splash screen images. If you have a basic splash screen it might be able to help you out. In my experience, because the dimensions of the images are so different, using a generator like this produces a few usable images and a few where the positioning is off.

Adding Splash Screen Images in Icenium

In Icenium there is a specific menu item to upload iOS splash screens in your project's properties view. This is shown in the image below.

Like new PhoneGap projects, Icenium also provides a starting set of splash screens for new projects. As it did with icons, Icenium displays the dimensions of the various images and gives you an easy means of uploading new ones - without having to worry about getting the file names correct.

Icenium will also resize uploaded images to match the required dimensions. While this feature was great for icons, here, since the dimensions of these images are so different, you almost certainly don't want to rely on this behavior as it will distort the image.

Next, let's switch to the Android splash screen images; they're configurable in the main Android properties screen, shown below.

As you can see, unlike our new PhoneGap project, there is only one image, and it's... a 9 patch? What in the world is that?

Nine-Patch Images

Android's documentation defines a nine-patch image as: "a stretchable bitmap image, which Android will automatically resize to accommodate the contents of the View in which you have placed it as the background". Personally, I've found Android's official documentation on nine-patch images to be confusing. If you're looking to learn more about how nine-patch images actually work I would recommend http://adilsoomro.blogspot.com/2012/11/android-how-to-use-9-patch-png.html.

Essentially, Android breaks an images into nine chunks so it can intelligently resize the image to adapt to multiple screen sizes and resolutions. There are several online tools to help you create nine-patch images:

• draw9patch (included in Android SDK)
• Better 9 Patch Tool
• Simple Nine-patch Generator

The Simple Nine-patch Generator is maintained by Google and I find it the easiest to use. Upload your splash screen source graphic (a .png); edit what regions are "stretchable"; then click the "DOWNLOAD .ZIP" to download the nine-patch images.

The downloaded archive's contents are shown below.

The .9.png extensions represents an Android nine-patch image file. Icenium currently only supports uploading a single nine-patch image file, therefore upload the highest resolution version: drawable-xxhdpi/splash.9.png.

GifThyself's Splash Screens

In my case I used my awe-inspiring design skills to create this work of art.

I then used an image editor to output this image in the various required dimensions - keeping the main text centered and sized appropriately. I uploaded the images into Icenium and used Google's nine-patch generator to create the appropriate nine-patch files.

In the end, here's how my splash screen looks on an iPhone 5 running iOS7.

And here's how it looks on a Nexus 7 running Android 4.4.

Wrapping Up

Hopefully this article helped you figure out how to add icons and splash screens to your PhoneGap and Icenium projects. The GifThyself project I used in this article is available on GitHub. You can view the raw image files in its App_Resources directory.

Have any other questions about icons and splash screens? Let us know in the comments.

Additional Resources

• Cordova docs on icons and splash screens
• Icenium docs on icons and splash screens

About the Author
TJ VanToll is a web developer, speaker, and writer living in Lansing, MI and working as a developer advocate for Icenium. He is an open source advocate that is on the jQuery UI team and publishes his blog open source. When not on the internet, TJ is generally found helping his significant other chase their twin sons in circles. TJ is on Twitter as @tjvantoll and tjvantoll on Github.