Documentation

YASQE extends the CodeMirror Library. For a complete overview of the functionality they offer (such as event hooks), check out the CodeMirror Documentation. Below we elaborate on the functionality YASQE offers (in addition to the CodeMiror API).
Note: Where CodeMirror provides CodeMirror in the global namespace, we provide YASQE.

Getting Started

Initialize YASQE via its constructor, or via the command fromTextArea. Both return in instance of YASQE, from now on referred to as yasqe (lowercase). Both function take as argument a config object. See the section on defaults for more information on this config object.

YASQE(parent: DOM-Element, settings: Object) → YASQE document: Doc

Main YASQE constructor. Pass a DOM element as argument to append the editor to, and (optionally) pass along config settings (see the YASQE.defaults object below, as well as the regular CodeMirror documentation, for more information on configurability)

YASQE.fromTextArea(textArea: DOM element, config: Object) → YASQE document: Doc

Initialize YASQE from an existing text area (see http://codemirror.net/doc/manual.html#fromTextArea for more info)

API

API methods accessible via the yasqe instance
doc.setValue(query: String)

Set query value in editor (see http://codemirror.net/doc/manual.html#setValue)

doc.getValue() → query: String

Get query value from editor (see http://codemirror.net/doc/manual.html#getValue)

doc.query(function|object)

Execute query. Pass a callback function, or a configuration object (see the sparql settings in the configuration object for possible values) I.e., you can change the query configuration by either changing the default settings, changing the settings of this document, or by passing query settings to this function

doc.getQueryMode() → string:

Fetch the query mode: 'query' or 'update'

doc.getQueryType() → string:

Fetch the query type (e.g. SELECT, ASK, DESCRIBE, CONSTRUCT etc)

yasqe.getPrefixesFromQuery() → object:

Fetch defined prefixes from query string

doc.setSize(width: Number|string, height: Number|string)

Set size. Use null value to leave width or height unchanged. To resize the editor to fit its content, see http://codemirror.net/demo/resize.html

doc.storeBulkCompletions(type: String)

Store bulk completions in memory as trie, and in localstorage as well (if enabled). The argument should be a key from the autocompletion settings

Configuration

This configuration object is accessible/changeable via YASQE.defaults and yasqe.options, and you can pass these along when initializing YASQE as well. Other than the configuration we describe here, check the CodeMirror documentation for even more options you (check the CodeMirror documentation for even more options you can set, such as disabling line numbers, or changing keyboard shortcut keys.

Defaults

value: String (default: "SELECT * WHERE {\n ?sub ?pred ?obj .\n} \nLIMIT 10")

Query string

extraKeys: object

Extra shortcut keys. Check the CodeMirror manual on how to add your own

createShareLink: function (default: YASQE.createShareLink)

Show a button with which users can create a link to this query. Set this value to null to disable this functionality. By default, this feature is enabled, and only the query value is appended to the link. This function should return an object which is parseable by jQuery.param

consumeShareLink: function (default: YASQE.consumeShareLink)

The handler for consuming the arguments of the current URL

persistent: function|string

Change persistency settings for the YASQE query value. Setting the values to null, will disable persistancy: nothing is stored between browser sessions. Setting the values to a string (or a function which returns a string), will store the query in localstorage using the specified string. By default, the ID is dynamically generated using the YASQE.determineId function, to avoid collissions when using multiple YASQE instances on one page

sparql: object

Settings for querying sparql endpoints

showQueryButton: boolean (default: false)

Show a query button. You don't like it? Then disable this setting, and create your button which calls the query() function of the yasqe document

endpoint: String|function (default: "http://dbpedia.org/sparql")

Endpoint to query

requestMethod: String|function (default: "POST")

Request method via which to access the SPARQL endpoint

acceptHeader: String|function (default: YASQE.getAcceptHeader)

Query accept header

namedGraphs: array (default: [])

Named graphs to query.

defaultGraphs: array (default: [])

Default graphs to query.

args: array (default: [])

Additional request arguments. Add them in the form: {name: "name", value: "value"}

headers: array (default: {})

Additional request headers

handlers: object

Set of ajax handlers

beforeSend: function (default: null)

See jQuery.ajax for more information

complete: function (default: null)

See jQuery.ajax for more information

error: function (default: null)

See jQuery.ajax for more information

success: function (default: null)

See jQuery.ajax for more information

autocompletions: object

The set of possible YASQE autocompletions. You can use these configurations as examples for creating your own kind of SPARQL autocompletions. To disable one or more of the autocompletions, set that particular key to null. A complete overview of the possible values for these autocompletion keys, is shown in detail in the separate autocompletions section. Below, we only shortly present the autocompletions we provide by default, and their most interesting properties.

prefixes: object
get: function|array (default: function (YASQE.fetchFromPrefixCc))

Fetches the prefixes from prefix.cc

async: boolean (default: false)

The get function is asynchronous

bulk: boolean (default: true)

Use bulk loading for prefixes: all prefixes are retrieved onLoad using the get() function, as this list easily fits in memory and localstorage (for persistency)

autoShow: boolean (default: true)

Auto-show the autocompletion dialog

autoAddDeclaration: boolean (default: true)

This property is specific to the prefix autocompletion type. When a user types e.g. rdf: in a triple pattern, the editor automatically add this particular PREFIX definition to the query if it isn't already specified yet.

persistent: string|function (default: "prefixes")

Automatically store autocompletions in localstorage, avoiding executing the prefix.cc ajax call on each load

properties: object

Property autocompletion settings

get: function|array (default: function (YASQE.fetchFromLov))

Fetches the autocompletions from the LOV API

preProcessToken: function (default: function)

Preprocesses the CodeMirror token before matching it with our autocompletions list: convert a prefixed URI to a full-length URI.

postProcessToken: function (default: function)

Postprocesses the autocompletion suggestion: if needed, convert the full-length suggestion back to the prefixed equivalent.

async: boolean (default: true)

The get function is asynchronous, i.e. for each autocompletion the token is passed to the get function

autoShow: boolean (default: false)
handlers: object

A set of handlers. Most taken from the CodeMirror showhint plugin

validPosition: function (default: YASQE.showCompletionNotification)

Show a small notification when the cursor is in a valid autocompletion position

invalidPosition: function (default: YASQE.hideCompletionNotification)

Hide the notification when the cursor is not in a valid autocompletion position

classes: object

Class autocompletion settings, very similar to the configuration of the properties autocompletions

get: function|array (default: function (YASQE.fetchFromLov))

Fetches the autocompletions from the LOV API

preProcessToken: function (default: function)

Preprocesses the CodeMirror token before matching it with our autocompletions list: convert a prefixed URI to a full-length URI.

postProcessToken: function (default: function)

Postprocesses the autocompletion suggestion: if needed, convert the full-length suggestion back to the prefixed equivalent.

async: boolean (default: true)

The get function is asynchronous, i.e. for each autocompletion the token is passed to the get function

autoShow: boolean (default: false)
handlers: object

A set of handlers. Most taken from the CodeMirror showhint plugin

validPosition: function (default: YASQE.showCompletionNotification)

Show a small notification when the cursor is in a valid autocompletion position

invalidPosition: function (default: YASQE.hideCompletionNotification)

Hide the notification when the cursor is not in a valid autocompletion position

variableNames: object

Variable names autocompletion settings

get: function|array (default: function (YASQE.autocompleteVariables))

For the current token, fetch the possible variables

async: boolean (default: false)

This get function is synchronous

bulk: boolean (default: false)

Variables are not loaded in bulk on first load, but dynamically fetch every time from the query itself

autoShow: boolean (default: true)

Auto-show the variable autocompletion dialog

Autocompletions

Here, we describe the properties of an autocompletions objects. Add this object to either YASQE.defaults.autocompletions.<name>, yasqe.options.autocompletions<name>, or as part of the configuration object passed during YASQE initialization.
isValidCompletionPosition: function

Check whether the cursor is in a proper position for this autocompletion.

get: function|array

Get the autocompletions. Either a function which returns an array, or an actual array. The array should be in the form ["<completionsString1>", "<completionsString2>"]

preProcessToken: function

Preprocesses the codemirror token before matching it with the autocompletions list. Use this for e.g. autocompleting prefixed resources when your autocompletion list contains only full-length URIs E.g., foaf:name -> http://xmlns.com/foaf/0.1/name

postProcessToken: function

Postprocesses the autocompletion suggestion. Use this for e.g. returning a prefixed URI based on a full-length URI suggestion E.g., http://xmlns.com/foaf/0.1/name -> foaf:name

async: boolean

Specifies that the get function is asynchronous

bulk: boolean

Use bulk loading of prefixes: all prefixes are retrieved onLoad using the get() function. Alternatively, disable bulk loading, to call the get() function whenever a token needs autocompletion (in which case the completion token is passed on to the get() function). whenever you have an autocompletion list that is static, and that easily fits in memory, we advice you to enable bulk for performance reasons (especially because the autocompletions are stored in a trie)

autoShow: boolean

Auto-show the autocompletion dialog. Disabling this requires the user to press [ctrl|cmd]-space to summon the dialog. Note: this only works when completions are not fetched asynchronously

persistent: string|function

Automatically store autocompletions in localstorage. This is particularly useful when the get() function is an expensive ajax call. Autocompletions are stored for a period of a month. Set this property to null to disable persistency. Otherwise, set a string value (or a function returning a string val), returning the key in which to store the data. Note: this feature only works when completions are loaded in memory (i.e. bulk: true)

handlers: object

A set of callbacks. Most, taken from the CodeMirror showhint plugin

validPosition: function

Fires when a codemirror change occurs in a position where we can show this particular type of autocompletion

invalidPosition: function

Fires when a codemirror change occurs in a position where we can not show this particular type of autocompletion

showHint: function

See CodeMirror manual

select: function

See CodeMirror manual

pick: function

See CodeMirror manual

close: function

See CodeMirror manual

Statics

Static functions YASQE
YASQE.consumeShareLink(YASQE: Doc, urlArgs: object)

Consume the share link, by parsing the document URL for possible yasqe arguments, and setting the appropriate values in the YASQE doc

YASQE.createShareLink(YASQE: Doc) → object:

Create a share link

YASQE.determineId(doc: YASQE)

Determine unique ID of the YASQE object. Useful when several objects are loaded on the same page, and all have 'persistency' enabled. Currently, the ID is determined by selecting the nearest parent in the DOM with an ID set

YASQE.fetchFromLov(doc: YASQE, partialToken: Object, type: "properties" | "classes", callback: Function)

Fetch property and class autocompletions the Linked Open Vocabulary services. Issues an async autocompletion call

YASQE.fetchFromPrefixCc(doc: YASQE)

Fetch prefixes from prefix.cc, and store in the YASQE object

YASQE.getAcceptHeader(doc: YASQE)

Get accept header for this particular query. Get JSON for regular queries, and text/plain for update queries

YASQE.getAllVariableNames(YASQE: Doc, token: Object) → variableNames: Array

Fetch all the used variables names from this query

YASQE.getCompleteToken(yasqe: Doc, token: Object, cursor: Object) → token: Object

When typing a query, this query is sometimes syntactically invalid, causing the current tokens to be incorrect This causes problem for autocompletion. http://bla might result in two tokens: http:// and bla. We'll want to combine these

YASQE.hideCompletionNotification(doc: YASQE, autocompletionType: String)

Hide completion notification

YASQE.showCompletionNotification(doc: YASQE, autocompletionType: String)

Show notification