Data JSON - Documentation

Purpose

Insert content extracted from a JSON file or provided by a dataset.

The role of this plugin is to display selected data into HTML elements, if you need to manipulate the data prior it get displayed or you need to interact with, then use this plugin in conjonction with the JSON-manager plugin that support dataset.

Use when

When you need to display the same atomic information on multiple pages. Like a fee for a services that is re-use across multiple pages.

To insert repeatitive content by using HTML5 template element.

Do not use when

• To insert block of HTML content, instead use data-ajax with the filtering option if neccessary.
• For inserting data that only apply to an unique page.

Working example

English:

• Data JSON
• HTML 5 template

French:

• Data JSON
• Gabarit HTML 5

How to implement

1. Create a valid JSON file
2. The one of the following:

   • Add one of the following data-json attributes to an element, with the attribute value being the URL of the JSON file followed by a JSON Pointer (RFC6901) URL hash:

     • data-json-after: Insert content after the element

       <span data-json-after="json/data-en.json#/JSON/Pointer">
       			...
       		</span>

     • data-json-append: Insert content at the end of the element

       <span data-json-append="json/data-en.json#/JSON/Pointer">
       			...
       		</span>

     • data-json-before: Insert content before the element

       <span data-json-before="json/data-en.json#/JSON/Pointer">
       			...
       		</span>

     • data-json-prepend: Insert content at the start of the element

       <span data-json-prepend="json/data-en.json#/JSON/Pointer">
       			...
       		</span>

     • data-json-replace: Replace content inside the element

       <span data-json-replace="json/data-en.json#/JSON/Pointer">
       			...
       		</span>

     • data-json-replacewith: Replace the element by the content

       <span data-json-replacewith="json/data-en.json#/JSON/Pointer">
       			...
       		</span>

   • For HTML5 templating, add the attribute data-wb-json on the elements you wanted to append items. The following populate a list:

     <ul data-wb-json='{
     		"url": "data-en.json#/anArray",
     		"queryall": "li",
     		"mapping": [
     			"/name"
     		]
     	}'>
     	<template>
     		<li></li>
     	</template>
     </ul>

     Where:

     url

     JSON file location or dataset name followed by an optional JSON pointer

     queryall

     Contain a valid CSS selector.

     mapping

     Array of JSON pointer, as many as the return result of queryall applied on the <template> element.

     Note: When using the template for filling a table, wrap your rows template into a table element in order to avoid a bug in Internet Explorer.

   • Use the data for shapping multiple area of an HTML element

     <a href="generic/location.html" data-wb-json='[
     		{
     			"url": "mydata.json#/first/title",
     			"type": "replace"
     		},
     		{
     			"url": "mydata.json#/first/html_url",
     			"type": "prop",
     			"prop": "href"
     		}
     	]'>Generic location</a>

Selecting data

(Source: JSON Pointer, RCF6901)

For example, given the JSON document

{
	"foo": ["bar", "baz"],
	"": 0,
	"a/b": 1,
	"c%d": 2,
	"e^f": 3,
	"g|h": 4,
	"i\\j": 5,
	"k\"l": 6,
	" ": 7,
	"m~n": 8
}

The following URI fragment identifiers evaluate to the accompanying values:

Issue that you may encounter

Display nothing, plugin seems to be broken.

Ensure that your JSON file is valid

Recently updated data do not display

Refresh your browser cache by opening a new tab the JSON file and then do a hard refresh Ctrl + F5 or by testing your page from a new private mode session of your browser.

HTML5 template element in the specification

Official reference:

• HTML5.2 W3C Working Draft - 4.12.3. The template element
• HTML5 W3C Recommendation - 4.11.3 The template element
• WHATWG Living standard - 4.12.3 The template element

The following was extracted from HTML5.2 spec:

Contexts in which this element can be used.

The following is a non-normative description of where the element can be used. This information is redundant with the content models of elements that allow this one as a child, and is provided only as a convenience.

