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
• Conditional template

French:

• Data JSON
• Gabarit HTML 5
• Gabarit conditionel

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 or without the streamline flag since WET 4.0.64 it is 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

Because the object already contains a field named @id

{
	"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.

Test functions that extract a testable value

Those test require a data pointer either provided with the value property which would also iterate or with assess which don't iterate.

fn:isArray

Boolean returning if the tested value is an array or not.

fn:isLiteral

Boolean returning if the tested value is an literal or not. A literal value is considered to be defined and not an object.

fn:getType

Return type of the value set via the @type property or its corresponding javascript typeof value.

fn:guessType

The template parser will try to guess the data type of the tested value.

This test function will return:

• rdfs:Container when the value is an array.
• rdfs:Literal for any value that is literal. A literal value is considered to be defined and not an object.
• rdfs:Resource when the value is an JSON object without any defined type.
• xsd:anyURI when the value is a string which start with non-spaced letter and digit immediately followed by colon ":" like https://example.com
• xsd:string when the value is a string and don't look to be an URI.
• xsd:boolean when the value is a boolean with the value set to true or false
• xsd:double when the value is a JSON number
• The value set via the @type sub property
• undefined when the value is undefined

fn:getValue

Return value as the testable value.

Operand function

Operand functions that check the testable value.

softEq (default)

Check if the value is equivalent equal to the expectation optionally either in an array value. When no expectation provide, return true if the testable value exist.

eq

Check if the value equal the expectation. Including when the value is an object.

neq

Check if the value is not equal the expectation. Including when the value is an object.

in

Check if the value (or array of value) is in the expectation (or array of expectation)

nin

Check if the value (or array of value) is not in the expectation (or array of expectation)

Configuration options

{
	error: "<Details of the error in English>",
	status: "<Status or category of the error>",
	url: "<Relative URL of the failed resource>",
	response: {
		text: "<Text version of the resource sanitized, if applicable>",
		status: "<HTTP status number>",
		statusText: "<HTTP status text>"
	}
}

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