Writing javascript result printers

Table of Contents

This documentation is work in progress. Little of it has been updated since it was first written (2013) and some sections were not finished yet.

This guide applies for result printers compatible with SMW 1.9 and later, and MediaWiki 1.19 and later.

JavaScript result printer (JSRPrinter)

See also Writing result printers

SMWAPI integration

Jeroen wrote

The parser and formatters for the query descriptions can be quickly implemented in JS making use of a new API module. This ensures completeness and consistency with the PHP implementation, at the cost of some latency. Later on the implementation of these can always be changed without affecting other parts of the system.

Some interfaces:

• smw.AskParser: parse( string, options ) -> parserResult // containing validity, error array and if valid smw.QueryDescription
• smw.AskFormatter: format( smw.QueryDescription, options ) -> string
• smw.Store: runQuery( smw.QueryDescription, params ) -> smw.QueryResult // main implementation of this would use the ask API

See SMW and Wikidata

Custom events (a.k.a. MediaWiki hooks)

Add a custom event

$( '#element' ).trigger( 'smw_custom_event' );

Add callback to a custom event

$( document ).on( 'smw_custom_event', '#element', function(){ ... } );

or

function smw_callback(){ ... }

$( document ).on( 'smw_custom_event', '#element', smw_callback );

Guidelines for JavaScript resources

Plug-ins that are being used with a printer are normally placed in a folder called /resources following the individual printer but for common resources that will be used in more than printer the folder SemanticResultFormats/resources can be used to share plug-ins among other printers.

In light of genuine courtesy for the plug-in developer, please be so kind to add relevant information to the Help:Plug-ins page.

Register a resource

Resources register (see also MW's ResourceLoader) their details in SRF_Resources.php and once those plug-ins are made available through a unique identifier (such as ext.srf.gallery.slideshow etc.), modules are accessible via:

• addResources,
• SMWOutputs::requireResource( 'ext.srf.gallery.slideshow' );, or
• mw.loader.using( 'ext.jquery.tagcanvas.excanvas', sphere.init ); within JavaScript itself

Resource naming

Experience showed that separating the plug-in resource definition from the implemented JavaScript code (the code that uses the plug-in) will help in identifying malicious code fragments and make plug-ins available to others. Some naming convention can help to achieve consistency among registered resources:

• ext. identifies it as external resource
• ext.srf. identifies the resource as member of SemanticResultFormats
• ext.srf.<printer> references the resource to a printer
• ext.srf.<printer>.<additional> additional namespace
• ext.jquery.<plug-in> identifies the individual jquery plug-in

SRF plug-in namespace

In order to avoid the "pollution" of the $ namespace with unnecessary invoked methods or functions it is recommended to use the "semanticFormats" namespace for JavaScript related to SRF functions.

An example in how to extend methods into semanticFormats namespace, see examples in resource/ext.srf.util.*. A class references can be added (if appropriate declaration in srf.util* exists) like:

## Usage
var options ={
	'context'   : chart,
	'container' : container,
	'id'        : chartID,
	'info'      : infotext,
	'data'      : data
};

// Gridview class reference
new srf.util.grid( options );

An example on how to add methods to the srf.formats namespace, see the sparkline example which follows a similar pattern like:

new srf.formats.sparkline( { context: $( this ) } );

Above examples will amend the namespace window.semanticFormats = window.srf = srf with methods declared in srf.util* or srf.formats.*.

Code quality and testing

jshint is a static code analysis tool which can help identify potential erroneous code and mistakes. Before making a commit, you want to check your JavaScript and correct any potential messages from jshint in order to allow an easier code review process.

For testing related topics, see QUnit tests.