Overview

In previous versions of FarCry, config structures were defined by setting up structs in /system/dmConfig and stored as WDDX in the config table. In Fortress (v5.0+), config definition and storage has been refactored to use a content types and leverage the non-persistent Form Components and the WDDX formtool for capturing config data.

Configs can be included in the project and also within Plugins. Configs behave similarly to content types with respect to overriding their behaviour. Configs leverage the FarCry Form Components which are very like non-persistent content types. This is extremely useful as it means we can build config editing interfaces using almost all the features of the FarCry Formtools engine.

Implementation

farConfig (the content type)

The farConfig content type stores the config key (i.e. application.config.key) and the WDDX of the form properties. On application start these values are loaded in to the application scope. If a given config form hasn't been instantiated (i.e. the key can't be found in the database) a config item is automatically created with the default values.

The config key is dynamically determined based on the filename of the config component, minus the config prefix. For example, a config component called confingGoogleMaps.cfc would have a key of "GoogleMaps".

You can safely delete config items from the webtop. When the application is re-initialised missing configs will be recreated with the default values nominated in the component cfproperty metadata.

form components

To add a new config to the application:

Create a form component prefixed with "config"
Add config variables to the form as properties
Add the attribute key="yourconfigkey" to the form component
Update the app (?updateapp=1)

Adding New Properties

If the config breaks when you add/remove/change a property, you may need to delete the config and have it recreated from defaults. This can be a pain as you have to re-enter any values that vary from the defaults.

Example of custom plugin config file


<!--- custom plugin config file, in this case placed in
farcry/plugins/wsoFarcryTickets/packages/forms/configwsoFarcryTickets.cfc --->

<cfcomponent name="wsoFarcryTicketsconfig"
extends="farcry.core.packages.forms.forms"
output="false"
displayname="Tickets"
hint="This utility allows you to set the config settings for wsoFarcryTickets."
bObjectBroker="true"
lObjectBrokerWebskins="display*"
key="wsoFarcryTickets">

<cfproperty ftSeq="1"
ftFieldset="Ticket Server Details"
name="ticketfrom"
type="email"
fttype="email"
default=""
ftLabel="Ticket From E-mail"
hint="Ticket From E-mail."
ftValidation="required,email" />

<cfproperty ftSeq="2"
ftFieldset="Ticket Server Details"
name="ticketserver"
type="string"
fttype="string"
default=""
ftLabel="Ticket Server"
hint="Ticket Server."
ftValidation="required" />

<cfproperty ftSeq="3"
ftFieldset="Ticket Server Details"
name="ticketservercfmail"
type="integer"
fttype="string"
ftLabel="Ticket Server Cfmail port"
hint="Ticket Server Cfmail port."
ftValidation="validate-number,integer"
ftDefault="25" />

</cfcomponent>

Example of retrieving and using values from above set config data


<!--- retrieving and using values from above set config data --->

<cfmail type="html"
from="#application.config.wsoFarcryTickets.ticketfrom#"
to="someone"
subject="some subject"
server="#application.config.wsoFarcryTickets.ticketserver#"
port="#application.config.wsoFarcryTickets.ticketservercfmail#"
>
some message
</cfmail>

Deprecated config

The following configs are included FarCry by default:

General
Plugins
TinyMCE (only for backwards compatibility)

All others are deprecated and aren't included in a new install. Deprecated configs are kept purely for backward compatibility in the assumption that someone, somewhere might be referring to them. If you are not one of these rare people, we recommend deleting the obsolete configs through the webtop admin.

Upgrading from Earlier Versions of FarCry

During an upgrade all existing configs are migrated automatically, including deprecated configs. Supported configs are converted to use the new form components and are editable. Deprecated and custom configs are stored as vanilla WDDX structs and are not editable.

The update does not remove or change the deprecated config table. You can empty the farConfig table and re-run the update to migrate the configs as many times as necessary.

A form component can be created for unsupported configs. If this form is in place when you attempt to edit the config, a full form will be provided for editing.