grunt-cordova-config
v0.2.1
Published
Generates cordova config.xml file
Downloads
52
Maintainers
ashustariovReadme
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-devOnce 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
The app's bundle identifier.
Type: (required) string
Default: "com.example.hello"
options.version
The app's version number, in semver2 format.
Type: (required) string
Default: "0.0.1"
options.name
The name of app.
Type: (required) string
Default: "HelloWorld"
options.description
A description of the app and/or its goals.
Type: string
Default: "A sample Apache Cordova application that responds to the deviceready event."
options.author
Describes the author and contact info of the project.
Type: object of:
options.author.email
The author's email address.
Type: string
options.author.name
The author's name.
Type: string
options.author.href
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"
}options.content
The starting page of the app.
Type: (required) string
Default: "index.html"
Examples
// The starting page is myroot/index.html
"myroot/index.html"options.access
Defines the set of external domains the app is allowed to communicate with.
Type: Array<object> | object of:
options.access.origin
The domain to allow. Wildcards (*) are supported.
Type: (required) string
options.access.launchExternal
Wether or not to launch the URL in an external browser (outside of the app)
Type: boolean
options.access.subdomains
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
}options.allowIntents
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:*"
]options.allowNavigations
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/*"options.preferences
A preference that can be defined.
Type: Array<object> | object of:
options.preferences.name
The name of the preference.
Type: (required) string
options.preferences.value
The value of the preference,
Type: (required) string
Default: []
Examples
// Define the webview's background color.
{
"name": "BackgroundColor",
"value": "0xff0000ff"
}options.features
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:
options.features.name
The plugin's name.
Type: string
options.features.onload
Wether or not the plugin should be loaded when the app launches or load it the first time it's requested.
Type: boolean
options.features.params
A list of params for the plugin.
Type: Array<object> | object of:
options.features.params.name
The name of the param.
Type: (required) string
options.features.params.value
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"
}
]
}options.icons
Describes the app's icon.
Type: Array<object> | object of:
options.icons.src
The path to the icon.
Type: (required) string
options.icons.density
The icon's density.
Type: string
options.icons.width
The icon's width.
Type: number
options.icons.height
The icon's height.
Type: number
options.icons.platform
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"
}
]options.splashes
Defines a splash screen to show.
Type: Array<object> | object of:
options.splashes.src
The path to the splash screen.
Type: (required) string
options.splashes.density
The splash screen's density.
Type: string
options.splashes.width
The splash screen's width.
Type: number
options.splashes.height
The splash screen's height.
Type: number
options.splashes.platform
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"
}
]options.platforms
Describes a platform level configuration.
Type: Array<object> | object of:
options.platforms.name
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
}
]
}
]options.engines
A platform to auto add with specified platform version.
Type: Array<object> | object of:
options.engines.name
The engine name.
Type: (required) string
options.engines.spec
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"
}options.plugins
Describes a plugin that the app utilizes.
Type: Array<object> | object of:
options.plugins.name
The plugin's name.
Type: (required) string
options.plugins.spec
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"
}
]options.hooks
Defines an action to be run during a certian cordova lifecycle event.
Type: Array<object> | object of:
options.hooks.type
The hook type.
Type: (required) string
options.hooks.src
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"
}options.configFiles
A block of configuration file content for use with cordova-custom-config.
Type: Array<object> | object of:
options.configFiles.target
The config file to which the contents will be added.
Type: (required) string
options.configFiles.parent
The existing item under which the contents will be added (XPath for Android, plist key name for iOS).
Type: (required) string
options.configFiles.contents
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"
]
}
}
}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: '[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'
}
});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.
Development
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.
API
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
Build
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.
Lint
grunt jshint
Documentation
grunt blueimp_tmpl
Test
grunt nodeunit
License
Copyright (c) 2014 Andrey Shustariov. Licensed under the MIT license.