Home > Sparnatural form > form integration

Sparnatural Form integration and parameters reference

Constructor

Sparnatural Form is inserted as custom HTML element named sparnatural-form, with specific attributes. It looks like so:

  <sparnatural-form 
    src="sparnatural-config.ttl"
    form="form-specification.json"
    query="form-query.json"
    endpoint="https://dbpedia.org/sparql"
    lang="en"
    defaultLang="en"
    limit="1000"
    debug="true"
  />

HTML attributes reference

In a nutshell, Sparnatural Form requires 4 things to be configured:

• A Sparnatural query structure that will be executed when the form is submitted. This query structure can be arbitrarily complicated, although the user will see only a flat and simple form.
• A form specification, that binds variables from the query to fields in the form. When the user selects a value for a certain field, the value is injected in the corresponding variable in the query.
• The src configuration giving the underlying structure of the knowledge graph and the Sparnatural configuration. In particular this will contain the widget configuration used in the form
• The endpoint against which the queries are executed.

Attribute	Description	Default	Mandatory/Optional
src	identical to the equivalent Sparnatural attribute	undefined	Mandatory
endpoint	identical to the equivalent Sparnatural attribute	undefined	Mandatory
form	URL of a JSON file giving the specification of the form fields, following the form specification structure	undefined	Mandatory
query	URL of a JSON file giving the structure of the final query that the form will execute, with variables bounded to the values provided in the form. This file must follow the Sparnatural form query structure	undefined	Mandatory
catalog	identical to the equivalent Sparnatural attribute	none	Optional
limit	identical to the equivalent Sparnatural attribute	-1	Optional
lang	identical to the equivalent Sparnatural attribute en	Recommended
defaultLang	identical to the equivalent Sparnatural attribute en	Recommended
prefixes	identical to the equivalent Sparnatural attribute	none	Optional

Sparnatural Form events

“queryUpdated” event

The queryUpdated event is triggered everytime the query is modified. The event detail contains :

• The SPARQL string in queryString
• The JSON Sparnatural structure in queryJson

sparnaturalForm.addEventListener("queryUpdated", (event) => {
  console.log(event.detail.queryString);
  console.log(event.detail.queryJson);
});

“submit” event

The submit event is triggered when the search/export button is clicked.

In typical integrations, the state of the submit button can be updated upon submit. The submit button can be “not loading and active”, “loading” or “disabled”. The functions to update the state of the button are:

• sparnaturalForm.disablePlayBtn()
• sparnaturalForm.enablePlayBtn()

disablePlayBtn() should be called on submit event and enablePlayBtn() when the query has returned.

“init” event

The init event is triggered when Sparnatural form has finished initializing itself.

See the corresponding event in Sparnatural.

“reset” event

The submit event is triggered when the reset button is clicked. It can be used to empty or reset other part of the page, typically YasQE.

See the corresponding event in Sparnatural.

Sparnatural Form element API

TODO