Steven S. Ross

When it comes time to deploy your application it is often difficult to manage application variables that change per instance. SimpleConfig aim’s to reduce the pain in running different environments. It does this by reading two xml files and taking those variables and placing them into your application scope for you to reference by using the prefix: Application.Configuration anywhere in your application.

source files: click to download

Setup and Configuration

Ok so lets dig into the file structure. When you download the zip file you will find a few directories listed as such:

/simpleconfig/config_files


/simpleconfig/html

The “html” directory is where you want to point Apache/IIS as the web root of your application. All you need to do is add a mapping of “/config” and point it to wherever you want to put the “config_files” directory and you are ready to start tweaking your config files.

Ok so on to configuring this puppy. Point Apache/IIS to the extracted directory /simpleconfig/html as your web root (again you can skip that step for demonstration purposes and just drop the contents of the directory “simpleconfig” onto your existing web root).

Defining your environments

Now go take a look at the file: /simpleconfig/config_files/config-instances.xml: 



<configuration>

    <option>

        <description>Local Instance</description>

        <name><![CDATA[simpleconfig.local]]></name>

        <value><![CDATA[config-dev.xml]]></value>

    </option>

    <option>

        <description>Configuration Files that pertain to all instances</description>

        <name><![CDATA[BASE_CONFIGURATION_FILES]]></name>

        <value>

            <key>

                <name><![CDATA[Base Config File]]></name>

                <value><![CDATA[config-base.xml]]></value>

            </key>

        </value>

    </option>

</configuration>

As you can see there is just some xml in here that defines each environment that you will be running. When you want to add an environment you simply add another node with the appropriate details. So to edit this for your own local machine you probably want to change the node to the host name of your machine, because CGI can be mucked with too easily on the client side I opted to use the java way at getting the machine name, most likely you will just have to run the app and see the dump to get your machine’s name so you can put the appropriate name in the config-instances.xml file. Next after that is the config file that pertains to your local instance. In this case we have “config-dev.xml”.

The idea here is to use this configuration file to define any differences from your base-config for your application. So say you have an email address that you want to use in your application, you probably don’t want to use your production account info while you are developing locally. However you probably do want the same DSN name and that would be put in your config-base.xml and not overridden in your config-dev.xml.

You should also note that the first word in the description will be the name of that environment type. So if you put into the description “QA” the “CurrentMode” variable in the configuration would become “QA” instead of “Local”. This is useful when you have to add more environments that you didn’t account for initially.

Also, this gives you the ability to quickly switch and test configurations by simply changing the xml file that you are loading for that instance. So if you had a “config-qa.xml” you could easily test that configuration locally by specifying that xml file instead of the “config-dev.xml”

h2. Configuring each environment The config-base.xml file:

<configuration>
    <option>
        <description>Application Status Struct</description>
        <name><![CDATA[applicationStatus]]></name>
        <value>
            <key>
                <name><![CDATA[isAvailable]]></name>
                <value><![CDATA[true]]></value>
            </key>
            <key>
                <name><![CDATA[unAvailableMessageHeader]]></name>
                <value><![CDATA[Website Unavailable]]></value>
            </key>
            <key>
                <name><![CDATA[unAvailableMessageBody]]></name>

                <value><![CDATA[Application is temporarily unavailable.]]></value>
            </key>
        </value>
    </option>
    <option>
        <description>An application variable</description>
        <name><![CDATA[somevariable]]></name>
        <value><![CDATA[something you need in the app scope]]></value>
    </option>
    <option>
        <description>Some struct that you want in the app scope</description>
        <name><![CDATA[theStructName]]></name>
        <value>
            <key>
                <name><![CDATA[structkeyOne]]></name>
                <value><![CDATA[~now()]]></value>
            </key>
            <key>
                <name><![CDATA[structKeyTwo]]></name>
                <value><![CDATA[some string]]></value>
            </key>
            <key>
                <name><![CDATA[structKeyThree]]></name>
                <value><![CDATA[some other string]]></value>
            </key>
        </value>
    </option>
</configuration>

This file is a bit bigger and it contains some interesting stuff. Basically you can put pretty much anything into your application scope. You can even put calls to coldfusion functions in your xml that will be called when the xml is read and placed into your application scope. You can see a few lines up where there is the coldfusion function “now()” being called on “structKeyThree”. You tell SimpleConfig to evaluate the function by placing a tilde (~) before the function. I think the other huge advantage here is being able to define a struct that will go into your Application.Configuration object.

You can see a struct being defined in the applicationstatus node. You see that the first node contains a node then what will be created is a struct. The first node will be the struct name ie: Application.Configuration.MyStruct and then the additional nodes under the nodes will be the key in the struct and the will be the value for that key. This is much easier to see in action. So make a change to one of the struct keys or their values and you can see it work.

About the applicationstatus node

I built this node into the guts of the application. If for some reason you need to take your application offline (some back-end system is down perhaps). You can edit the applicationstatus node and set the isAvailable node to false and the Application.cfc will throw an exception (for every request) which you can then catch and display to your users on your own custom error page. Granted you don’t have to go this route but, it is there for you to use.

Reloading your configuration files

To reload the application you simply tack on a ?reload to the query string. Note that this only works when the application is not in production mode and also when trusted cache is off.

SimpleConfig.cfc

If you take a look at org/ross/SimpleConfig.cfc there are two places for you to add in your own methods that can be called when the application is starting up. The first place is the setup() method and the second is the start() method. The setup method is designed to be used when you need to call some other code before variables are placed into the Application scope and the start() method is designed to be used after those variables have been placed into the Application scope. Both of these methods are called each time the Application is reloaded (which you can see in the Application.cfc).

I hope this is enough to get you started. It really is a simple and elegant way to handle configuration variables. I will be adding additional text as I get time that will explain how you can add more configuration data into the application scope just by adding your own xml files and editing the config-instances.xml. Here is a hint: The SimpleConfig.cfc will keep loading any of the defined xml files in the BASE_CONFIGURATION_FILES node, just make sure you structure them exactly like the other config files.

This software is licensed under the CC-GNU GPL.