ColdFusion 9.0 Resources

cfsprydataset

Description

Creates a Spry XML or JSON data set from the results of a bind expression.

Syntax

<cfsprydataset 
    bind = "bind expression" 
    name = "data set name" 
    onBindError = "JavaScript function name" 
    options = "Spry options object" 
    type = "xml|json" 
    xpath = "XPath expression">

Note: You can specify this tag’s attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag’s attribute names as structure keys.

History

ColdFusion 8: Added this tag.

Attributes

Attribute	Req/Opt	Default	Description
`bind`	Required		A bind expression that returns an XML- or JSON- formatted string to populate the Spry data set. The bind expression specifies a CFC function or URL and includes bind parameters that represent the values of ColdFusion controls. For detailed information on bind expressions, see Binding data to form fields in the Developing ColdFusion Applications.
`name`	Required		The name of the Spry data set.
`onBindError`	Optional; HTML	See Description	The name of a JavaScript function to execute if the bind expression results in an error. The function must take two attributes: an HTTP status code and a message. If you omit this attribute, and specified a global error handler (by using the `ColdFusion.setGlobalErrorHandler` function), the handler displays the error message; otherwise a default error pop-up appears.
`options`	Optional		A JavaScript object containing constructor options for the data set. For example, to request the data using the HTTP POST method, specify the following attribute: `options="{method: 'POST'}"`. For detailed information on Spry options, see the Spry documentation at www.adobe.com/go/learn_spry_framework_en.
`type`	Optional	`xml`	Specifies data set type, corresponding to the format of the data that is returned by the bind expression. The following values are valid: `json` `xml`
`xpath`	Required for xml type Not used for JSON		An XPath expression that extracts data from the XML returned by the bind expression. The data set contains only the data that matches the XPath expression.

Usage

Use this tag to use a bind expression to dynamically create the contents of a Spry XML or JSON data set based on the value of a ColdFusion control or another Spry data set. To create a Spry data set without using a bind expression, use the Spry.Data.JSONDataSet() and Spry.Data.XMLDataSet() JavaScript functions.

This tag cannot create a Spry HTML data set.

To use a filter to select the contents of a JSON data set from a JSON expression, specify a path or subpath option in the options attribute. For example, to create a Spry JSON data set by using only the items.item element from the JSON data, use a tag such as the following:

<cfsprydataset name="theItems" type="json"  
    bind="CFC:dataMgr.getdetails(prodname={myform:mygrid.TITLE})" 
    options="{path: 'items.item.'}">

Example

The following cfsprydataset tag updates the dsProduct Spry XML data set by calling the GridDataManager.getProductDetails CFC function each time the selected row in the bookgrid control changes. It passes the TITLE field of the selected row to the CFC function as a prodname parameter. For a complete example that uses this tag, see Using Spry with ColdFusion in the Developing ColdFusion Applications.

<cfsprydataset  
    name="dsProduct"  
    type="xml" 
    bind="CFC:GridDataManager.getProductDetails(prodname= 
        {bookform:bookgrid.TITLE})"  
    xpath="products/product"  
    options="{method: 'POST'}" 
    onBindError="errorHandler">