Generates cordova config.xml file
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-devOnce the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-cordova-config');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'
}
}
})The app's bundle identifier.
Type: (required) string
Default: "com.example.hello"
The app's version number, in semver2 format.
Type: (required) string
Default: "0.0.1"
The name of app.
Type: (required) string
Default: "HelloWorld"
A description of the app and/or its goals.
Type: string
Default: "A sample Apache Cordova application that responds to the deviceready event."
Describes the author and contact info of the project.
Type: object of:
The author's email address.
Type: string
The author's name.
Type: string
A URL to more info about the author.
Type: string
Default
{
"email": "[email protected]",
"name": "Apache Cordova Team",
"href": "http://cordova.io"
}Examples
// A simple example.
{
"email": "[email protected]",
"name": "John Smith",
"href": "http://johnsmith.me"
}The starting page of the app.
Type: (required) string
Default: "index.html"
Examples
// The starting page is myroot/index.html
"myroot/index.html"Defines the set of external domains the app is allowed to communicate with.
Type: Array<object> | object of:
The domain to allow. Wildcards (*) are supported.
Type: (required) string
Wether or not to launch the URL in an external browser (outside of the app)
Type: boolean
Wether ot not to allow subdomains. Effectively the same as http://*.domain.tld
Type: boolean
Default
[
{
"origin": "*"
}
]Examples
// Allow access to google.com
{
"origin": "http://google.com"
}// Open github.com in external browser.
{
"origin": "http://github.com",
"launchExternal": true
}// Allow access to *.google.com
{
"origin": "http://google.com",
"subdomains": true
}Controls which URLs the app is allowed to ask the system to open.
Type: Array<string> | string
Default
[
"http://*/*",
"https://*/*",
"tel:*",
"sms:*",
"mailto:*",
"geo:*"
]Examples
// Allow links to web pages to open in a browser.
[
"http://*/*",
"https://*/*"
]// Allow SMS links to open messaging app
[
"sms:*"
]Controls which URLs the WebView itself can be navigated to. Applies to top-level navigations only.
Type: Array<string> | string
Default: []
Examples
// Allow links to example.com
"http://example.com/*"A preference that can be defined.
Type: Array<object> | object of:
The name of the preference.
Type: (required) string
The value of the preference,
Type: (required) string
Default: []
Examples
// Define the webview's background color.
{
"name": "BackgroundColor",
"value": "0xff0000ff"
}Used to describe a plugin if you're not using the Cordova command line tool, but instead working directly with platform specific config.xml files.
Type: Array<object> | object of:
The plugin's name.
Type: string
Wether or not the plugin should be loaded when the app launches or load it the first time it's requested.
Type: boolean
A list of params for the plugin.
Type: Array<object> | object of:
The name of the param.
Type: (required) string
The value of the param.
Type: (required) string
Default: []
Examples
// Whitelist plugin for android.
{
"name": "Whitelist",
"onload": true,
"params": [
{
"name": "android-package",
"value": "org.apache.cordova.whitelist.WhitelistPlugin"
}
]
}Describes the app's icon.
Type: Array<object> | object of:
The path to the icon.
Type: (required) string
The icon's density.
Type: string
The icon's width.
Type: number
The icon's height.
Type: number
The icon's platform.
Type: string
Default: []
Examples
// Define some icons
[
{
"src": "res/ios/[email protected]",
"platform": "ios",
"width": 180,
"height": 180
},
{
"src": "res/ios/icon-60.png",
"platform": "ios",
"width": 60,
"height": 60
},
{
"src": "res/android/ldpi.png",
"platform": "android",
"density": "ldpi"
},
{
"src": "res/android/mdpi.png",
"platform": "android",
"density": "mdpi"
}
]Defines a splash screen to show.
Type: Array<object> | object of:
The path to the splash screen.
Type: (required) string
The splash screen's density.
Type: string
The splash screen's width.
Type: number
The splash screen's height.
Type: number
The splash screen's platform.
Type: string
Default: []
Examples
// Define some splash screens.
[
{
"src": "res/screen/ios/Default~iphone.png",
"platform": "ios",
"width": 320,
"height": 480
},
{
"src": "res/screen/ios/Default@2x~iphone.png",
"platform": "ios",
"width": 640,
"height": 960
},
{
"src": "res/screen/android/splash-land-hdpi.png",
"platform": "android",
"density": "land-hdpi"
},
{
"src": "res/screen/android/splash-land-mdpi.png",
"platform": "android",
"density": "land-mdpi"
}
]Describes a platform level configuration.
Type: Array<object> | object of:
Type: (required) string
Can include any normal configuration.
Default
[
{
"name": "android",
"allowIntents": [
"market:*"
]
},
{
"name": "ios",
"allowIntents": [
"itms:*",
"itms-apps:*"
]
}
]Examples
[
{
"name": "android",
"allowIntent": [
"market:*"
],
"icon": [
{
"src": "res/android/ldpi.png",
"density": "ldpi"
},
{
"src": "res/android/mdpi.png",
"density": "mdpi"
}
]
},
{
"name": "ios",
"allowIntent": [
"itms:*",
"itms-apps:*"
],
"icon": [
{
"src": "res/ios/[email protected]",
"width": 180,
"height": 180
},
{
"src": "res/ios/icon-60.png",
"width": 60,
"height": 60
}
]
}
]A platform to auto add with specified platform version.
Type: Array<object> | object of:
The engine name.
Type: (required) string
The engine spec/version.
Type: (required) string
Default: []
Examples
// Add Android platform version 4.0.2
{
"name": "android",
"spec": "4.0.2"
}// Add iOS platform version 3.8.0
{
"name": "ios",
"spec": "3.8.0"
}Describes a plugin that the app utilizes.
Type: Array<object> | object of:
The plugin's name.
Type: (required) string
The plugin's spec/version.
Type: (required) string
Default
[
{
"name": "cordova-plugin-whitelist",
"spec": "1"
}
]Examples
// Add whitelist plugin.
[
{
"name": "cordova-plugin-whitelist",
"spec": "1"
}
]Defines an action to be run during a certian cordova lifecycle event.
Type: Array<object> | object of:
The hook type.
Type: (required) string
The path to the hook to execute.
Type: (required) string
Default: []
Examples
// Run path/to/myscript.js after the app is prepared.
{
"type": "after_prepare",
"src": "myscript.js"
}// Run path/to/myscript.sh before a clean is done.
{
"type": "before_clean",
"src": "path/to/myscript.sh"
}A block of configuration file content for use with cordova-custom-config.
Type: Array<object> | object of:
The config file to which the contents will be added.
Type: (required) string
The existing item under which the contents will be added (XPath for Android, plist key name for iOS).
Type: (required) string
The js2xmlparser-compatible JSON object to insert into the configuration file as XML.
Type: (required) object of:
Default: []
Examples
// Add values to the AndroidManifest.xml file
{
"target": "AndroidManifest.xml",
"parent": "/*",
"contents": {
"supports-screens": {
"@": {
"android:xlargeScreens": false,
"android:largeScreens": false,
"android:smallScreens": true
}
},
"uses-permission": [
{
"@": {
"android:name": "android.permission.READ_CONTACTS",
"android:maxSdkVersion": 15
}
},
{
"@": {
"android:name": "android.permission.WRITE_CONTACTS"
}
}
]
}
}// Add an array value to the iOS Info.plist file
{
"target": "*-Info.plist",
"parent": "UIBackgroundModes",
"contents": {
"array": {
"string": "location"
}
}
}// Add a dict value to the iOS Info.plist file
{
"target": "*-Info.plist",
"parent": "NSAppTransportSecurity",
"contents": {
"dict": {
"key": [
"NSAllowsArbitraryLoads",
"true"
]
}
}
}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'
}
}
})grunt.initConfig({
cordova_config: {
options: {
id: 'com.example.application',
name: 'app name',
author: {
name: 'First Last',
email: '[email protected]'
},
preferences: [
{
name: 'fullscreen',
value: true
},
{
name: 'webviewbounce',
value: false
},
{
name: 'UIWebViewBounce',
value: false
},
{
name: 'DisallowOverscroll',
value: true
},
{
name: 'BackupWebStorage',
value: 'none'
}
],
features: [
{
name: 'StatusBar',
onload: true,
params: [
{
name: 'ios-package',
value: 'CDVStatusBar'
}
]
}
]
icons: [
{
src: 'icon-default.png'
}
],
platforms: [
{
name: 'ios',
icons: [
{
src: 'res/Icon-60.png',
width: 60,
height: 60
}
],
splashes: [
{
src: 'res/Default.png',
width : 320,
height: 480
}
],
preferences: [
{
name: 'fullscreen',
value: false
}
]
}
]
}
dest: 'cordova-project/www/config.xml'
}
});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.
Adding a new property/option to grunt-cordova-config is relatively painless. Add a new file inisde of src/configs that will contain the declaration for your new property. You can reference an existing config.
Each config must declare the following:
- occurances (string)
- This is how many times this configuration can appear in the options. Valid values are
multipleorsingle.- Single means that the configuration can only occur once and at the root of the options.
- Multiple means it can occur anywhere and at anytime, multiple times. An example of this would be the icon config. It can appear in the root of the options, or inside of a platform configuration.
- This is how many times this configuration can appear in the options. Valid values are
- hasMany (boolean)
- This is wether or not the option can handle multiple values. The value passed in will automatially be converted to an array if it is not already when this is set to true. An example of this would be the icon configuration.
- optionsKey (string)
- This is only required if your configuration has a specific option key that it correlates to. You can leave this blank to handle the options parsing yourself.
- getDefaultOptions (() => any)
- This function should return what the default options are.
- getDocumentation (() => object)
- This function should return documentation about your config.
- The result should be an object with the following format:
-
{ description: 'The description about your config.', examples: [ { title: 'An example', example: { // An object example. This will be JSON.stringify-ied } } ], moreInfo: 'http://aUrlToMoreInfo', type: { someKey: { description: // ... examples: // ... moreInfo: // ... type: // ... } } }
- All of the fields are optional except for `type`. This field can be either: - A single element array of any of the following, or one of the following: - An object with key-value pairs. The key being the name of a property, and the value being the description of that property. - A string. -
- The result should be an object with the following format:
- This function should return documentation about your config.
- processor ((object,() => object) => object)
- This function is called to transform the options into a JSON XML object. The first argument passed in is the options, and the second argument is a nested processor that you can call to include child options. An example of this would be the
platformsconfig, allowing you to nest more configurations inside it.
- This function is called to transform the options into a JSON XML object. The first argument passed in is the options, and the second argument is a nested processor that you can call to include child options. An example of this would be the
This project is written in ES6. To compile with grunt use: grunt babel. The sources inside src will be built and placed inside the lib directory.
grunt jshint
grunt blueimp_tmpl
grunt nodeunit
Copyright (c) 2014 Andrey Shustariov. Licensed under the MIT license.