mxAjax = Coldfusion + Ajax => Prototype + Json

mxAjax Usage

Common Concepts

Base URL

The baseUrl property is required of every tag and is used by the tag to make a request to the serverside. The responding resource (e.g., CFM, html etc.) is responsible for returning the response in the appropriate format (plain text, HTML, XML, JSON etc.)

Parameters

Overview

Each tag has a common parameters property, composed of name-value pairs that eventually get passed to the URL specified in the baseUrl property. You may specify multiple name-value pairs by separating them with commas. Within each pair, you can also indicate that you want a certain form field value to be inserted at the time the request is made by surrounding the value with curly brackets.

Let's look at an example. Assume we want to pass two parameters on the URL, one indicating the make of our automobile and another that is a plain text constant. The value of the make parameter will be inserted at request time. In this case, we assume the makeId form field contains a value of "Honda".

parameters="make={makeId},q=someConstantValue"

...will be replaced at request time with...

parameters="make=Honda,q=someConstantValue"

Post-functions and Error Functions

If you've wondered how to either chain AJAX tags together--by having one execute after another has completed--then you'll like this. The postFunction attribute allows you do just that. This attribute expects a JavaScript function name to be passed. The AJAX JavaScript will execute the function you define after it has finished its work.

In addition to post-functions, you may also define functions to be executed when the AJAX request could not be completed (e.g., invalid URL, server exception). You simply enter the name of the user-defined JavaScript function into the optional errorFunction tag attribute.

mxAutocomplete

The autocomplete tag allows one to retrieve a list of probable values from CF and display them in a dropdown beneath an HTML text input field. The user may then use the cursor and ENTER keys or the mouse to make a selection from that list of labels, which is then populated into the text field. This tag also allows for a second field to be populated with the value or ID of the item in the dropdown.

<form>
	State : <input id="searchCharacter" name="searchCharacter" type="text" size="40" />
	<input id="statecode" name="statecode" type="text" size="2" />
</form>

new mxAjax.Autocomplete({
	indicator: "indicator",
	minimumCharacters: "1",
	target: "statecode",
	className: "autocomplete",
	paramArgs: new mxAjax.Param(url,{cffunction:"getStateList"}),
	parser: new mxAjax.CFQueryToJSKeyValueParser(),
	source: "searchCharacter"
});

Parameter	Description	Required
var	Name of the JavaScript object created	no
attachTo	Name of the JavaScript object to which autocompleter will attach. You must define 'var' for this to work.	no
baseUrl	URL of CF code that processes search and returns list of values used in autocomplete dropdown; expression language (EL) is supported for this field	yes
source	Text field where label of autocomplete selection will be populated; also the field in which the user types out the search string	yes
target	Text field where value of autocomplete selection will be populated; you may set this to the same value as the source field	yes
parameters	A comma-separated list of parameters to pass to the server-side CFM page or CFC	yes
className	CSS class name to apply to the popup autocomplete dropdown	yes
indicator	ID of indicator region that will show during Ajax request call	no
minimumCharacters	Minimum number of characters needed before autocomplete is executed	no
appendSeparator	The separator to use for the target field when values are appended [default=space]. If appendValue is not set or is set to "false", this parameter has no effect.	no
preFunction	Function to execute before Ajax is begun	no
postFunction	Function to execute after Ajax is finished, allowing for a chain of additional functions to execute	no
errorFunction	Function to execute if there is a server exception (non-200 HTTP response)	no
parser	The response parser to implement [default=CFArrayToJSKeyValueParser]	no

mxPortlet

The portlet tag simulates a a href="http://www.jcp.org/en/jsr/detail?id=168"JSR-168/a style portlet by allowing you to define a portion of the page that pulls content from another location using Ajax with or without a periodic refresh.

This tag expects an HTML response instead of XML and the AJAX function will not parse it as XML; it will simply insert the content of the response as is.

