Serialization (JSON)

From semantic-mediawiki.org
Jump to: navigation, search
Table of Contents

This documentation is work in progress; some sections are not finished yet.

Specification

This guide applies for result printers compatible with SMW 1.9 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 SMWApi, the 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 SMWApi 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