• Where metadata content is expected.
• Where phrasing content is expected.
• Where script-supporting elements are expected.
• As a child of a colgroup element that doesn’t have a span attribute.

Content model

A normative description of what content must be included as children and descendants of the element.

• Either: Metadata content.
• Or: Flow content.
• Or: The content model of <ol> and <ul> elements.
• Or: The content model of <dl> elements.
• Or: The content model of <figure> elements.
• Or: The content model of <ruby> elements.
• Or: The content model of <object> elements.
• Or: The content model of <video> and audio elements.
• Or: The content model of <table> elements.
• Or: The content model of <colgroup> elements.
• Or: The content model of <thead>, <tbody>, and <tfoot> elements.
• Or: The content model of <tr> elements.
• Or: The content model of <fieldset> elements.
• Or: The content model of <select> elements.
• Or: The content model of <details> elements.
• Or: The content model of <menu> elements whose type attribute is in the popup menu state.

Note that the following elements, incomplete list, have a content model that could expect script-supporting elements: ol, ul, dl, table, thead, tbody, tfoot, tr, select, menu

Template - Transforming JSON object into an array

Since WET 4.0.27 it is now possible to iterate anything that is not an array to render content through a <template>. It simply get transformed into a array. There is a low risk of lost of information, only one specific use case. It's quite similar to the JSON-LD Expanded Form. In this transformation process, it assume the array key is an IRI. Then the will result include some property from JSON-LD such as @id and @value. The @id wont be overwritten, in those such case the array key will be discard after the transformation.

When the value is a sub-object

{
	"key1": {
		"keyA": "value1",
		"keyB": "value2"
	},
	"key2": {
		"keyA": "value3",
		"keyB": "value4"
	}
}

[
	{
		"@id": "key1",
		"keyA": "value1",
		"keyB": "value2"
	},
	{
		"@id": "key2",
		"keyA": "value3",
		"keyB": "value4"
	}
]

When the value are not an object

{
	"key1": "value1",
	"key2": "value2",
	"key3": "value3"
}

[
	{
		"@id": "key1",
		"@value": "value1"
	},
	{
		"@id": "key2",
		"@value": "value2"
	},
	{
		"@id": "key3",
		"@value": "value3"
	}
]

When the value is a native data type

Selecting the value of key1 to iterate.

{
	"key1": "value1"
}

{
	"key1": [
		"value1"
	]
}

When the value is an array

{
	"key1": [
		{ "keyA": "value1" },
		{ "keyA": "value2" }
	],
	"key2":  [
		{ "keyA": "value3" },
		{ "keyA": "value4" }
	]
}

[
	{
		"@id": "key1",
		"@value": [
			"keyA": "value1",
			"keyA": "value2"
		]
	},
	{
		"@id": "key2",
		"@value":
			"keyA": "value3",
			"keyA": "value4"
		]
	}
]

When the array key information will be lost

{
	"key1": {
		"@id": "https://wet-boew.github.io/vocab/example/1",
		"keyA": "value1",
		"keyB": "value2"
	},
	"key2": {
		"@id": "https://wet-boew.github.io/vocab/example/2",
		"keyA": "value3",
		"keyB": "value4"
	}
}

[
	{
		"@id": "https://wet-boew.github.io/vocab/example/1",
		"keyA": "value1",
		"keyB": "value2"
	},
	{
		"@id": "https://wet-boew.github.io/vocab/example/2",
		"keyA": "value3",
		"keyB": "value4"
	}
]

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

Events

$( document ).on( "wb-ready.wb-data-json", "[data-json-after], [data-json-append], [data-json-before], [data-json-prepend], [data-json-replace], [data-json-replacewith]", function( event, ajaxType ) {
	});

$( "[data-json-after], [data-json-append], [data-json-before], [data-json-prepend], [data-json-replace], [data-json-replacewith]" ).on( "wb-ready.wb-data-json", function( event, ajaxType ) {
	});

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

$('#mycontainer').on( "wb-contentupdated", function( event, data ){
	});

Source code

Data JSON plugin source code on GitHub