Documentation

YASR is an extendable library which helps you present SPARQL results. The main class of YASR is responsible for gluing the different output plugins together, and providing utilities such as SPARQL results parsers.

Getting Started

Initialize YASQE via its constructor, which returns an instance (from now on referred to as yasr (lowercase).

YASR(parent: DOM-Element, settings: object, queryResponse: string|object) → YASR document: yasr

Main YASR constructor. The first argument, the DOM element to which to append YASR, is required. Optional values are a settings object (see the defaults section for more information), and/or the query response you'd like to show directly on initialization (or alternatively, set this via the doc.setResponse function)

Examples

API

yasr.setresponse(response: string|object)

Set and draw a SPARQL response. The parameter is either a plain response string, a jQuery response object, or it is an object with the following keys:

  • response: string|object (optional): the response string (or SPARQL XML/JSON object of the response)
  • contentType: string (optional)
  • exception: string (optional): YASR can display SPARQL errors as well
yasr.draw()

If there are any results already stored in YASR, draw them according to the currently selected visualization plugin

yasr.draw()

If there are any results already stored in YASR, draw them according to the currently selected visualization plugin

yasr.warn(warningMsg: string|object)

Show a warning message to the user. Input can either be an html string, or a jQuery object

yasr.somethingDrawn() → boolean

Check whether a result has been drawn

store: function()

Store persistent settings in local storage (if enabled via persistency setting in configuration)

load: function()

Load persistent settings from local storage

Events

YASR emits several events. For information on the possibilities of our event handler, see the EventEmitter implementation documentation of NodeJS
draw (instance: yasr, outputPlugin: outputPlugin)

Fires just before a plugins draws the results

draw (instance: yasr, outputPlugin: outputPlugin)

Fires when a plugin finished drawing the results

Configuration

This configuration object is accessible/changeable via YASR.defaults and yasr.options, and you can pass these along when initializing YASR as well. Output visualizations are defined separately.

outputPlugins: array (default: ["error", "boolean", "rawResponse", "table", "pivot", "leaflet"])

List of enabled output plugins. The order of these plugins specifies the order of the output buttons as well

output: string (default: "table")

key of default plugin

useGoogleCharts: true

Enable the use of Google Charts output. Google Charts is used in the Pivot plugin, as well as the Google Charts plugin. As Google Charts cannot be packaged fully in YASR, it poses an external dependency. (in case the Google API is not accessible, the Google Charts visualizations are disabled automatically)

drawOutputSelector: boolean (default: true)

Draw the output selector widget

drawDownloadIcon: boolean (default: true)

Draw download icon. Enabled HTML5 download functionality of query results, all on the client-side (i.e. without re-executing the query). This allows the user to download results already queried for, such as a CSV when a table is shown, or the original response when the raw response output is selected

uriTarget: boolean (default: '_blank')

Open links (anchor tags) of SPARQL results in a new browser tab/window (_blank), or the current one (_self)

getUsedPrefixes: function() → object (default: null)

Get the used prefixes. Plugins may use this to create more human-readable URIs. Return object should be in the form {"rdf" : "http://www.w3.org/1999/02/22-rdf-syntax-ns#"}

persistency: object
prefix

YASR is able to store settings between browser sessions, using LocalStorage (or, if this is not available, regular cookies or session storage). The persistent settings of YASR are prefixed, to avoid collisions with other applications or instances of YASR (running on the same domain). By default, key of the persistent settings are prefixed using the ID of the nearest parent (containing an ID, that is). To disable persistency alltogether, set this value to false.

results: object
key: string|function (default: 'results')

Make the query results persistent (set to null or false to disable)

maxSize: int (default: 100000)

The result set might too large to fit in local storage. It is impossible to detect the free space in the client-side storage. Therefore, we do not store all results in local storage, depending on a max number of characters in the SPARQL result serialization. Set this function conservatively. (especially when using multiple YASR instances on one page)

Plugins

Table

This plugin shows SPARQL results as a table, using the DataTables jQuery plugin. This plugin is defined at YASR.plugins.table. To configure this plugin, change the following settings:
YASR.plugins.table.defaults: object

Defaults for table plugin

fetchTitlesFromPreflabel: boolean (default: false when YASR is served via https, otherwise true)

Try to fetch the label representation for each URI, using the preflabel.org services. (fetching occurs when hovering over the cell)

mergeLabelsWithUris: boolean|string (default: false)

Merge bindings together, by using one value as the label, and the other as the hyperlink. When setting this to true, every projection variable ending with 'Label' will be used as text for the corresponding projection variable without that label. I.e., ?carLabel is used as text for the ?car projection variable (as long as ?car is a URI). If you'd like to specify your own postfix to trigger this behaviour, set your postfix as value, instead true.

.
yasr, plugin, binding, sparqlVar, {'rowId': rowId, 'colId': colId, 'usedPrefixes': usedPrefixes}) getCellContent: function (yasr: doc, plugin: doc, bindings: object, var: string, context:object) → string

Draw the cell content, for a given binding

getColumns: function(yasr: doc, plugin: doc) → array

Return the columns you'd like to draw. The output array should be in a format supports by DataTables (for more info see this)

