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 instance: yasqe
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 instance: yasqe
Initialize YASQE from an existing text area (see CodeMirror for more info)
API
API methods accessible via theyasqe
instance
yasqe.setValue(query: String)
Set query value in editor (see also)
yasqe.getValue() → query: String
Get query value from editor (see also)
yasqe.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
yasqe.getQueryMode() → string:
Fetch the query mode: 'query' or 'update'
yasqe.getQueryType() → string:
Fetch the query type (e.g. SELECT, ASK, DESCRIBE, CONSTRUCT etc)
yasqe.getPrefixesFromQuery() → object:
Fetch defined prefixes from query string
yasqe.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
yasqe.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 viaYASQE.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 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
Note: To avoid colissions with other browser shortcuts, these shortcuts only work when the YASQE editor is selected (has 'focus').
The list of shortcuts provided by YASQE:
[Ctrl|Cmd]-Space
: Trigger Autocompletion[Ctrl|Cmd]-D
and[Ctrl|Cmd]-D
: Delete current/selected line(s)[Ctrl|Cmd]-/
: Comment or uncomment current/selected line(s)[Ctrl|Cmd]-Alt-Down
: Copy line down[Ctrl|Cmd]-Alt-Up
: Copy line up[Ctrl|Cmd]-Shift-F
: Auto-format/indent selected lines[Ctrl|Cmd]-]
: Indent current/selected line(s) more[Ctrl|Cmd]-[
: Indent current/selected line(s) less[Ctrl|Cmd]-S
: Save current query in local storage[Ctrl|Cmd]-Enter
: Execute QueryF11
: Set query editor full-screen (or leave full-screen)Esc
: Leave full-screen
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
acceptHeaderSelect: String|function (default: "application/sparql-results+json,*/*;q=0.9")
Accept header for regular SELECT
queries
acceptHeaderGraph: String|function (default: "text/turtle,*/*;q=0.9")
Accept header for queries returning a graph (e.g. CONSTRUCT
)
acceptHeaderUpdate: String|function (default: "text/plain,*/*;q=0.9")
Accept header for update queries
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: true)
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 eitherYASQE.defaults.autocompletions.<name>
, yasqe.options.autocompletions<name>
, or as part of the configuration object passed during YASQE initialization.
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>"].
If used as a function, the parameters it receives are
doc: yasqe
The yasqe instancetoken: object
If 'bulk' loading is disabled, use this token to return the appropriate list of suggestions forcompletionType: string
The identifier for this type of autocompletioncallback: function
If 'async' is enabled, return the suggestions by passing it on to this callback
isValidCompletionPosition: function
Check whether the cursor is in a proper position for this autocompletion.
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
select: function
pick: function
close: function
Statics
Static functions YASQEYASQE.consumeShareLink(doc: yasqe, 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(doc: yasqe) → 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(doc: yasqe, token: Object) → variableNames: Array
Fetch all the used variables names from this query
YASQE.getCompleteToken(doc: yasqe, 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