Updated instructions
Description
Integrate and Mashup the easy way!
More and more data on the web, as well as on local systems, are available through descriptive formats as xml and json. Such formats can be used to display data from other systems, such as news updates etc.
Displaying, or rendering, information in a json feed takes parsing of the json data, extracting relevant data and inserting this data into some kind of template document. This is where the Widgeteer steps in and keeps it SIMPLX!
The Widgeteer takes a very pleasent Modxish way to accomplish this: chunkMatching.
Consider the following json string:
--------------------------------------------------------------------------------------
{
"source":"modx",
"result":[
{"id":"1","type":"document","pagetitle":"JSON Test","description":"Simple demo of json"},
{"id":"2","type":"document","pagetitle":"JSON Test 2","description":"Simple demo of json 2"}
]
}
--------------------------------------------------------------------------------------
This is a very simplified json representing two pages in ModX.
First of all, as soon as you spot the char "{" its the start of a new json object representation. Consequently "}" finishes an object.
The first object in the json string above only has two attributes: "source", "result". "source" has the value "modx". The "result" attribute though is followed by "[". This sign represents the start of an array of json objects, in this case ModX documents. Widgeteer calls the "result" attribute "dataSetRoot", in other words the element which holds the array of data we want to render.
Instructions
The Widgeteer Snippet call:
-----------------------------------------------------------------------------------
[!SIMPLX_Widgeteer?
dataSet=`{"source":"modx","result":[{"id":"1","type":"document","pagetitle":"JSON Test","description":"Simple demo of json"},{"id":"2","type":"document","pagetitle":"JSON Test 2","description":"Simple demo of json 2"}]}`
&dataSetRoot=`result`
&useChunkMatching=true
&chunkMatchingSelector=`type`
&chunkPrefix=`test.`!]
-----------------------------------------------------------------------------------
The above call tells the Snippet:
1. to load a dataSet of json data.
2. to use the "result" element as root,
3. to automatically match json objects to Chunks,
4. which field in the json object to match Chunks with,
5. if we use a prefix in the Chunk name ("test.document" in this example)
The Snippet will now parse through the "result" array and for each object in the array it will try to find a matching ModX Chunk using the chunkPrefix + chunkMatchingSelector. If it finds a matching Chunk it will take the whole json object and replace the placeholders ([[+field_name]]) with the corresponding fields. A matching Chunk (named "test.document") for the above call could look like this:
--------------------------------------------------------------------------------
<div>
<p>
<strong>+pagetitle</strong>
</p>
<p>
[[+desription]]
<a href="?id=[[+id]]">Read more...</a>
</p>
</div>
--------------------------------------------------------------------------------
The Widgeteer can load data from,
1. a static data set, like in the previous example
2. a Snippet or a Chunk
3. an url to any valid json feed (using the dataSourceUrl parameter)
The parameters:
- "dataSourceUrl" - An url to any valid json source (uses CURL)
- "dataSet" - If no dataSourceUrl is specified a json string is expected here
- "useChunkMatching" - true/false decides if Widgeteer should try to match Chunks
- "chunkMatchingSelector" - If the useChunkMatching is set to true a json lookup field is expected here
- "staticChunkName" - If useChunkMatching is set to false, a Chunk name is expected there (will be applied to all json objects)
- "dataSetRoot" - The json array which holds the objects to parse. Adjust according to json format.
- "chunkMatchRoot" - true/false, if set to true Widgeteer will try to find a matching Chunk for the dataSetRoot property and wrap results in this.
- "chunkPrefix" - The prefix alows you to match the same type of json object differently depending on context. Very handy.
Also
Included in the Snippet you get a template which includes some examples.
You also get some sample Chunks which will get you started with templating.
Dont forget that you can potentially nest Snippet calls in your Chunks in order to parse more complex structures such as Atom feeds etc. I can not account for how this will affect caching henche Snippet performance...
Have fun!
/Lars