This page displays the "Global Config" demo form. You can create a GlobalConfig struct in CFML, or if you are utilizing a DI framework such as ColdSpring, you can create your config inside of it. (See the code page for an example.)
You can use keys matching any valid attribute on the form tag. Then simply provide your config struct to the form via the attributeCollection, as shown below.
<uform:form attributeCollection="#cfUniFormConfig#">
By utilizing the attributeCollection, we can take advantage of ColdFusion's handling of attributeCollection keys vs. explicitly declared keys. What do I mean by that? Well, if you have a key in the struct that is passed via attributeCollection but also explicitly provide that same key, ColdFusion will automatically use the value provided by the explicit key instead. This allows us to provide a global config, and yet still override it at the form level!
We demonstrate this in the form on this page by explicitly providing the 'dateSetup' key, even though it exists in the attributeCollection. Note that the cfUniFormConfig struct's dateSetup sets the yearRange to year(now()) [2010] through year(now()+2) [2012].
cfUniFormConfig.dateSetup['yearRange'] = "'#year(now())#:#year(dateAdd('yyyy', 1, now()))#'";
However, since we've explicitly provided a range of 2000-2005 via the 'dateSetup' key...
<uform:form attributeCollection="#cfUniFormConfig#" dateSetup="{yearRange:'2000:2005'}">
...ColdFusion gives precedence to the explicit declaration, and the form contains the latter setup. Thank you, CF!!
A few important notes:
For a full list of valid keys that you can pass to the attributeCollection, see the comments at the top of the form.cfm template (/tags/forms/cfUniForm/form.cfm).
One of the most common configuration changes made is to provide alternate paths to the various CSS and JavaScript files. These can be provided via the 'pathConfig' key, which must be a struct. Valid keys for the 'pathConfig' struct are as follows (all keys are optional):
NOTE: Prior to cfUniForm v4.0 the key name for the 'pathConfig' struct was known as 'config'. The 'config' key has been deprecated in v4.0, and **will** be removed in a future version. Please be sure to do a find/replace on all of your forms and replace calls to 'config' with calls to 'pathConfig'.
JavaScript is cAsE-sEnSiTiVe. Therefore, when creating config keys for your plugin setups, you *must* utilize array notation. If you don't, ColdFusion will automatically render the key in UPPERCASE. So, instead of
<cfset myStruct.dateSetup.yearRange = "'2008:2040'" />
you would write it as
<cfset myStruct.dateSetup['yearRange'] = "'2008:2040'" />
Certain plugin setup rules require single quotes (e.g. strings). Others require no quotes (e.g. true|false). The cfUniForm tags assume that you know what you're doing and will output exactly what you've written. If the JavaScript breaks, it's likely because of quotes not being where they should be, or vice-versa.
As noted above, even if you've supplied plugin setup rules in your GlobalConfig struct, you can still override them on an individual form by utilizing the attributes provided on the form tag (e.g. @dateSetup or @timeSetup). However, it is important to understand that the explicit key overrides, or supercedes, the attributeCollection key. It *does not* merge the two.
So if you have a configuration setting in your global config struct (provided to attributeCollection) but do not have that same key in the explicit config struct (provided to 'dateSetup'), it will be ignored. No need to fret though, it is quite easy to have the best of both worlds. How? Use structAppend() to merge your two structs into one and don't bother with the explicit key!
<cfscript>
// declare your local (explicit) date setup
myLocalDateSetup = structNew();
myLocalDateSetup['yearRange'] = "'2000:2005'";
// next, create a duplicate of our globals struct to hold the merged configs
myMergedConfig = duplicate(cfUniFormConfig);
/*
* IMPORTANT! If you do not use duplicate() above, you will overwrite the
* 'dateSetup' portion of your cfUniFormConfig struct when you do the
* structAppend() on the next line!
*/
// merge our local date setup into the date setup of our merged struct (overwrite=true)
structAppend(myMergedConfig.dateSetup,myLocalDateSetup,true);
</cfscript>
<--- use our merged config struct instead of our global one (don't pass the explicit 'dateSetup') --->
<uform:form attributeCollection="#myMergedConfig#">
In our demo form here, we're skipping the merging. As a result you will see that because we did not declare the 'changeYear' setting in our 'dateSetup' config string, the calendars will allow you to change years, even though our global config struct has it set to false. Give the merge a try and watch that option disappear! :-)
You may also override plugin setups (e.g. date/time configuration) on an individual field by utilizing the 'pluginSetup' attribute on the field tag. When utilizing the 'pluginSetup' attribute for date or time configuration, the settings you provide are automatically merged (by the plugin) with any global settings provided.
View the code used to generate the form.