Config.xml: customizing the app

The Cordova config.xml file in a cordova project directory, is used to inform the various build processes of stuff like the app name and which plugins to use.

Because coraline apps don’t actually need to be compiled–we’re just distributing the HTML/CSS/JS in some content directory–we need a way to inform them of these same settings if we want to customize the user experience.

The easiest way to do this, if you’ve got a cordova or ionic app, is just to copy the top level directory’s config.xml file into the root of the content directory you will be distributing.

But if you don’t have a cordova/ionic project, you can create a suitable config.xml file easily.  It has only one requirement–a top level

<widget />

element–and a few optional elements within that.  Here’s the a minimalist example of a config.xml file:

<?xml version='1.0' encoding='utf-8'?>
<widget id="com.example.myapp" version="1.2.0" 
   xmlns="http://www.w3.org/ns/widgets" 
   xmlns:cdv="http://cordova.apache.org/ns/1.0">
 <name>My App</name>
 <description>
 My App: a sample coraline application
 </description>
 <author email="myname@example.com" 
     href="https://psychogenic.com/">
   Pat Deegan
 </author> 
 <icon src="assets/icon/myapp.png" />
 <splash src="assets/img/mysplash.png" />
 <plugin name="cordova-plugin-dialogs" />
 <plugin name="cordova-plugin-device" />
</widget>

In bold are the parts coraline currently actually cares about.

Widget element

The <widget /> element has two jobs:

  1. to provide your app id
  2. to contain the other elements

The app id attribute is your unique application id.  It may be used by plugins (e.g. with the id com.example.myapp, the SQLite plugin would create database files within ~/.myapp/ ).

App Name

The <name /> element contains a short name for your application.  This is the name that will be given to and displayed on the top window while the application is running.

Icon

The <icon /> element needs a src attribute, that uses a relative URI that points to an image file within your content directory.

When deployed following the indications, this icon will be displayed by the window manager for your app.  It is also used by the notifications plugin for native dialogs.

Here’s a sample of what it looks like, with a custom name and icon set for the druid builder app (you can see the icon on the bottom left, next to the mouse cursor)

Splash

The <splash /> element is like the icon element,except that this will be displayed as a popup during loading of your app.

Plugin

The list of <plugin /> elements is the same as with cordova.  Just list any plugin(s) you are using and (if they’re actually available–see the deployment guide to ensure that they are) they will be loaded.