Let’s have a closer look at a Railo extension. An extension is delivered as a zip file, which next to the application itself, must contain the two following files:

  • install.cfc - The install.cfc contains the installation code and methods that can be used in order to create dynamic content of the installation form.
  • config.xml - The config.xml contains a definition of form entries of the installation form.

install.cfc

The install.cfc is the main file for the installation. Next to the code that is used for the installation process itself it contains methods that can be used together with the config.xml in order to dynamically populate the form items of the install form or to dynamically generate form items as well. The main task of the component install.cfc is to install, uninstall or update an extension. The installation of an extension is „application based“, which means that the installation is not done by Railo but by the extension itself. Railo just tells the extension to install itself and passes the configuration data to it. Therefore the install.cfc is the communication interface between Railo and the extension. This interface looks like follows:

Public methods of install.cfc

Method Description
validate(struct: error, string: path, struct: config, numeric: step): void The method validate is called after a user has submitted the installation form. If the installation form consists out of several steps (wizard), the validate method is called after each step. Validate will check the data. In case an entry is not valid or perhaps missing, a corresponding error can be thrown. By passing the argument error the extension notifies Railo about the errors of the validation. The other arguments help the method to validate the data. More about these arguments further below.
install(struct: error, string: path, struct:config): string:message The method install is called by Railo after the last step of the form has been submitted and the validate method has been successfully executed. The method is responsible for the installation of the extension by using the data of the passed arguments (more on these arguments further below). How this method executes its task is up to the method itself.
update(struct: error, string: path, struct: config, struct: previousConfig): string: message The method update is called by Railo after the last step of the form has been submitted and the validate method has been successfully executed. The method is responsible for updating an extension by using the data of the passed arguments (more on these arguments further below). How this method executes its task is up to the method itself.
uninstall(string: path, struct:formerConfig): string:message The method uninstall is called by Railo when a user has clicked on the uninstall button. The method is responsible for uninstalling an extension by using the data of the passed arguments (more on these arguments further below).

Arguments:

Argument Description
struct: error The argument error contains a struct that gathers all occurred errors. In addition to this struct a regular exception can be thrown as well. The structure contains the following keys:
  • fields - a struct that contains all erroneous fieldnames as keys. The value is the error message itself.
  • common - common error message, that is not related to a field
string: path The argument path contains the path to the root directory of the extension and therefore allows you to access all the files of the extension zip.
struct: config The config struct contains all the data of the form, that has been entered by the user. It is structured as follows:
  • mixed - contains all values of the input fields, from all steps merged into a struct. Caution: Data is overwritten, in case two steps contain a field with the same name
  • step - contains an array of all the steps. An array element contains all input field values of the corresponding step
Example: Let's assume we have a form that consists out of two steps. The first step defines the field s1f1 and the second the field s2f1. If you dump the config argument, you receive the following output: Installation steps
struct: previousConfig The argument previousConfig is analog to config. It just contains the data of the previous installation. In case of an update this might be important in order to have information about already entered Data.
numeric: step This argument contains the current step of the form. This helps defining the data that needs to be validated.

Return Value

Argument Description
message Message is a text that is displayed after the successfull installation/update.

config.xml

The config.xml describes the data entry forms for the installation process. It is build as a XML structure which can contain the following data tags:

<config>
? <step>
? <group>
? <item>
? <option>

Above you can see the hierarchy structure of the possible tags. The root tag of the XML is named <config>. More on the <config> tag further below.

step

Hierarchy

<config>
? <step>

A form can consist out of several steps, like a wizard. This is why the <config> tag contains any number of <step> tags. config.xml:

<config>
<step label="First Step" description="This is the first step"/>
<step label="Second Step" description="This is the second step"/>
</config>

Each step describes a page of the installation form. Above the config.xml defines two pages that provide a label and description of the page with the corresponding attributes label and description.

group

Hierarchy

<config>
? <step>
? <group>

Next to pages, the <group> tag can group several form elements on a page. config.xml:

<config>
<step label="First Step" description="This is the first step">
<group label="First Group" description="This is the first group"/>
<group label="Second Group" description="This is the second group"/>
</step>
</config>

The group item itself allows the attributes label and description for detailed information.

item

Hierarchy

<config>
? <step>
? <group>
? <item>

The single fields are described with the tag <item>. config.xml:

<config>
<step label="First Step" description="This is the first step">
<group label="First Group" description="This is the first group">
<item label="First Item" description="This is the first item"
name="firstItem" type="text">
First Item Value
</item>
</group>
</step>
</config>

Next to the usual attributes label and description, the tag <item> allows the attribute name for the name of the form field and type for the type of the item. A value as the default value can be used as well.

option

Hierarchy

<config>
? <step>
? <group>
? <item>
? <option>

An item might contain a sub element named option which contains the different options for a certain item type (like select). config.xml:

<config>
<step label="First Step" description="This is the first step">
<group label="First Group" description="This is the first group">
<item label="First Item" description="This is the first item"
name="firstItem" type="text">
First Item Value
</item>
<item label="Second Item" description="This is the second item"
name="secondItem" type="radio">
<option selected="true" label="First Option"
description="This is the first option">
first
</option>
<option label="Second Option"
description="This is the second option">
second
</option>
</item>
</group>
</step>
</config>

Inside the second item tag in the above config.xml the <option> has been used. It can be used when item is of type radio, checkbox or select. Of course this tag allows the attributes label and description as well. In addition next to the value the attribute selected can be used in order to mark the selected option. The above config.xml would be generating the form below:
Generated form

dynamic content

The above examples show how to build a static form for the extension. Now how do we fill the form with dynamic content or even dynamic form fields?

evaluate

The easiest way to use dynamic content is to use evaluate functionality:

...
<item label="Root" name="root" type="text">
evaluate:expandPath('{web-root-directory}')
</item>
...

Everything you can do in Railo with the Build In Function evaluate() can be used in the config.xml. So the above code would return a string which could be displayed in Railo like this:

<cfdump var="#evaluate("expandPath('{web-root-directory}')")#">