Newstex / grunt-cordova-config

Generates cordova config.xml file

grunt-cordova-config

Generates cordova config.xml file

Getting Started

This plugin requires Grunt.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-cordova-config --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-cordova-config');

The "cordova_config" task

Overview

In your project's Gruntfile, add a section named cordova_config to the data object passed into grunt.initConfig().

grunt.initConfig({
  cordova_config: {
    my_target: {
        options : {
            id : 'com.example.hello',
            version : '1.0.0',
            // ...
        },
        dest : 'path/to/config.xml
      
    }
  },
})

Options

options.id

Type: String

Default value: com.example.hello

options.version

Type: String

Default value: 0.0.1

options.androidVersionCode

Type: Number (optional)

Can be used to override the default code calculated by Cordova as PATCH + MINOR * 100 + MAJOR * 10000

options.iosBundleVersion

Type: String (optional)

Can be used to override the default code generated by Cordova as "MAJOR.MINOR.PATCH"

options.name

Type: String

Default value: HelloWorld

options.description

Type: String

Default value: A sample Apache Cordova application that responds to the deviceready event.

options.author.name

Type: String

Default value: Apache Cordova Team

options.author.email

Type: String

Default value: [e-mail]

options.author.href

Type: String

Default value: http://cordova.io

options.content.src

Type: String

Default value: index.html

options.access.origin

Type: String

Default value: *

options.preferences

Type: Array of (Preference objects)

Example:

preferences: [
{
	name : 'fullscreen',
	value: true
},
{
	name : 'webviewbounce',
	value: false
},
...

Default value: []

options.features

Type: Array

Example:

features : [
  {
    name : 'StatusBar',
    params: [
      {
        name  : 'ios-package',
        value : 'CDVStatusBar',
        onload: true
      }
    ]
  }
]

Default value: []

options.icons

Type: Array of (Image objects)

References images from which Cordova can generate appropriately-sized icons for each platform. This is particularly useful for early prototypes for which platform-specific icons have not yet been created. See also the icons attribute in options.platforms.

Example:

icons : [
  {
    src : 'res/icon-1024.png'
  }
]

Default value: []

options.platforms

Type: Array of (Platform objects)

Example:

platforms : [
  {
    name : 'ios',
    icons: [
      {
        src   : 'res/Icon-60.png',
        width : 60,
        height: 60
      }
    ],
    splash: [
      {
        src   : 'res/Default.png',
        width : 320,
        height: 480
      }
    ],
    preferences: [
      {
        fullscreen: false
      }
    ]
  },
  {
    name : 'android',
    icons: [
      {
        src    : 'res/icon-hdpi.png',
        density: 'hdpi'
      }
    ]
  }
]

Preference Objects

preference.name

Type: String

preference.value

Type: any

Image Objects

Please refer to the Cordova/PhoneGap Icons and Splash Screens documentation for usage. Generally, Android requires the density parameter while other platforms either use width and height or require a specific image name.

image.src

Type: String

image.density

Type: String (optional)

image.width

Type: Number (optional)

image.height

Type: Number (optional)

image.platform

Type: String (optional)

For use in option.icons, though specifying icons in the platforms array may be preferable.

Platform Objects

platform.name

Type: String

platform.icons

Type: Array of (Image objects)

platform.splash

Type: Array of (Image objects)

platform.preferences

Type: Array of (Preference objects)

Usage Examples

Default Options

In this example, the default options are used to generate config.xml file. The result will be the same as after cordova create command

grunt.initConfig({
  cordova_config: {
    my_target : {
      dest: 'cordova-project/www/config.xml'
    }
  },
})

Custom Options

grunt.initConfig({
  cordova_config: {
    options: {
      id: 'com.example.application',
      name: 'app name',
      author : {
      	name : 'First Last',
        email : '[e-mail]'
      },
      preferences: [
        {
          name : 'fullscreen',
          value: true
        },
        {
          name : 'webviewbounce',
          value: false
        },
        {
          name : 'UIWebViewBounce',
          value: false
        },
        {
          name : 'DisallowOverscroll',
          value: true
        },
        {
          name : 'BackupWebStorage',
          value: 'none'
        }
      ],
      features   : [
        {
          name  : 'StatusBar',
          params: [
              {
                  name  : 'ios-package',
                  value : 'CDVStatusBar',
                  onload: true
              }
          ]
        }
      ],
      icons : [
        {
          src : 'icon-default.png'
        }
      ],
      platforms : [
        {
          name : 'ios',
          icons: [
            {
              src   : 'res/Icon-60.png',
              width : 60,
              height: 60
            }
          ],
          splash: [
            {
              src   : 'res/Default.png',
              width : 320,
              height: 480
            }
          ],
          preferences: [
            {
              fullscreen: false
            }
          ]
        }
      ]
    },
    dest : 'cordova-project/www/config.xml'
  }
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

License

Copyright (c) 2014 Andrey Shustariov. Licensed under the MIT license.