diff --git a/editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid b/editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid index acf482789..816fa9110 100644 --- a/editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid +++ b/editions/tw5.com/tiddlers/howtos/Reading data from JSON tiddlers.tid @@ -6,6 +6,33 @@ type: text/vnd.tiddlywiki See [[JSON in TiddlyWiki]] for an overview of using JSON in TiddlyWiki. +!! Introduction + +The following examples assume the following JSON data structure is stored in a data tiddler called "foobar" with the type `application/json`: + +```json +{ + "a": "one", + "b": "", + "c": "three", + "d": { + "e": "four", + "f": [ + "five", + "six", + true, + false, + null + ], + "g": { + "x": "max", + "y": "may", + "z": "maize" + } + } +} +``` + !! Text References for Accessing JSON Data [[Text references|TextReference]] are a simple shortcut syntax to look up the value of a named property. For example, if a [[DictionaryTiddler|DictionaryTiddlers]] called `MonthDays` contains: @@ -23,3 +50,74 @@ The same is true if `MonthDays` is a [[JSONTiddler|JSONTiddlers]] with the follo ``` {"oct":31,"nov":30,"dec":31} ``` + +!! Operators for Reading JSON Data + +Values are identified by a sequence of indexes. For example, the value at `[a]` is `one`, and the value at `[d][f][0]` is `five`. + +The new operators use multiple operands to specify the indexes: + +``` +[[foobar]jsonget[a]] --> "one" +[[foobar]jsonget[d],[e]] --> "four" +[[foobar]jsonget[d],[f],[0]] --> "five" +``` + +Indexes can be dynamically composed from variables and transclusions: + +``` +[[foobar]jsonget,{!!field},[0]] +``` + +Boolean values and null are returned as normal strings. The [[jsontype Operator]] returns a string identifying the original type. Thus: + +``` +[[foobar]jsontype[a]] --> "string" +[[foobar]jsontype[d]] --> "object" +[[foobar]jsontype[d],[f]] --> "array" +[[foobar]jsontype[d],[f],[2]] --> "boolean" +``` + +Using the [[jsonget Operator]] to retrieve an object or an array returns a list of all the values. For example: + +``` +[[foobar]jsonget[d],[f]] --> "five","six","true","false","null" +[[foobar]jsonget[d],[g]] --> "max", "may", "maize" +``` + +The [[jsonindexes Operator]] retrieves the corresponding indexes: + +``` +[[foobar]jsonindexes[d],[f]] --> "0", "1", "2", "3", "4" +[[foobar]jsonindexes[d],[g]] --> "x", "y", "z" +``` + +The behaviour when retrieving an object or array that contains values that are themselves objects or arrays may be confusing: the object is read recursively as a list of values. For example: + +``` +[[foobar]jsonget[d]] --> "four", "five", "six", "true", "false", "null", "max", "may", "maize" +``` + +A further subtlety is that the special case of a single blank operand is used to identify the root object. Thus: + +``` +[[foobar]jsonindexes[]] --> "a", "b", "c", "d" +``` + +An example of using a list widget to iterate through the properties of an array within a JSON object: + +``` +<$list filter="[[foobar]jsonindexes[d][f]]"> +
+ <$text text=<>/>: <$text text={{{ [[foobar]jsonget[d][f]] }}}/> +
+ + +Prints: + +0: five +1: six +2: true +3: false +4: null +```