Config.xml is a platform specific configuration file.

With the help of this configuration file, it is possible to modify the default values of PhoneGap application elements like –

  • Widget
  • Name
  • Description
  • Plugins
  • API
  • Icons
  • Splash Screens etc.

Important Points About Config.xml

  1. Make sure it is at the top level of your application.
  2. You can take a look at the file structure of PhoneGap here.
  3. Its major purpose is to let developers specify the metadata about the application.

Now let’s take a look at the steps through which you can create a configuration file:

Step 1: Including XML Element

The very first step while creating a configuration file is to include XML element with the attributes version and encoding type.

<?xml version = "1.0" encoding = "UTF-8"?>

Step 2: Including Widget, Name & Description Element

Following elements are the basic elements of the configuration file. Their inclusion is mandatory.

Necessary Elements

  1. <widget>: (required) It is the root of the configuration file. It indicates that whether configuration file is following W3C Standards or not.
    <widget xmlns = "http://www.w3.org/ns/widgets"
    xmlns:gap = "http://phonegap.com/ns/1.0"
    id = "com.formget.sample"
    versionCode = "1"
    version = "1.0.0">

    (a) id: It acts like the unique identifier for an application. It is written as reverse domain format. An application supports different platforms because of it.

    id = "com.formget.sample"

    (b) version: Full version number of the application with the three number format : “Major.Minor.Patch”.

    version = "1.0.0"

    (c) versionCode: (optional) Internal version number only set for android.

    versionCode = "1"

    (d) cfBundleVersion: (optional) Internal version number only set for ios.

  2. <name>: (required) It is the name of the application which is going to be visible on home screen and app store.
    <name>FormGet</name>
  3. <description>: (optional) It is the description of the application that what this app is all about and what it does.
    <description>An online form building application to create & design any type of HTML web form</description>

Step 3: Including Author Element

(optional) It defines the author of the application with the attributes email and href.

<author email="neeraj@formget.com" href="http://formget.com">FormGet Team</author>

Step 4: Including Content Element

(optional) It sets the starting page of the application.

<content src="index.html"/>

Step 5: Including Platform Element

By default PhoneGap Build builds an application for all platforms. If you want to build an app for a specific platform, you can do it with gap:platform element or platform element.

With ‘gap:platform’ Element:

<gap:platform name="android"/>
<gap:platform name="ios"/>
<gap:platform name="winphone"/>

With ‘platform’ Element:

<platform name="android" />
<platform name="ios" />
<platform name="winphone" />

Step 6: Including Feature (API) Element

Feature Element is used to include the features (API) which are going to used by the application.

Suppose you want to include the network feature.

<feature name="http://api.phonegap.com/1.0/network" />

Similarly, you can add multiple features.

<feature name="http://api.phonegap.com/1.0/network" />
<feature name="http://api.phonegap.com/1.0/camera" />
<feature name="http://api.phonegap.com/1.0/notification" />
<feature name="http://api.phonegap.com/1.0/geolocation" />
<feature name="http://api.phonegap.com/1.0/media" />
<feature name="http://api.phonegap.com/1.0/contacts" />
<feature name="http://api.phonegap.com/1.0/file" />
<feature name="http://api.phonegap.com/1.0/battery" />
<feature name="http://api.phonegap.com/1.0/device" />

Step 7: Including Plugin Element

Plugin Element is used to include the plugins.

Plugin

<plugin name="com.phonegap.plugins..barcodescanner" spec="~1" source="npm" />
  1. name: Plugin id with the reverse domain format.
     name="com.phonegap.plugins..barcodescanner" 
  2. spec: (optional) Plugin version.
    spec="~1"
  3. source: (optional) It can be pgb or npm.
    source="npm"
  4. params: (optional) Parameters for configuration properties.

Suppose you want to include the barcodescanner plugin.

<plugin name="com.phonegap.plugins..barcodescanner" spec="~1" source="npm" />

There are several plugins available for different purposes. You can see them here.

Step 8: Including Preference Element

There are 2 types of preferences you can set in the configuration file of PhoneGap.

  1. Common Preferences
  2. Platform Specific Preferences

Common Preferences:

Common Preferences

  1. Fullscreen Preference: It makes the application full screen. It is used to hide the status bar at the top of the screen.
    <preference name="Fullscreen" value="true"/>
  2. DisallowOverscroll Preference: If you don’t want the application to show anything when users scroll past the beginning or end of content, set this to true.
    <preference name="DisallowOverscroll" value="true"/>
  3. Orientation Preference: Orientation allows you to set and fix the orientation of the app to avoid automatic rotation.
    There are three options for orientation: default, landscape and portrait.

    <preference name="Orientation" value="landscape"/>
  4. HideKeyboardFromAccessoryBar Preference: Sets to true to hide additional toolbar above the keyboard.
    <preference name="HideKeyboardFormAccessoryBar" value="false"/>
  5. BackgroundColor Preference: Sets the background color of the application with a 4 byte format.
    Byte 1 : Alpha Channel
    Byte 2-4 : RGB(Red Green Blue Colors)

    <preference name="BackgroundColor" value="0xff0000ff"/>

