3 Cordova CLI Changes You Should Know About

February 10, 2014By 7 Comments

If you’re using the Cordova CLI (command line interface) to create Cordova/PhoneGap projects, then you should be aware of some recent tool updates that help make things easier when you update to this latest version (Cordova CLI version 3.3.1-0.3.1).

Here are some changes I specifically want to highlight:

  1. The config.xml file is created in the project root now (no longer in www folder)

    Screen Shot 2014-02-10 at 1.52.35 PM The root project folder now contains a basic config.xml with some core elements for configuring the app name, description etc and the access-origin set to a wildcard (* ) to prevent whitelist errors. You should modify this root config.xml with the preferences that apply to all platforms you’re targeting and the contents will be merged with some default platform-specific elements at build time and put in their proper final locations per platform.

    For instance, when building for android, the merged config.xml is created at this path: MyProject/platforms/android/res/xml/config.xml. For iOS it is put in MyProject/platforms/ios/MyProject/config.xml.

    To illustrate how this file is used when building per platform, assume you start with the basic generated config.xml file created from the cordova create command:

    <?xml version='1.0' encoding='utf-8'?>
    <widget id="org.devgirl.mydemo" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
        <name>MyDemoApp</name>
        <description>
            A sample Apache Cordova application that responds to the deviceready event.
        </description>
        <author email="dev@cordova.apache.org" href="http://cordova.io">
            Apache Cordova Team
        </author>
        <content src="index.html" />
        <access origin="*" />
    </widget>
    

    If I edit it to change some basic info and add a global preference to specify that it be locked to landscape orientation, such as:

    <?xml version='1.0' encoding='utf-8'?>
    <widget id="org.devgirl.mydemo" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
        <name>MyDemoApp</name>
        <description>
            Holly's Demo App
        </description>
        <author email="devgirl@devgirl.org" href="http://devgirl.org">
           Holly Schinsky
        </author>
        <preference name="Orientation" value="landscape" />
        <content src="index.html" />
        <access origin="*" />
    </widget>
    

    When I run:
    $ cordova build ios

    I will get the following output indicating default values are being added to the config.xml as part of the output from the CLI:
    Generating config.xml from defaults for platform "ios"

    And my merged config.xml file for my ios platform folder (MyDemoApp/platforms/ios/MyDemoApp/config.xml) looks like below and includes some default iOS settings as well as the contents I had added to my base root config.xml:

    <?xml version='1.0' encoding='utf-8'?>
    <widget id="org.devgirl.mydemo" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
        <name>Hello Cordova</name>
        <preference name="AllowInlineMediaPlayback" value="false" />
        <preference name="BackupWebStorage" value="cloud" />
        <preference name="DisallowOverscroll" value="false" />
        <preference name="EnableViewportScale" value="false" />
        <preference name="KeyboardDisplayRequiresUserAction" value="true" />
        <preference name="MediaPlaybackRequiresUserAction" value="false" />
        <preference name="SuppressesIncrementalRendering" value="false" />
        <preference name="TopActivityIndicator" value="gray" />
        <preference name="GapBetweenPages" value="0" />
        <preference name="PageLength" value="0" />
        <preference name="PaginationBreakingMode" value="page" />
        <preference name="PaginationMode" value="unpaginated" />
        <feature name="LocalStorage">
            <param name="ios-package" value="CDVLocalStorage" />
        </feature>
        <name>MyDemoApp</name>
        <description>
            Holly's Demo App
        </description>
        <author email="devgirl@devgirl.org" href="http://devgirl.org">
           Holly Schinsky
        </author>
        <preference name="Orientation" value="landscape" />
        <content src="index.html" />
        <access origin="*" />
    </widget>
    

    If I then do the same for android:

    $ cordova build ios
    Again I will get the following output indicating default values are being added to the config.xml as part of the output from the CLI:

    Generating config.xml from defaults for platform "android"

    And when I look at the resulting MyDemoApp/platforms/android/res/xml/config.xml file I see:

    <?xml version='1.0' encoding='utf-8'?>
    <widget id="org.devgirl.mydemo" version="0.0.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">
        <name>Hello Cordova</name>
        <preference name="loglevel" value="DEBUG" />
        <feature name="App">
            <param name="android-package" value="org.apache.cordova.App" />
        </feature>
        <name>MyDemoApp</name>
        <description>
            Holly's Demo App
        </description>
        <author email="devgirl@devgirl.org" href="http://devgirl.org">
           Holly Schinsky
        </author>
        <preference name="Orientation" value="landscape" />
        <content src="index.html" />
        <access origin="*" />
    </widget>
    

    In this case there are less defaults added for android (note the loglevel set to DEBUG and App feature), but you can see my root config.xml contents were also merged in to this final location.

    For more details on the specific settings and preferences that can be specified across and per platform, see here.

    The docs still need to be updated to show the move from the www path so please disregard where the path is shown under www for now.
  2. New create options to create a project with your own custom www contents (via copy (--copy-from) or symbolic link (--link-to))

    Allows you to specify an existing www folder to copy from or link to rather than generating the default project and having to delete it.

    For instance, assume I have ~/demo/www folder containing some custom code I want to create a mobile app with already on my hard drive with the following contents:
    Screen Shot 2014-02-10 at 12.53.13 PMTo use this folder/contents when creating a new cordova project, I can specify the --copy-from option and then the path to copy from, such as:

    $ cordova create MyDemoApp "org.devgirl.mydemo" "MyDemoApp" --copy-from ~/demo/www

    The following output is shown after this command is run from the CLI:
    Screen Shot 2014-02-10 at 1.40.20 PM 1The resulting www folder in my MyDemoApp root now contains custom contents from ~/demo/www rather than the default project:
    Screen Shot 2014-02-10 at 1.43.23 PM
    To link to an existing folder I can specify --link-to and the path to create a symbolic link to:

    $ cordova create MyDemoApp2 "org.devgirl.mydemo2" "MyDemoApp2" --link-to ~/demo/www

    I’m again notified that custom assets are being used but when I list the files in the newly created project, it shows that a link was created to the custom www folder this time (denoted by www -> /Users/hollyschinsky/demo/www):

    Screen Shot 2014-02-10 at 1.00.05 PM

  3. The /hooks folder is now created in the root project:

    With this latest update the hooks folder is now part of the root project rather than under .cordova.
    Screen Shot 2014-02-10 at 3.35.50 PM

    I highly recommend reading this post for details about how to use this folder to increase productivity.

