Adobe ColdFusion 8

cfsprydataset

Description

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

Category

Internet protocol tags

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.

See also

cfajaximport, "Using Spry with ColdFusion" in the ColdFusion Developer's Guide

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 ColdFusion Developer's Guide.

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.

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 bookgird 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 ColdFusion Developer's Guide.

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