Config (class)

Categories:Framework

Overview

Summary

The Config class is an object oriented wrapper for easily saving and loading settings.

Contents

Concept

Overview

The Config class provides a simple but powerful settings API, that:

  • Loads and saves settings from disk as XML
  • Supports the xJSFL file-finding mechanism, so users can override module and core settings
  • Automatically saves the internal XML to disk when adding or updating values, via set()
  • Automatically parses values to the correct datatype, via get()

Automatically-found config items

The first thing to know about Config, is that it's been designed to work with xJSFL's cascading file structure, so that users can override module or core settings. As such:

  1. Config instances are usually instantiated with just the filename of the related file you want to find
  2. Config files should have unique names, so not toclash with other files in the system

The following example automatically finds and loads the config file test.xml:

var config = new Config('test'); // .xml is added automatically
trace(config);
[object Config path="F:/Users/Dave Stewart/AppData/Local/Adobe/Flash CS4/en/Configuration/xJSFL/config/test.xml" rootnodes=0 exists=true]

What happens here is that xJSFL looks in each of the search paths in turn to find the file...

  1. /Users/<user>/AppData/Local/Adobe/Flash CS4/en/Configuration/xJSFL/config/
  2. /xJSFL/user/config/
  3. /xJSFL/modules/<module 1>/config/
  4. /xJSFL/modules/<module 2>/config/
  5. /xJSFL/modules/<module 3, etc>/config/
  6. /xJSFL/core/config/

...and returns the first found file matching the supplied config name. In the case above, the user had already created a file in the Flash/xJSFL/config/ folder, so the file was found and returned.

If an existing config file is NOT found, Config defaults to xJSFL/user/config/ but does not yet create the file:

[object Config path="E:/Projects/xJSFL/user/config/test.xml" rootnodes=0 exists=false]

Absolutely-pathed config items

If you wish to create a config file that doesn't use the cascading file system, simply pass in an absolute path to the constructor:

var config = new Config('c:/temp/test.xml');
trace(config);
[object Config path="c:/temp/test.xml" rootnodes=0 exists=false]

Usage

Setting (including saving) config values is as simple as one line of code:

var config = new Config('test');
config.set('value', 5);

trace('The new value is: ' + config.get('value'));
trace('The XML is:\n' + config.toXMLString());
The new value is: 5
The XML is:
<config>
	<value>5</value>
</config>

Getting values, is also a single line, and simple values (i.e. not complex XML) are parsed into their correct data types:

var config = new Config('test').clear();
config.set('value', 5);
inspect([config.xml.value, config.get('value')]);
Inspect: Number (depth:4, objects:0, values:0, time:0.0 seconds)
--------------------------------------------------------------------------------
5

API

Config(configPath, xml)

Config class, loads and saves XML from the config folders

Parameters:

  • configPath String The absolute or relative path to the config file
  • xml XML An XML object with which to populate the Config instance

Creating a new Config instance will do one of 2 things:

  1. If the associated XML file doesn't exist, the Config instance will be created, without yet creating an XML file
  2. If the associated XML file does exist, the file will be loaded and the data saved in the file will be available to use straight away

Note that passing a relative file path will attempt to find the file in the cascading file structure, defaulting to user/config/

The following example creates a new empty config file in the user folder:

var config = new Config('test');
trace(config);
[object Config path="E:/Projects/xJSFL/user/config/test.xml" rootnodes=0 exists=false]

Note that you can save config data to subfolders by specifying a path:

var config = new Config('settings/test');

There is no need to specify an .xml extension as Config files are XML by default, but if you do so, it will be ignored.

Properties

uri

The uri of the config instance

  • Type: Object
  • Access: Read

 

xml

The raw XML in the config object

  • Type: XML
  • Access: Read/write

autosave

A flag to save data as soon as it is set()

  • Type: Boolean
  • Access: Read/write

Data methods

set(path, value)

Sets data on the wrapped XML data

Parameters:

  • path String A dot-notation path to a node or attribute
  • value Value Any value that can be converted to a string

Returns:

  •   Config The current Config node

The following example sets various properties and attributes on a new Config instance:

var config = new Config('settings/test');
config
	.set('app', 'xJSFL')                // root-level node (string)
	.set('@id', 1)                      // root-level attribute (number)
	.set('long.path.to.value', 'Hello') // compound path

trace(config.toXMLString());
<settings id="1">
  <app>xJSFL</app>
  <long>
    <path>
      <to>
        <value>Hello</value>
      </to>
    </path>
  </long>
</settings>

The following example attempts to set various datatypes:

var config = new Config('settings/test');
config
    .clear()
    .set('string', '"Hello"')
    .set('illegalstring', '<Hello>')
    .set('number', 1)
    .set('boolean', true)
    .set('xml', <name>Dave</name>)
    .set('xmllist', new XMLList('<icon id="1" /><icon id="2" /><icon id="3" />'))
    .set('date', new Date())
    .set('class', new Config('settings/config'))
    .set('array', [1,2,3,4,5]);

