October 26, 2016
Hot Topics:

Apache Cordova: Using Merges for Multiple Platforms

By Raymond K. Camden

This article is excerpted from the book Apache Cordova in Action

While you can use one code base to create applications for all the platforms Cordova supports, you typically will want to create an experience that is tailored to a particular platform. For example, it is a common Android UI design to have tabs on top of the app, while on iOS tabs will be on the bottom. Given that you have one www folder within a Cordova project, how do you handle that?

One way would be to generate a build for one platform, edit the www files, and then generate a build for the other platform. That's simple, but error prone. Another way would be to use the Device plugin. The Device plugin gives you access to information about the device on which your application is running. That works too but it could be complex to use JavaScript to assign CSS based on different factors.

A much easier solution is to use the merges folder. This folder does not exist by default. To test it, simply create a new folder called merges at the root of your project (figure 1).

Figure 1: A project with the merges folder

Inside of this folder, you can create a new directory for each platform you want to customize. For testing purposes, create one for android and ios (figure 2):

Figure 2: Two new directories for Android and iOS

When you use the Cordova CLI to create projects, the merges folder will be checked for each platform you support. If a file exists in the platform-specific merges folder that matches one in www, it will be replaced. If there is a file in the platform-specific merges folder that doesn't exist in www, it will simply be added. The subdirectory in the merges folder should be named the same as the platform you want to modify. Case does not matter. Let's look at a simple example of this in action.

We'll begin by creating a new application and making a simple "Hello World" HTML page. You can find this in the "merges_test" folder from the zip you downloaded for the book.

Listing 1: Application home page (merges_test/www/index.html

<!DOCTYPE html>
      <meta charset="utf-8" />
      <meta name="format-detection"
         content="telephone=no" />
      <meta name="msapplication-tap-highlight"
         content="no" />
      <meta name="viewport"
         content="user-scalable=no, initial-scale=1,
         maximum-scale=1, minimum-scale=1, width=device-width,
         height=device-height, target-densitydpi=device-dpi" />
      <link rel="stylesheet" type="text/css"
         href="css/index.css" />    #1
      <link rel="stylesheet" type="text/css"
         href="css/platform.css" /> #2
      <title>Hello World</title>

      <h1>Hello World</h1>
      Hello folks!

      <script type="text/javascript"
#1 Default CSS for all platforms.
#2 A specific CSS file for a platform

Notice that our application loads two different CSS files. The first one, #1, is meant to contain CSS for all platforms. The second one, #2, will be a platform specific CSS file. The main index.css is pretty minimal:

Listing 2: CSS file for all platforms (merges_test/www/css/index.css)

/* Apply to all */
h1 {
   font-family: sans-serif;

p {
   font-family: sans-serif;
   color: black;

Here is platform.css:

Listing 3: Default platform CSS file (merges_test/www/css/platform.css)

/* Blank by default */

Yes, that's it. Why do we have an (essentially) blank file? We're going to use the merges feature to provide custom CSS for one or more platforms. For platforms that don't need this feature, we want to provide a blank file so that when the application requests the CSS file, it doesn't create an error. That error wouldn't really hurt anything, but if we are debugging then we do not want a bogus error message to get in the way.

We're going to customize the Android platform only. To do that, we'll create an android folder under a merges folder in the project root, and then a css folder, and finally a platform.css file (figure 3):

Figure 3: Our directory structure now includes a merge for Android

The result will now be different for Android, and just Android, when creating builds. Cordova will notice that a file exists in the android merges folder and use that instead of the version in www. The result is a different look for Android versus iOS. Here is the Android-specific platform.css.

Listing 4: The Android modified CSS (merges_test/merges/android/css/platform.css)

body {
   background-color: aquamarine;

p {
   font-family: sans-serif;
   color: black;
   font-size: 40px;
   font-style: italic;

When running the application on both iOS and Android you can immediately see the differences in figure 4.

Figure 4: An example of how a merge can modify an application by platform


Apache Cordova: Using Merges for Multiple Platforms

By Raymond K. Camden

This article is excerpted from the book Apache Cordova in Action

Tags: CSS, Android, Apache, HTML, IOS, Merge, apache cordova, Cordova

Comment and Contribute


(Maximum characters: 1200). You have characters left.



Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date
Rocket Fuel