new mxAjax.Portlet({
	executeOnLoad: true,
	paramArgs: new mxAjax.Param(url + '?htmlResponse=true',{param:"code=honda", cffunction:"getContent"}),
	imageClose: "../core/images/close.png",
	imageRefresh: "../core/images/refresh.png",
	title: "Demo Portlet",
	classNamePrefix: "portlet",
	imageMaximize: "../core/images/maximize.png",
	imageMinimize: "../core/images/minimize.png",
	source: "portlet_1",
	refreshPeriod: "5"
});

Parameter	Description	Required
var	Name of the JavaScript object created	no
attachTo	Name of the JavaScript object to which portlet will attach. You must define 'var' for this to work.	no
baseUrl	URL of CF code that processes a simple command	yes
source	ID of the portlet	yes
parameters	A comma-separated list of parameters to pass to the CF code	no
classNamePrefix	CSS class name prefix to use for the portlet's 'Box', 'Tools', 'Refresh', 'Size', 'Close', 'Title', and 'Content' elements	yes
title	Title for portlet header	yes
imageClose	Image used for the close icon	no
imageMaximize	Image used for the maximize icon	no
imageMinimize	Image used for the minimize icon	no
imageRefresh	Image used for the refresh icon	no
refreshPeriod	The time (in seconds) the portlet waits before automatically refreshing its content. If no period is specified, the portlet will not refresh itself automatically, but must be commanded to do so by clicking the refresh image/link (if one is defined). Lastly, the refresh will not occur until after the first time the content is loaded, so if executeOnLoad is set to false, the refresh will not begin until you manually refresh the first time.	no
executeOnLoad	Indicates whether the portlet's content should be retrieved when the page loads [default=true]	no
expireDays	Number of days cookie should persist	no
expireHours	Number of hours cookie should persist	no
expireMinutes	Number of minutes cookie should persist	no
preFunction	Function to execute before Ajax is begun	no
postFunction	Function to execute after Ajax is finished, allowing for a chain of additional functions to execute	no
errorFunction	Function to execute if there is a server exception (non-200 HTTP response)	no

mxSelect

The select tag allows one to retrieve a list of values from a backend servlet (or other server-side control) and display them in another HTML select box.

<form>
    <table>
	<tr>
		<td>
			Select a phone brand :
		</td>
		<td>
			<select id="brand" name="brand">
				<option value="Nokia">Nokia</option>
				<option value="Motorolla">Motorolla</option>
				<option value="Samsung">Samsung</option>
			</select>
		</td>
	</tr>
	<tr>
		<td align="right">
			Select a phone model :
		</td>
		<td>
			<select name="model" id="model" style="vertical-align:top;"></select>
		</td>
	</tr>
    </table>
</form>

new mxAjax.Select({
	parser: new mxAjax.CFArrayToJSKeyValueParser(),
	executeOnLoad: true,
	target: "model", 
	paramArgs: new mxAjax.Param(url,{param:"brand={brand}", cffunction:"makelookup"}),
	source: "brand"
});

Parameter	Description	Required
var	Name of the JavaScript object created	no
attachTo	Name of the JavaScript object to which select will attach. You must define 'var' for this to work.	no
baseUrl	URL of CF code that processes a simple command	yes
source	The initial select field that will form the basis for the search via AJAX	yes
target	Select field where value of AJAX search will be populated	yes
parameters	A comma-separated list of parameters to pass to the CF code	no
eventType	Specifies the event type to attach to the source field(s)	no
executeOnLoad	Indicates whether the target select/dropdown should be populated when the object is initialized (this is essentially when the form loads) [default=false]	no
defaultOptions	A comma-seperated list of values of options to be marked as selected by default if they exist in the new set of options	no
preFunction	Function to execute before Ajax is begun	no
postFunction	Function to execute after Ajax is finished, allowing for a chain of additional functions to execute	no
errorFunction	Function to execute if there is a server exception (non-200 HTTP response)	no
parser	The response parser to implement [default=CFArrayToJSKeyValueParser]	no