callbacks: object

Set a number of handlers for the table

onCellMouseEnter: function (default: null)

Mouse-enter-cell event. Params that are passed to this function are td: domElement, event: event

onCellMouseLeave: function (default: null)

Mouse-leave-cell event. Params that are passed to this function are td: domElement, event: event

onCellClick: function (default: null)

Cell clicked event. Params that are passed to this function are td: domElement, event: event

datatable: object

Any additional DataTables-related settings. See the DataTables manual for more information

Raw Response

A plugin which uses CodeMirror to present the SPARQL results as-is.
YASR.plugins.rawResponse(yasr: Object) → yasr-rawResponse (doc):

Constructor of plugin which the query response as-is (highlighted using CodeMirror)

YASR.plugins.rawResponse.defaults

Settings object

CodeMirror: object

Any additional CodeMirror related settings. See the CodeMirror manual for more information.

Pivot Table

A plugin which uses the Pivot Table plugin.
YASR.plugins.pivot(yasr: Object) → yasr-pivot (doc):

Constructor of plugin

YASR.plugins.pivot.defaults

Settings object

pivottable: object

Any additional PivotTable related settings. See the PivotTable manual for more information.

useGoogleCharts: boolean (default: true)

Enable the use of google charts for visualizing the pivot data

useD3Chart: boolean (default: true)

Enable the use of D3Js for visualizing the pivot data. At this moment, the TreeMap is the only visualization for which the D3 library is used

mergeLabelsWithUris: boolean|string (default: false)

Merge bindings together, by using one value as the label. When setting this to true, every projection variable ending with 'Label' will be used as text for the corresponding projection variable without that label. I.e., ?carLabel is used as text for the ?car projection variable (as long as ?car is a URI). If you'd like to specify your own postfix to trigger this behaviour, set your postfix as value, instead of true.

.

Geo (leaflet)

A plugin which uses leaflet.
YASR.plugins.leaflet(yasr: Object) → yasr-leaflet (doc):

Constructor of plugin

YASR.plugins.leaflet.defaults

Settings object

map: function(yasr: doc, L: leaflet) → map-instance

Instantiate the leaflet map. By default, it instantiates the map with an Open Street Maps layer

formatPopup: function(yasr: doc, L: leaflet, forVariable:string, bindings) → string

Return the popup content for a given variable. The content is rendered as html. By default it tries to detect whether a similar variable exists in the bindings that is post-fixes with `Label`, and uses that as popup content.

missingPopupMsg: string | function(yasr: doc, L: leaflet, geoVariables: string[]) → string

The notification message when no poup content is found

Google Charts

A plugin which uses the Google Visualizations API. See this query for the capabilities of the chart output (example by Eetu Mäkelä).
YASR.plugins.gchart(yasr: Object) → yasr-pivot (doc):

Constructor of plugin

YASR.plugins.gchart.defaults

Settings object

Boolean results

YASR.plugins.boolean(yasr: Object) → yasr-boolean (doc):

Constructor of plugin which displays boolean info (i.e., the result of ASK queries)

Exceptions

YASR.plugins.error(yasr: Object) → yasr-error (doc):

Constructor of plugin which displays query response errors

YASR.plugins.error.defaults

Settings object

corsMessage: string (default: 'Unable to get response from endpoint')

The message to show when no response was returned. I.e., a DNS or TCP error. Depending on how you use YASR, there might be several reasons for this missing response, such as a CORS-disabled endpoint, the user being offline (where the endpoint is online), an endpoint under maintenance, or simply a wrong URL.

tryQueryLink: function → string (default: null)

Set this function to present the user with a button to try the same query via a regular browser window. This function simply returns the http link to open the browser window for.

Writing a plugin

To register an autocompletion, one needs to execute the YASQE.registerAutocompleter function. To register a plugin, add it to YASR by running YASR.registerOutput(pluginName: string, plugin: constructor). Below, we describe the autocompletion function in more detail, and the object it should return.

constructor(doc: yasr) → configurationObject: Object

The constructor should return an object with the following keys:

draw: function()Required

Draw the results. Use the yasr object to retrieve the SPARQL response

canHandleResults: function() → booleanRequired

Return whether this plugin is able to draw the current results

getPriority: int|functionRequired

The priority of a plugin is used to select the output plugin when the currently selected plugin is not able to draw the results.

hideFromSelection: booleanOptional

Whether to show this plugin in the output selector.

name: stringOptional

The human-readable name of the plugin, shown in the output selector.

getDownloadInfo: function() → objectOptional

Enables the download button. Returns a an object with the keys getContent: function() → response: string, filename: string, contentType: string, buttonTitle: string (the title attribute of the download button). Returning null will disable the download button for the current result.

getEmbedHtml: function() → stringOptional

Enables the embed button. Function should return an html string usable to embed the current output in other web pages. Returning null will disable the embed button for the current result.

getPersistentSettings: function() → objectOptional

If persistency is enabled, use this function to return those settings that you'd like to be persistent. Use to yasr.store() function to actually save these settings

setPersistentSettings: function(settings: object)Optional

If persistency is enabled, use this function to modify the plugin based on its previous state.