Documentation
YASHE 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 YASHE offers (in addition to the CodeMiror API).Note: Where CodeMirror provides
CodeMirror
in the global namespace, we provide YASHE
.
Getting Started
Initialize YASHE via its constructor, or via the command fromTextArea
. Both return in instance of YASHE, from now on referred to as yashe
(lowercase). Both function take as argument a config object. See the section on defaults for more information on this config object.
YASHE(parent: DOM-Element, settings: Object) → YASHE instance: yashe
Main YASHE constructor. Pass a DOM element as argument to append the editor to, and (optionally) pass along config settings (see the YASHE.defaults object below, as well as the regular CodeMirror documentation, for more information on configurability)
YASHE.fromTextArea(textArea: DOM element, config: Object) → YASHE instance: yashe
Initialize YASHE from an existing text area (see CodeMirror for more info)
Examples
API
API methods accessible via theyashe
instance
yashe.setValue(query: String)
Set query value in editor (see also)
yashe.getValue() → query: String
Get query value from editor (see also)
yashe.getDefinedPrefixes() → object:
Fetch defined prefixes
yashe.addPrefixes(prefixes: object)
Add prefixes to the query. The prefixes are defined as {"rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#"}
yashe.removePrefixes(prefixes: object)
Remove prefixes from query. The prefixes are defined as {"rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#"}
yashe.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
yashe.enableCompleter(completerName: String)
Enable an autocompleter with this name. Only makes sense if you've programatically disabled this completer before, as a plugin is automatically enabled when registering it (see this function)
yashe.disableCompleter(completerName: String)
Disable an autocompleter with this name.
yashe.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
yashe.collapsePrefixes(collapse: boolean)
Collapsing prefixes if there are any. Use false to expand them.
Statics
Static functions YASHEYASHE.registerAutocompleter(name: String, autocompleter: function)
Register an autocompleter in YASHE. This automatically enables the completer as well
YASHE.getCompleteToken(doc: yashe, token: Object, cursor: Object) → token: Object
When typing a shape, this shape 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
Configuration
This configuration object is accessible/changeable viaYASHE.defaults
and yashe.options
, and you can pass these along when initializing YASHE 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: PREFIX : PREFIX schema: PREFIX xsd: :User IRI { schema:name xsd:string ;schema:birthDate xsd:date? ;schema:gender [ schema:Male schema:Female ] ;schema:knows @:User* }
Shape string
autocompleters: array (default: ["prefixDefinition", "wikidata", "prefixesAndKeywords"])
The list of enabled autocompletion plugins (See this section on how to write your own)
syntaxErrorCheck: boolean (default: true)
Whether to validate the ShEx syntax
collapsePrefixesOnLoad: boolean (default: false)
Collapse prefixes on page load
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 YASHE editor is selected (has 'focus').
The list of shortcuts provided by YASHE:
[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]-Down
: Copy line down[Ctrl|Cmd]-Up
: Copy line up[Ctrl|Cmd]-Shift-F
: Auto-format/indent selected lines[Ctrl|Cmd]-S
: Save current content in local storageF11
: Set query editor full-screen (or leave full-screen)Esc
: Leave full-screen
persistent: function|string
Change persistency settings for the YASHE content 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 YASHE.determineId
function, to avoid collissions when using multiple YASHE instances on one
page
Writing an Autocompletion Plugin
To register an autocompletion, one needs to execute theYASHE.registerAutocompleter
function.
Below, we describe the autocompletion function in more detail, and the object it should return.
constructor(doc: yashe) → configurationObject: Object
Autocompleter constructor, which should return the object described below
get: function|array
Required
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
token: object
If 'bulk' loading is disabled, use this token to return the appropriate list of suggestions forcallback: function
If 'async' is enabled, return the suggestions by passing it on to this callback
isValidCompletionPosition: function() → boolean
Required
Check whether the cursor is in a proper position for this autocompletion.
preProcessToken: function(token: object|string) → token: object
Optional
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(token: object|string, suggestion: string) → string
Optional
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
Required
Specifies that the get function is asynchronous
bulk: boolean
Required
Use bulk loading of completions: all completions 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
Optional
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
Optional
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)
validPosition: function
Optional
Fires when a codemirror change occurs in a position where we can show this particular type of autocompletion
invalidPosition: function
Optional
Fires when a codemirror change occurs in a position where we can not show this particular type of autocompletion
Configuring Autocompletion Plugins
To modify how autocompletion plugins work, you can simply overwrite the settings and/or function that are explained in the section above. To e.g. modify theautoShow
setting for the prefix autocompleter, set `YASHE.Autocompleters.prefixes.autoShow = false` before you initialize YASHE.
Some plugins may come with extra configuration options such as the prefix autocompleter, that allows you to change the url from where the prefix json is fetched:
YASHE.Autocompleters.prefixes.fetchFrom: string (default: //prefix.cc/popular/all.file.json)
Where to fetch the prefix json from. Change this when you'd like to host the json yourself. This might be useful when you run YASHE on an `https` site, considering that prefix.cc currently does not support `https`