mxTabPanel

Provides a tabbed page view of content from different resources

<div id="tabPanelWrapper">
	<div id="tabPanel" class="tabPanel">
<ul>
 <li><a href="javascript://" onclick="executeAjaxTab(this, 'code=ford'); return false;" 
	class="ajaxCurrentTab">Ford</a></li>
 <li><a href="javascript://" onclick="executeAjaxTab(this, 'code=honda'); return false;">Honda</a></li>
 <li><a href="javascript://" onclick="executeAjaxTab(this, 'code=mazda'); return false;">Mazda</a></li>
</ul>
	</div>
	<div id="tabContent" class="tabContent"></div>
	<p>Page loaded at: <cfoutput>#now()#</cfoutput></p>
</div>

function executeAjaxTab(elem, params) {
	var aj_tabPanel = new mxAjax.TabPanel({
	paramArgs: new mxAjax.Param(url + '?htmlResponse=true',{param:params, cffunction:"getContent"}),
	target: "tabContent",
	panelId: "tabPanel",
	source: elem,
	currentStyleClass: "ajaxCurrentTab"
	});
}

mxTabPanel

Parameter	Description	Required
var	Name of the JavaScript object created	no
attachTo	Name of the JavaScript object to which tabPanel will attach. You must define 'var' for this to work.	no
panelStyleId	ID of the tab panel	yes
contentStyleId	ID of the tab panel content	yes
panelStyleClass	CSS classname of the tab panel	no
contentStyleClass	CSS classname of the tab panel content	no
currentStyleClass	CSS classname to use for the active tab	yes
preFunction	Function to execute before Ajax is begun	no
postFunction	Function to execute after Ajax is finished, allowing for a chain of additional functions to execute	no
errorFunction	Function to execute if there is a server exception (non-200 HTTP response)	no
parser	The response parser to implement [default=CFArrayToJSKeyValueParser]	no

mxTablePanel - Individual Tab

Parameter	Description	Required
baseUrl	The URL to use for the AJAX action, which will return content for this tab	yes
caption	The caption for this tab	yes
defaultTab	Indicates whether this tab is the initial one loaded [true	false]
parameters	A comma-separated list of parameters to pass to the CF code	no

mxUpdateField

Builds the JavaScript required to update one or more form fields based on the value of another single field.

	
<select id="brand" name="brand">
	<option value="Nokia">Nokia</option>
	<option value="Motorolla">Motorolla</option>
</select>
Make : <input id="make" name="make" type="text" size="30" />
Model : <input id="model" name="model" type="text" size="30" />

new mxAjax.UpdateField({
	parser: new mxAjax.CFArrayToJSArray(),
	paramArgs: new mxAjax.Param(url,{param:"brand={brand}", cffunction:"makelookup"}),
	target: "make,model",
	source: "brand"
});

Parameter	Description	Required
var	Name of the JavaScript object created	no
attachTo	Name of the JavaScript object to which updateField will attach. You must define 'var' for this to work.	no
baseUrl	URL of CF code that processes a simple command	yes
source	The form field that will hold the parameter passed to the servlet	yes
target	A comma-delimited list of form field IDs that will be populated with results	yes
action	ID of form button or image tag that will fire the onclick event	yes
parameters	A comma-separated list of parameters to pass to the CF code	no
eventType	Specifies the event type to attach to the source field(s)	no
preFunction	Function to execute before Ajax is begun	no
postFunction	Function to execute after Ajax is finished, allowing for a chain of additional functions to execute	no
errorFunction	Function to execute if there is a server exception (non-200 HTTP response)	no
parser	The response parser to implement [default=CFArrayToJSKeyValueParser]	no

mxAjax

mxAjax Usage

Common Concepts

Base URL

Parameters

Overview

Post-functions and Error Functions

mxAutocomplete

mxPortlet

mxSelect

mxTabPanel

mxTabPanel

mxTablePanel - Individual Tab

mxUpdateField

mxDomInclude