grunt-cordova-config
Generates cordova config.xml file
Last updated 4 years ago by ashustariov .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install grunt-cordova-config 
SYNC missed versions from official npm registry.

grunt-cordova-config

Generates cordova config.xml file

Build Status Dependency Status devDependency Status

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

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

More Info

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

More Info

Default

{
    "email": "dev@callback.apache.org",
    "name": "Apache Cordova Team",
    "href": "http://cordova.io"
}

Examples

// A simple example.
{
    "email": "someone@someplace.com",
    "name": "John Smith",
    "href": "http://johnsmith.me"
}

options.content

The starting page of the app.

Type: (required) string

More Info

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

More Info

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

More Info

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

More Info

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

More Info

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

More Info

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

More Info

Default: []

Examples

// Define some icons
[
    {
        "src": "res/ios/icon-60@3x.png",
        "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

More Info

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.

More Info

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/icon-60@3x.png",
                "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

More Info

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

More Info

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

More Info

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:

More Info

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@example.com'
            },
            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 multiple or single.
      • 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.
  • 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.
        
  • 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 platforms config, allowing you to nest more configurations inside it.

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.

Current Tags

  • 0.2.1                                ...           latest (4 years ago)

6 Versions

  • 0.2.1                                ...           4 years ago
  • 0.2.0                                ...           5 years ago
  • 0.1.3                                ...           5 years ago
  • 0.1.2                                ...           5 years ago
  • 0.1.1                                ...           6 years ago
  • 0.1.0                                ...           6 years ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dependencies (2)
Dev Dependencies (11)

Copyright 2014 - 2016 © taobao.org |