Platform Specific Preferences:

Platform Specific Preferences:

IOS Specific Preferences

  1. Target-Device Preference: Targeting the specific device. Its options are : handset, tablet, or universal.
    <preference name="target-device" value="universal" />
  2. Prerendered-icon Preference: Sets to ‘true’ to let ios know that icon is already rendered and don’t add anything to it.
    <preference name="prerendered-icon" value="true" />
  3. Detect-data-types: Checks whether data types (For Example: dates and phone numbers) are automatically converted to links by the system.
    <preference name="detect-data-types" value="true" />
  4. Exit-on-suspend: Application will be closed when suspended.
    <preference name="exit-on-suspend" value="true" />
  5. Deployment-target: It sets the IPHONEOS_DEPLOYMENT_TARGET in the build process, which is converted to theMinimumOSVersion in the ipa Propertly List.
    <preference name="deployment-target" value="7.0" />

Android Specific Preferences

  1. KeepRunning: App will continue to run in the background.
    <preference name="KeepRunning" value="false"/>
  2. LoadUrlTimeoutValue: It sets the amount of time to wait during a page load. After that, it will throw a timeout error. It is in milliseconds.
    <preference name="LoadUrlTimeoutValue" value="5000"/>
  3. SplashScreen: To set the names of the splash screen images. They must share a common name.
    <preference name="SplashScreen" value="FormGetSplash"/>
  4. SplashScreenDelay: The amount to time a splash screen appears. It is in milliseconds.
    <preference name="SplashScreenDelay" value="5000"/>
  5. InAppBrowserStorageEnabled: It makes sure that web pages opened in an InAppBrowser and web pages opened in the default browser share the same localStorage.
    <preference name="InAppBrowserStorageEnabled" value="true"/>
  6. LoadingDialog: It displays a dialog at the first page of the application with a title, message and a loading image.
    <preference name="LoadingDialog" value="My Title,My Message"/>
  7. LoadingPageDialog:  It displays a dialog at every page of the application.
    <preference name="LoadingPageDialog" value="My Title,My Message"/>
  8. ErrorUrl: Intead of dialog, an error page will be displayed with a title,”Application Error”.
    <preference name="ErrorUrl" value="myErrorPage.html"/>
  9. ShowTitle: It displays the title at the top of the screen.
    <preference name="ShowTitle" value="true"/>
  10. LogLevel: Its sets the log level to minimum. By doing this, log messages of the app are filtered. Options are :   ERROR, DEBUG, INFO, VERBOSE, and WARN.
    <preference name="LogLevel" value="VERBOSE"/>
  11. SetFullscreen: It is similar to the FullScreen of global config file.
    <preference name="SetFullscreen" value="false"/>

Step 9: Including Icon and Spash Element

Icons and Splashes are also platform specific. Use ‘icon’ element to include ‘icons’ and use ‘splash’ element to include ‘splash screens’.

There are 2 ways to include icons and splashes:

  1. Use icon and splash element directly
    <icon src="formget-icon.png" platform="ios" width="180" height="180"/>
    <splash src="formget-icon.png" platform="ios" width="180" height="180"/>
  2. Put icon element inside the platform element
    <platform name="ios">
    <icon src="formget-icon.png" width="180" height="180" />
    <splash src="formget-icon.png" platform="ios" width="180" height="180"/>
    </platform>

Icons:

Icon

<icon src="formget-icon.png" platform="ios" width="180" height="180"/>
  1. src: (required) Source/Location of the icon image file specific to the www folder.
    src= "formget-icon.png" 
  2. platform: (optional) Platform for which the icon belongs to.
    platform="ios"
  3. width: (optional) Width of the icon image.
    width="180"
  4. height: (optional) Height of the icon image.
    height="180"

Similarly, icons of different sizes can be included for different platforms.

Splashes:

Splash

<splash src="formget-icon.png" platform="ios" width="180" height="180"/>
  1. src: (required) Source/Location of the splash image file specific to the www folder.
    src= "formget-icon.png" 
  2. platform: (optional) Platform for which the icon belongs to.
    platform="ios"
  3. width: (optional) Width of the icon image.
    width="180"
  4. height: (optional) Height of the icon image.
    height="180"

Similarly, splash screens of different sizes can be included for different platforms.

Conclusion:

So you see, how easy it is to configure PhoneGap using the configuration file. It’s no rocket science to include icons, splash screens, plugins and other elements. I hope this will definitely help you.