cfsprydataset

Description

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

History

ColdFusion 8: Added this tag.

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.

Attributes

Attribute	Description	Required	Default
bind	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.	Required
name	The name of the Spry data set.	Required
onBindError	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.	Optional; HTML	See Description
options	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.	Optional
type	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	Optional	xml
xpath	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.	Required for xml type Not used for JSON

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">

cfmldocs