Spry JSON Data Set Overview

JSON stands for JavaScript Object Notation. It is a lightweight data exchange format written in Javascript. Smaller file size and ease of use makes it a preferred choice for some developers.

Spry can now make use of this data format in Spry pages.

Since the Spry region mechanism doesn't care where the data comes from, using regions and data references doesn't change with a JSON data set. Similarly, JSON works the same way as the XML data set with things like filtering and caching. Because of these similarities, they will not be discussed in this document. Please refer to the Data Set Overview for base data set functions.

To see working examples of the different ways JSON can be used, see the JSON sample.

This document will discuss the JSON specific features of the data set.

What is JSON?

Like XML, JSON is a repeating data structure used to pass data. Here is a basic sample:

{
    "firstName": "Jason",
    "lastName": "Jones",
    "address": {
        "city": "San Francisco, CA",
        "zip": 94121,
        "address": "444 Columbus Ave"
    },
    "email": [
        "jason@sf.com",
        "sjones@adobe.com"
       ]
}

For more information about JSON, check our JSON Primer. JSON lends itself to complex, nested structures. (Which is why we didn't introduce it until we had our Nested Data Set solution...)

Creating JSON Data Sets

For those used to XML data sets, JSON will be similar, with a couple small differences.

First, you need 'SpryJSONDataSet.js'. 'SpryData.js', which contains the region handling code and the filtering and other functionality, is required. You do not need 'xpath.js' for the JSON data set.

<script src="SpryData.js" language="javascript" type="text/javascript"></script>
<script src="SpryJSONDataSet.js" language="javascript" type="text/javascript"></script>

As with all data sets, you point to a file that contains the JSON data and then specify the node of the data that defines the starting point of the data set.

A typical data set constructor for a JSON data set is:

var dsExample4 = new Spry.Data.JSONDataSet("../../data/json/object-02.js", { path: "batters.batter" });

The JSON file referenced is here.

The constructor starts with defining a variable name which is the name of the data set. The name can be whatever you wish. Multiple data sets are possible and must have unique names.

Then create the new object:

Remember that Javascript is case sensitive.

Next, specify the path to the file that contains the JSON info:

If it is a path to a file, wrap it in quotes as shown. Variables and Spry data references can also be used here, without quotes.

This is the minimum amount of information required to create the data set.

Paths and Subpaths

If you need to specify a specific section of the JSON data, specify a path in the constructor. Since it is an option, it is wrapped in {}.

Note: JSON uses a 'dot' notation to specify the path within the JSON. This works similar to XML and XPath, which uses a '/' to denote the node path.

Using another example from the JSON sample above.

{
    "firstName": "Jason",
    "lastName": "Jones",
    "address": {
        "city": "San Francisco, CA",
        "zip": 94121,
        "address": "444 Columbus Ave"
    },
    "email": [
        "jason@sf.com",
        "sjones@adobe.com"
       ]
}

If we wanted to just get the "city" node of the file, the constructor would be:

var ds1 = new Spry.Data.JSONDataSet("myfile.js", {path: "address.city"});

Sub Paths

Because of the complexity of some JSON files, the JSON data set has a way to specify advanced flattening.

Some JSON formats use nested structures to simply group data together. An example of this would be the "image" and "thumbnail" properties in the following example:

{
	"id": "0001",
	"type": "donut",
	"name": "Cake",
	"image":
		{
			"url": "images/0001.jpg",
			"width": 200,
			"height": 200
		},
	"thumbnail":
		{
			"url": "images/thumbnails/0001.jpg",
			"width": 32,
			"height": 32
		}
}

It is sometimes desirable to flatten these structures so they are also available as columns in the data set. You can use the "subPaths" constructor option to tell the JSON Data Set to include these nested structures when it flattens the top-level JSON object, or the data selected by the "path" constructor option. In this particular example, because we have not specified a "path" constructor option, the JSON data set will attempt to flatten only the top-level object. Since we want to also include the data from the "image" nested structure, we specify the path to the data which is simply "image".

var dsExample6 = new Spry.Data.JSONDataSet("../../data/json/object-03.js", { subPaths: "image" });

Spry will take the information within the "image" node, and pull it to the top node, therefore, including the sub node information in the data set. Now, the image sub nodes can be used as data references by prepending 'image.' to the sub node name.

{id} {type} {name} {image.width} {image.height} {image.url}

Spry supports multiple sub paths. In the above sample, it is likely the 'thumbnail' information will be needed as well. To get this into the data set, specify the 'thumbnail' as another sub path.

var dsExample7 = new Spry.Data.JSONDataSet("../../data/json/object-03.js", { subPaths: [ "image", "thumbnail" ] });

Note that multiple sub paths are sent as an array of strings, wrapped in []. Now the available data references look like:

{id} {type} {name} {image.width} {image.height} {image.url} {thumbnail.width} {thumbnail.height} {thumbnail.url}

Using Data Set functionality

As a Spry Data Set, the JSON Data Set can take advantage of all the base data set functionality.

For instance, to turn off the cache and use distinct:

var ds1 = new Spry.Data.JSONDataSet("myfile.js", {path: "address.city", useCache:false, distinctOnLoad:true});

One of the goals of Spry is that the region workflow is independent of the data set types. JSON, XML and HTML data sets can be used interchangeably with the same region markup..

Copyright © 2007. Adobe Systems Incorporated. All rights reserved.