trace(config.toString(true));
<settings>
    <string>"Hello"</string>
    <illegalstring>&lt;Hello&gt;</illegalstring>
    <number>1</number>
    <boolean>true</boolean>
    <xml>
        <name>Dave</name>
    </xml>
    <xmllist>
        <icon id="1"/>
        <icon id="2"/>
        <icon id="3"/>
    </xmllist>
    <date>Thu Jul 21 2011 17:43:05 GMT+0100 (GMT Daylight Time)</date>
    <class>[object Config path="xJSFL/user/config/settings/config.xml" nodes=0]</class>
    <array>1,2,3,4,5</array>
</settings>

get(path)

Gets the value of the specified node path

Parameters:

  • path String A dot-notation String path to a node or attribute
  • parse Boolean A Boolean flag indicating that you want to parse the value to the currect datatype
  • test Boolean A Boolean flag to test the path exists, but trap and return an Error object if not

Returns:

  •   value The value of the node or attribute

The following example gets a node attribute:

var config = new Config('settings/test');
config
	.clear()
	.set('some.setting.@id', 'Hello')
	
trace(config.toXMLString());
trace(config.get('some.setting.@id'));
<settings>
  <some>
    <setting id="Hello"/>
  </some>
</settings>
Hello

The following example enters some values into the Config instance, then extracts them into a table, so you can see how the data types are parsed for simple node types:

// create a new config, and clear it
	var config = new Config('test').clear();
	
// set some values
	config.set('@attr', 5);
	config.set('a.b', 'hello');
	config.set('c', value);

// trace the XML
	XML.prettyPrinting = true;
	trace(config.toXMLString());
	
// extract the values into a table	
	var data = [];
	var nodes = ['a', 'a.b', 'c', '@attr', 'somenode'];
	XML.prettyPrinting = false;
	for each(var node in nodes)
	{
		var value	= config.get(node);
		data.push({node:node, value:value, type:typeof value});
	}
	XML.prettyPrinting = true;
	
// trace values
	Table.print(data);
<config attr="5">
	<a>
		<b>hello</b>
	</a>
	<c attr="1">value</c>
</config>
+----------+---------------------+-----------+
| node     | value               | type      |
+----------+---------------------+-----------+
| a        | <a><b>hello</b></a> | xml       |
| a.b      | hello               | string    |
| c        | value               | string    |
| @attr    | 5                   | number    |
| somenode | undefined           | undefined |
+----------+---------------------+-----------+

remove(path)

Removes the node from the Config instance's XML

Parameters:

  • path String An xJSFL XML notation path to a node or attribute

Returns:

  •   Config The current Config instance

The following example adds a new value, then removes one of its parent nodes:

var config = new Config('test').clear();
config.set('a.b.c', 5);
config.remove('a.b');
trace(config.toXMLString());	
<config>
	<a/>
</config>	

clear()

Clears all nodes inside the internal XML

Returns:

  •   Config The current Config node

The following example clears the current config instance:

var config = new Config('test').clear();
config.set('value', 5);
config.clear();
trace(config.toXMLString());
<config />

File methods

load()

Loads the XML config from disk

Returns:

  •   Config The current Config node

You normally won't need to call this method, as a Config instance's XML is loaded automatically from disk when first instantiated, however, the following example loads (or reloads) the related XML file:

var config = new Config('settings/test');
// perhaps something happened here, like an external modification to config
config.load();
[object Config path="E:/Projects/xJSFL/user/config/settings/test.xml" rootnodes=5 exists=true]

save()

Saves the internal XML to disk

Returns:

  •   Config The current Config node

The following example saves the current config instance:

var config = new Config('test');
config.save();
trace(config);
[object Config path="E:/Projects/xJSFL/user/config/test.xml" rootnodes=0 exists=true]

removeFile()

Removes the config file from disk

Returns:

  •   Config The current Config node

The following example removes the config item from disk:

var config = new Config('test');
config.set('value', 5);
trace(config);
config.removeFile();
trace(config);
[object Config path="E:/Projects/xJSFL/user/config/test.xml" rootnodes=1 exists=true]
[object Config path="E:/Projects/xJSFL/user/config/test.xml" rootnodes=1 exists=false]	

Utility methods

toString()

Returns a String representation of the Config instance

Returns:

  •   String The String summary of the Config instance

The following example traces a new, empty Config instance:

trace(new Config('test'));
[object Config path="E:/Projects/xJSFL/user/config/test.xml" rootnodes=0 exists=false]

toXMLString()

Returns the pretty-printed XML contents

Returns:

  •   String The pretty-printed XML contents

The following example traces a new, empty Config instance as an XML String:

trace(new Config('test').toXMLString());
<config />

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>