Serialization (JSON)

From semantic-mediawiki.org
Table of Contents
This documentation is work in progress; some sections are not finished yet.

Specification

This guide applies for result printers compatible with Semantic MediaWiki 1.9.0Released on 3 January 2014 and compatible with MW 1.19.0 - 1.22.x. and later.

Printrequests

The printrequests array will contain:

  • label -> string for labeling results, contains no markup
  • typeid -> id of the datatype of the printed objects, if applicable
  • mode -> type of print request
  • format -> output format string for formatting results, if applicable

Results

The results array will contain:

  • subject (like File:Foo.jpg)
  • printouts specifed by
    • printrequests label (queried property)
    • printrequests value
  • fulltext -> subject fulltext name
  • fullurl -> subject url
  • namespace -> subject namespace number
  • exists -> boolean if the subject exists (red vs. blue link)

Meta

  • hash -> md5 hash key of the result array (mostly used for comparison on the client side via JS etc.)
  • count -> count of the results arrays
  • offset -> set by the query (count + offset result in total of available results)

Meta array is only relevant for the SMW API, the result format "JSON"Outputs semantic data in JSON format will only export the count number of the related query.

Example

{
"printrequests": [
    {
        "label": "",
        "typeid": "_wpg",
        "mode": 2
        "format": "",
    },
    {
        "label": "Modification date",
        "typeid": "_dat",
        "mode": 1
        "fomat": "",
    }
],
"results": {
    "File:Foo.jpg": {
        "printouts": {
            "Modification date": [
                "1360064258"
            ]
        },
        "fulltext": "File:Foo.jpg",
        "fullurl": "http:\/\/localhost\/mw\/index.php\/File:Foo.jpg",
        "namespace": 6,
        "exists": true
    },
    "Bar": {
        "printouts": {
            "Modification date": [
                "1358906761"
            ]
        },
        "fulltext": "Bar",
        "fullurl": "http:\/\/localhost\/mw\/index.php\/Bar",
        "namespace": 0,
        "exists": true
    },

JavaScript and SMW JSON serialization

Currently available result printers that use the SMW API and result serialization are DataTables class and EventCalendar class

The "smw.Data.factory()" (normally is only called during smw.Api.parse/fetch) will map result objects that were serialized by the SMW\DISerializer and generate type hinting objects simialar to the dataitems/datavalues in PHP. TypeId is used as reference map to assign each of its objects to a corresponding a smw.dataItem/smw.dataValue object.

  • '_wpg' -> smw.dataItem.wikiPage
  • '_uri' -> smw.dataItem.uri
  • '_dat' -> smw.dataItem.time
  • smw.dataItem.property
 * Structure is similar to
 *
 * Subject (if exists is of type smw.dataItem.wikiPage otherwise a simple object)
 * |--> property -> smw.dataItem.property
 *         |--> smw.dataItem.wikiPage
 *         |--> ...
 * |--> property -> smw.dataItem.property
 *         |--> smw.dataItem.uri
 *         |--> ...
 * |--> property -> smw.dataItem.property
 *         |--> smw.dataItem.time
 *         |--> ...

Access serialized objects via Api

var smwApi = new smw.Api();
smwApi.parse( data ) returns typed objects

// Collect query information
var conditions = data.query.ask.conditions,
	printouts = data.query.ask.printouts,
	parameters = {
		'limit' : data.query.ask.parameters.limit,
		'offset': data.query.ask.parameters.offset
	};

// Stringify the query
var query = new smw.Query( printouts, parameters, conditions ).toString();

// Fetch data via Ajax/SMWAPI
smwApi.fetch( query )
.done( function ( result ) {
...
} )
.fail( function ( error ) {
...
} );

Parse serialized objects

This is an example and only should give a glipmse in "how easy" it is to parse SMW typed objects in JS.

function getResults( parameters, results ) {
	...
	$.each( results, function( subjectName, subject ) {
		...
		// Subject
		if ( subject instanceof smw.dataItem.wikiPage ) {
			url = parameters.link === 'none' ? null : subject.getUri();
			title = subject.getFullText();
		}

		if ( $.inArray( 'printouts', subject ) ) {
			$.each ( subject.printouts, function( property, values ) {

				$.map ( values, function( value ) {
					var D = {};

					// Time type properties
					if ( value instanceof smw.dataItem.time ) {
						D.date = value.getDate().toISOString();
					// Page type properties
					} else if ( value instanceof smw.dataItem.wikiPage ) {
						D.title = value.getFullText();
					}
					...
				} )
			} )
		} );
	} );

	return { ... };
}

See also