Be sure to check out the post on the Apache Cordova website regarding this update for more updates and details.

Filed in: AndroidCordovaHTML/JSiOSMobile DevelopmentPhoneGap Tags:

About the Author ()

Comments (7)

Trackback URL | Comments RSS Feed

Sites That Link to this Post

  1. Accessing more information from your Cordova CLI hooks | Dan Moore! | February 17, 2014
  1. Alberto says:

    Hi Holly,

    thanks for the info.
    I am struggling to understand if it’s better to use cordova-cli or phonegap-cli.
    Even phonegap documentation http://docs.phonegap.com/en/3.3.0/guide_cli_index.md.html#The%20Command-Line%20Interface now uses cordova command.
    Could you, please, help us to understand?

    Cheers,

    Alberto

    • Juliano says:

      Hi Alberto,
      I also have this very same question and as far as I understood (please Holly or readers, correct me if I am wrong) running Cordova CLI locally give us some flexibility when building packages (custom settings, permissions, etc), easier debugging (you can use ripple emulator), not all plugins are available on phonegap cloud and we don’t need to rely on them to build. But all those facilities come with a cost, you will need to setup all the environments you want to target the devices you need (ie: android SDK, win SDK, etc). In my case, as I use a windows environment, I can’t build iOS locally and therefore I use Phonegap build to create the iOS package for me.
      Phonegap is getting more attention every day and consequently their services are getting better and better. Debug remotely is very good and Hydration is very handy too. Ah, almost forgot to say .. building locally you can have as many as private projects you want and on Phonegap you can only have 1 private for free and unlimited on Github ;-)

      I’m not an expert and Holly’s blog have been helping me a lot; it is really good and very informative.

      Thanks all

      Juliano X

  2. Michael says:

    npm update -g Cordova gives no indication that it does anything in CLI.

    @Anthony this has been an issue for over a year. Nobody will help you to understand the logic. My suggestion is use Cordova even though there are commands that do nothing.

  3. Matt Ray says:

    Holly,

    Thanks for the info. Quick note that in the middle you state “If I then do the same for android:” but then forgot to modify the pasted command to “cordova build android”.

    Anyway, your blogs are always very informative and helpful. Thanks again!

    Matt Ray

  4. Anthony says:

    Hi Holly,

    I am trying to add something to my config.xml and was wondering if you could lend any insight.

    Here is a link if you have a moment.

    http://stackoverflow.com/questions/22769111/add-entry-to-ios-plist-file-via-cordova-config-xml

    Thanks! Great blogs.

    ~Anthony

    • Juliano says:

      Hi Anthony,

      I’m not an expert on Cordova/Phonegap but have you tried to use “Cordova Hooks”? https://github.com/apache/cordova-cli#hooks

      As far I understood using those scripts you can move/copy data and files, add/modify settings and much more; on a module and project level.

      I hope this can be helpful as a solution or at least giving you some sort of direction ;-)

      Cheers
      Juliano

Leave a Reply