Configuring ColdExt in Application.cfc

From ColdExt

Jump to: navigation, search

Contents

The Application scope

One of the requirements of ColdExt is that the Application scope must be available for storing ColdExt configuration information. ColdExt can insert the default config into the Application scope automatically (as long as an Application Name has been assigned in Application.cfc or Application.cfm), but if you desire a slightly different setup for your file paths or other ColdExt configuration options then you can set those items in your Application.cfc/cfm file using the <ext:config> tag.

Sample Application.cfc

Below is a sample Application.cfc which you could use as a starting point: 

<cfcomponent output="false">
 
	<cfset this.Name = "myColdExtApplication">
 
	<cffunction name="onApplicationStart" returntype="void">
		<cfset ColdExtConfig()>
	</cffunction>
 
	<cffunction name="onRequestStart" returntype="void" output="false">
		<cfargument name="page" type="string" required="true">
		<cfif StructKeyExists(url, "initColdExt")>
			<cfset ColdExtConfig()>
		</cfif>
	</cffunction>
 
	<cffunction name="ColdExtConfig">
		<cfimport prefix="ext" taglib="/coldext">
		<ext:config
			<!--- application wide ColdExt config attributes go here --->
		/>
	</cffunction>
 
</cfcomponent>

Setting up a config function

The ColdExtConfig function above provides a starting point for configuring ColdExt. In its current state it is a vanilla configuration that will simply use ColdExt's built-in defaults. Configuration options can be supplied as attributes to the <ext:config> tag. The actual configuration options will be discussed below.

Important Note: you should only use the <ext:config> tag in the Application.cfc/cfm as it sets/resets the entire ColdExt config - you shouldn't use this tag in a display page (overriding options for individual requests can be handled a different way, using the <ext:init> tag!).

The ColdExtConfig function can then be called from onApplicationStart so that ColdExt is set up once, or in onRequestStart if ColdExt needs to be reconfigured after the application has started.

Reloading the config

The cfif block above (containing the StructKeyExists(url, "initColdExt") condition) provides a method of reloading the config after changes have been made, by simply adding ?initColdExt to any URL in your application. The ColdExtConfig function will then be executed again and the new configuration will take effect.

Available configuration options

There are a number of ColdExt configuration options which can be passed to the <ext:config> tag as attribute/value pairs.

AttributeDefault SettingDescription
js/extPath to the Ext JavaScript resources (ext-all.js, ext-base.js, ext-all-debug.js)
css/ext/cssPath to the Ext CSS resources (ext-all.css, xtheme-gray.css, other theme CSS files)
images/ext/imagesPath to the Ext image resources (contains default and gray folders, and other theme folders)
blankImageURL/ext/images/default/s.gifPath to the blank image (Ext requires this to be a path to a valid 1x1 pixel transparent gif)
theme[empty string]The file name of the theme to use, minus the .css file extension (e.g. xtheme-gray or leave blank for default theme)

Example Usage

Custom Ext paths

<ext:config
	js="/custom/path/ext"
	css="/custom/path/ext/css"
	images="/custom/path/ext/images"
	blankImageURL="/custom/path/ext/images/default/s.gif"
/>

Note: Just a heads up, I am considering making a change to the paths so that a base Ext path can be specified without the need to specify paths to css and images, assuming that the same directory structure is followed. If the directory structure is different then the css and images paths would be relative to the base path, which would break compatibility with the current (Beta 1) build. However, this would be noted as a breaking change in the release notes and should be trivial to correct.

Changing the Ext theme

<ext:config
	theme="xtheme-gray"
/>
Retrieved from "http://www.madfellas.com/wiki/index.php?title=Configuring_ColdExt_in_Application.cfc"