JSON Manager - Documentation

Purpose

Middleware plugin that perform JSON manipulation through patches and are accessed through dataset, a named alias.

Use when

When a reteived JSON file or when a JSON result requested through a RESTful API need a few minor manipulation in order to be displayed with the data-json.

Do not use when

To perform complexe manipulation or metamorphing data in a way that change his original meaning. By complexe manipulation is like filtering, sorting, forking, merging, infering a result based from multiple source inside or outside the data context and any other operation that take time or required considerable amount of ressource where it badly impact the performance of the device and the user experience.

Instead, if your JSON file need a lot of manipulation, consider to create your own RESTful service that will accomodate for performing those task and it will allow to cache the result.

Instead, if your are metamorphing the JSON data source, then that is probably means it should be an middleware service that do that transformation prior to receive the data for being display.

Working example

English:

• JSON manager
• JSON manager with Do Action patches

French:

• Gestionnaire JSON
• Gestionnaire JSON avec l'exécuteur d'action de patches

How to implement

JSON manager is a middleware plugin that allow to manipulate JSON data and return it as a fetch result.

1. From a plugin that request JSON content, refer to a dataset name in the request url. For example with the data json plugin.

   <span data-json-replace="#[example1]/product">unknown number of</span>

2. Create a JSON manager plugin by adding the attribute data-jsonmanager to an element. At the minimum, you will need to configure the url and the dataset name.

   Then the following configuration is required if:

   • patches=[] If you are only applying static patches at the fetched JSON.

     <div data-wb-jsonmanager='{
     	"url": "demo/data-en.json",
     	"name": "example1",
     	"patches": [
     		{ "op": "wb-count", "path": "/products", "set": "/nbproduct" },
     		{ "op": "copy", "from": "/products/0", "path": "/product"}
     	]
     }'></div>

   • wait=true If the JSON manager need to wait to receive patches from another plugin, like urlmapping. Note that in this mode you can also specified a series of default patches to apply through setting the configuration patches

     <div id="jmexample1" data-wb-jsonmanager='{
     	"url": "data/data-1.json",
     	"name": "example1",
     	"wait": true
     }'></div>

3. Configure your patches as per the supported operation bellow

Note: The json manager can not be set on the same element that listen to wb.jsonfetch event, like data json.

Using Dataset

To refer at a dataset, it is quite similar to a JSON pointer. But you start with a bracket "[", followed by the dataset name, then by the closing bracket "]" and the rest is the JSON pointer to navigate in the dataset. You can find read about JSON Pointer in the RFC6901 spec or in the data-json plugin documentation.

#[DatasetName]/JSON/Pointer

JSON patches operation

JSON operation is defined as per RFC6002 - JavaScript Object Notation (JSON) Patch with additional operation to fullfill the needs of the JSON manager. Described in the documentation, the following operation are supported: add, remove, replace, move, copy, test, wb-count, wb-first, wb-last, wb-toDateISO and wb-toDateTimeISO. The operation that start with "wb" are custom operation defined inside the JSON manager

In the description bellow when it refering to :

<path>

That represents a string containing a valid JavaScript Object Notation (JSON) Pointer [RFC6901]. You can find JSON pointer example in the data-json working example under "Selecting data" heading.

<value>

A valid value, it could be a number, a string, a JSON object or a JSON array.

You will find a few examples in the Appendix A of RFC6002

It's is possible to add your own custom operations, like:

window[ "wb-jsonmanager" ] = {
	ops: [
		{
			name: "wb-count",
			fn: function( obj, key, tree ) {
				var countme = obj[ key ],
					len = 0;
				if ( $.isArray( countme ) ) {
					len = countme.length;
				}

				jsonpatch.apply( tree, [
					{ op: "add", path: this.set, value: len }
				] );
			}
		},
		{
			name: "wb-first",
			fn: function( obj, key, tree ) {
				var currObj = obj[ key ];
				if ( !$.isArray( currObj ) || currObj.length === 0 ) {
					return;
				}

				jsonpatch.apply( tree, [
					{ op: "add", path: this.set, value: currObj[ 0 ] }
				] );
			}
		}
	],
	opsArray: [ ],
	opsRoot: [ ],
}

There is tree type of configuration where you can defined your custom operation depending on what the operation is executed.

ops

Basic operation on a JSON node.

opsArray

Operation made upon JSON array.

opsRoot

Operation that target the root of JSON object.

Debugging

You can set the configuration option "debug": true to show, added the element that call the JSON manager, the modified JSON object and his applied patches. The JSON are displayed without any formating.

<div data-wb-jsonmanager='{
	"url": "data-en.json",
	"name": "example2",
	"debug": true
}'></div>

Cache busting

Before to use the cache busting mechanism with your data json instance, it's highly recommended to configure your server properly instead.

Various strategy can be set on the server side and those are communicated to the browser through an http header as defined in section 5 of RFC7234.

Configuration options

URL advanced configuration (Url fetch object)

An object representing the URL to be fetch with some advanced configuration on how to fetch and merge the file specified by the URL into the JSON manager.

Filtering (evaluation object)

The path selector must point to an valid JSON array object. All the option presented in the table bellow can be combined.

The configuration option fpath must be set in the JSON manager configuration in order to apply any filtering.

Extractor (selector object)

Events

$( "#MyJsonManager" ).trigger(  {
	type: "patches.wb-jsonmanager",
	patches: [ { JSON patached operation object } ]
} );

$( document ).on( "wb-ready.wb-jsonmanager", ".wb-jsonmanager", function( event ) {
});

$( ".wb-jsonmanager" ).on( "wb-ready.wb-jsonmanager", function( event ) {
});

$( document ).on( "wb-ready.wb", function( event ) {
});

Source code

JSON manager plugin source code on GitHub