@titanium/tiapp-xml

    1.0.3 • Public • Published

    @titanium/tiapp-xml

    @titanium/tiapp-xml Dependabot Status

    Modify your tiapp.xml file from Node.js. This is a fork from tonylukasavage that primarily addresses the "." in the package name and module but leaving room to possibly add more enhancements.

    📝 Description

    A node.js parsing and manipulation API module for Appcelerator's Titanium tiapp.xml configuration file. It makes it exceedingly easy now to read and modify entries in the tiapp.xml file programmatically. No need to manually parse XML anymore, but you can if you so choose.

    For complete details regarding tiapp.xml files, please consult Appcelerator's full documentation.

    🚀 Getting Started

    Install

    Install @titanium/tiapp-xml in root of your project

    $ npm install @titanium/tiapp-xml

    Examples

    Change the Titanium SDK version

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    tiapp.sdkVersion = '8.1.0.GA';
    tiapp.write();

    Disable analytics

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    tiapp.analytics = false;
    tiapp.write();

    Add a new native module for android

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    tiapp.setModule('com.tonylukasavage.someCoolModule', '1.0', 'android');
    tiapp.write();

    Print the tiapp.xml from the tiapp object

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    console.log(tiapp.doc.toString());

    API

    load(file)

    Load a tiapp.xml file and return a Tiapp object. If file is undefined, find() will attempt to locate a tiapp.xml file.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');

    parse(xmlString, filename)

    Parse an xml string as a tiapp.xml document and return a Tiapp object. This is used by load() and generally isn't used directly. filename is optional, and is used only as a default value if you attempt to write() later.

    var tiapp = require('@titanium/tiapp-xml').parse('<ti:app><!-- the rest of the tiapp.xml --></ti:app>');

    find()

    Find a tiapp.xml file and return its file path. It will start by searching the current working directory for a tiapp.xml file. If it doesn't find it, it will continue to move up the folder hierarchy attempting to find tiapp.xml files. If it never finds a tiapp.xml, it returns null.

    var pathToTiappXml = require('@titanium/tiapp-xml').find();

    toString()

    Return the string representation of the tiapp.xml file.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    console.log(tiapp.toString());

    write([file])

    Write the current Tiapp object out as a tiapp.xml file to file. If file is undefined, it will use the file supplied in the inital load() or parse() call. If it still can't find a file, an exception with be thrown.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
     
    // disable analytics
    tiapp.analytics = false;
     
    // write out the changes to "./tiapp.xml"
    tiapp.write();
     
    // or write out to an explicit location
    tiapp.write('/path/to/tiapp.xml');

    top-level elements

    Get and set top-level tiapp.xml elements directly as properties. These properties can be referenced in dash form or camel case. For example, to work with the sdk-version you can use either tiapp['sdk-version'] or tiapp.sdkVersion.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
     
    // prints the name and guid of the app
    console.log(tiapp.name + '' + tiapp.guid);
     
    // disable analytics
    tiapp.analytics = false;
     
    // change the sdk version
    tiapp['sdk-version'] = '3.2.2.GA';

    getDeploymentTarget(platform)

    Return a boolean indicating whether or not the given platform is enabled. If no platform is given, getDeploymentTargets is called instead.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    console.log(tiapp.getDeploymentTarget('android'));

    The previous code would print true if the deployment-targets section of your tiapp.xml looked something like this:

    <deployment-targets>
        <target device="android">true</target>
    </deployment-targets>

    getDeploymentTargets()

    Return an object representation of all the deployment target elements.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    console.log(tiapp.getDeploymentTargets());

    The previous code executed against a tiapp.xml that had everything but Tizen enabled would print this:

    {
        android: true,
        blackberry: true,
        ipad: true,
        iphone: true,
        mobileweb: true,
        tizen: false
    }

    setDeploymentTarget(platform, value)

    Enable or disable a platform. If platform is an object, setDeploymentTargets is called instead.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    tiapp.setDeploymentTarget('android', false);
    tiapp.write();

    The previous code would write a deployment-targets entry something like this:

    <deployment-targets>
        <target device="android">false</target>
    </deployment-targets>

    setDeploymentTargets(obj)

    Enabled or disable all platforms at once. obj is an object representation of all deployment targets.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
     
    // get existing list of deployment targets
    var targets = tiapp.getDeploymentTarget();
     
    // disable tizen and blackberry
    targets.blackberry = false;
    targets.tizen = false;
    tiapp.setDeploymentTargets(targets);
     
    // or use an object literal to do the same without the getDeploymentTargets() call
    tiapp.setDeploymentTargets({
        android: true,
        blackberry: false,
        ipad: true,
        iphone: true,
        mobileweb: true,
        tizen: false
    });
     
    tiapp.write();

    getProperty(name)

    Get a tiapp.xml application property value.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    console.log(tiapp.getProperty('ti.ui.defaultunit')); // prints "system"

    setProperty(name, [value], [type])

    Set a tiapp.xml application property.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
     
    // with just a value
    tiapp.setProperty('ti.ui.defaultunit', 'dp');
     
    // or with a value and type
    tiapp.setProperty('ti.ui.defaultunit', 'dp', 'string');
     
    tiapp.write();

    removeProperty(name)

    Remove an application property from the tiapp.xml.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    tiapp.removeProperty('ti.ui.defaultunit');
    tiapp.write();

    getModules()

    Get an array of objects representing modules listed in the tiapp.xml.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    var modules = tiapp.getModules();
     
    // iterate through a list of modules from the tiapp.xml
    modules.forEach(function(mod) {
        // read access to properties on module object
        console.log('id=%s,version=%s,platform=%s',
            mod.id, mod.version || '<no version>', mod.platform || '<no platform>');
    });

    setModule(id, [version], [platform])

    Add or update a module in the tiapp.xml.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
     
    // Add the ti.cloud module
    tiapp.setModule('ti.cloud');
     
    // Set the version of ti.cloud to 2.0
    tiapp.setModule('ti.cloud', '2.0');
     
    // Add a platform-specific module
    tiapp.setModule('ti.cloud', '1.0', 'android');
     
    // add with object for attributes
    tiapp.setModule('some.module', {
        platform: 'android',
        version: '3.3'
    });
     
    // Add one more module, no additional details
    tiapp.setModule('com.tonylukasavage.nothing');
     
    tiapp.write();

    The resulting tiapp.xml <modules> section would look like this:

    <modules>
        <module version="2.0">ti.cloud</module>
        <module version="1.0" platform="android">ti.cloud</module>
        <module version="3.3" platform="android">some.module</module>
        <module>com.tonylukasavage.nothing</module>
    </modules>

    removeModule(id, [platform])

    Remove a module from the tiapp.xml.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
     
    // remove ti.cloud module that is _not_ platform-specific
    tiapp.removeModule('ti.cloud');
     
    // remove a platform-specific ti.cloud entry
    tiapp.removeModule('ti.cloud', 'android');
     
    tiapp.write();

    getPlugins()

    Get an array of objects representing plugins listed in the tiapp.xml.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    var plugins = tiapp.getPlugins();
     
    // iterate through a list of plugins from the tiapp.xml
    plugins.forEach(function(plugin) {
        // read access to properties on plugin object
        console.log('id=%s,version=%s', plugin.id, plugin.version || '<no version>');
    });

    setPlugin(id, [version])

    Add or update a plugin in the tiapp.xml.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
     
    // Add the ti.alloy plugin
    tiapp.setPlugin('ti.alloy');
     
    // Set the version of ti.alloy to 2.0
    tiapp.setModule('ti.alloy', '2.0');
     
    tiapp.write();

    The resulting tiapp.xml <plugins> section would look like this:

    <plugins>
        <plugin version="2.0">ti.alloy</plugin>
    </plugins>

    removePlugin(id)

    Remove a plugin from the tiapp.xml.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    tiapp.removePlugin('ti.alloy');
    tiapp.write();

    doc

    A direct reference to the underlying XML Document object as supplied by xmldom. You will not need to use this in most cases and should use the tiapp.xml module APIs instead.

    var tiapp = require('@titanium/tiapp-xml').load('./tiapp.xml');
    console.log(tiapp.doc.documentElement.nodeName); // prints "ti:app"

    Todo

    • Platform-specific tiapp.xml sections

    📚Learn More

    📣 Feedback

    Have an idea or a comment? Join in the conversation here!

    Install

    npm i @titanium/tiapp-xml

    DownloadsWeekly Downloads

    23

    Version

    1.0.3

    License

    MIT

    Unpacked Size

    37.1 kB

    Total Files

    14

    Last publish

    Collaborators

    • avatar