SemwidgJS / Docs

Documentation

On this page, we provide a documentation on the SemwidgJS library. We give information about the three types of SemwdigJS elements: configuration elements, widgets, and templates.

Table of Content

  1. Configuration Elements
    1. Endpoint
    2. Resource
    3. Namespace
    4. Mapping
    5. Proxy
  2. Widgets
  3. Templates
    1. Template Definition
    2. Template Instance

1. Configuration Elements

Every configuration element is defined by several data-* attributes of an HTML element. Typically, this HTML element is a div or span element. The type of the configuration element is defined by the data-* attribute data-sw-config and a type name as value: endpoint, resource, namespace, mapping, or proxy. Other properties are defined by data-* attributes depending on the type of the configuration element. Mandatory attributes are marked by "(*)".

1.1. Endpoint

An endpoint configuration element specifies the access to a SPARQL endpoint by the following parameters:

data-swp-id: (*) A unique value that identifies the configuration element. Resource elements can use this value to link to a SPARQL endpoint.

data-swp-url: (*) The URL of a SPARQL endpoint. Typically, the URL ends with '/sparql'. It is recommended to omit the http(s) part of the URL. This way, the browser will use the same protocol for the endpoint as for the website itself. Using different protocols will result in errors.

data-swp-default-graph-uri: The default graph URI used for sparql requests.

data-swp-default-lang: The default language of the endpoint. This value is used by the WYSIWYG editor to request informtion for code completion.

data-swp-proxy: The id of a proxy element, or the values none (same as empty), or default.

data-swp-default: True or False. Defines if an endpoint is the default endpoint that will always be used, when no specific endpoint is defined within a query or widget.

Additional Information

Before executing a query, SemwidgJS will search for the endpoint specification to use at the following places in this stated order:

  1. Main resource of the query
  2. Widget parameter specific endpoint
  3. Widget specific endpoint
  4. Default endpoint of the page

Example

<div data-sw-config="endpoint" 
     data-swp-id="dbpedia" 
     data-swp-url="//dbpedia.org/sparql" 
     data-swp-default-graph-uri="http://dbpedia.org" 
     data-swp-default-lang="en"
     data-swp-proxy="none"
     data-swp-default="true">
</div>

1.2. Resource

A resource configuration element specifies a resource of a SPARQL endpoint by the following parameters:

data-swp-id: (*) A unique value that identifies the configuration element. This value can be used within SemwidgQL queries as an interchangeable placeholder variable instead of a fixed resource.

data-swp-uri: (*) The URI of a resource.

data-swp-endpoint: (*) The id of the endpoint to use. Since this configuration element is associated with an endpoint, it is not necessary anymore to specify the endpoint as an additional parameter within the widget.

Changing the data-swp-uri value will automatically cause all widgets that make use of this resource to reload its content, taking the changed resource into account.

Example

<div data-sw-config="resource"
     data-swp-id="university"
     data-swp-uri="http://dbpedia.org/resource/University_of_Duisburg-Essen"
     data-swp-endpoint="dbpedia">
</div>

1.3. Namespace

A namespace configuration element specifies a namespace that can be used in SemwidgQL queries by the following parameters:

data-swp-id: (*) A unique value that identifies the configuration element and acts a prefix in SemwidgQL queries.

data-swp-uri: (*) The URI of a namespace.

According to the following example, instead of writing http://dbpedia.org/resource/University_of_Duisburg-Essen in a SemwidgQL query, we could now write dbpr:University_of_Duisburg-Essen.

Example

<div data-sw-config="namespace"
     data-swp-id="dbpr"
     data-swp-uri="http://dbpedia.org/resource/"
</div>

1.4. Mapping

A mapping configuration element defines a mapping between a parameter - usable in SemwidgJS widgets - and a specific value. When processing a widget, all mapping parameters are replaced by the corresponding value. For instance, mappings can be used to change the language of the queried texts of all widgets on a page. The element is specified by the following parameters:

data-swp-id: (*) A unique value that identifies the configuration element and acts as the parameter in SemwidgQL queries that is replaced during widget processing. In queries this id must be enclosed in double $ signs (e.g. $$language$$).

data-swp-value: (*) The value by which the parmaeter (id) should be replaced during widget processing.

Changing the data-swp-value value will automatically cause all widgets that make use of this mapping to reload its content, taking the changed mapping value into account.

Example

<div data-sw-config="namespace"
     data-swp-id="language"
     data-swp-value="en"
</div>

1.5. Proxy

A proxy configuration element specifies the access to a proxy server that forwards the query to a SPARQL endpoint. This is necessary for SPARQL endpoints without CORS enabled. These endpoints cannot be queried by JavaScript directly as it violates the same-origin policy of the browser. This element is specified by the following parameters:

data-swp-id: (*) A unique value that identifies the configuration element.

data-swp-value: (*) The URL of the proxy server.

When an endpoint requires a proxy server, SemwidgJS will send a request to this server that is similar to the regular request but appends the parameter url to the list of POST parameters. This parameter contains the SPARQL endpoint URL to which the proxy server should forward the request.

Example

<div data-sw-config="proxy"
     data-swp-id="myProxy"
     data-swp-url="https://example.com/proxy.php"
</div>

2. Widgets

Every widget is defined by several data-* attributes of an HTML element. Typically, this HTML element is a div or span element. Depending on the widget's type, it might also be possible to use e.g. a h1 element to make use of the predefined css styles for this element. The type of the widget is defined by the data-* attribute data-sw-widget and a type name as value, e.g.: SwText, SwImage, or SwOpenStreetMap. Widget properties are defined by data-* attributes. Which properties are available depends on the widget type, but a set of them is avaliable for every widget. For a complete overview visit the SemwidgJS widget documentation.

Basic Widget Properties

Each widget has the following data-* attributes:

data-swp-id: Unique identifier in SemwidgJS and HTML.

data-swp-endpoint: Default endpoint to use, if neither query nor value property define an endpoint.

data-swp-styleclass: CSS class name(s) applied to HTML.

data-swp-style: CSS styles applied to HTML.

data-swp-title: Title attribute applied to HTML, typically mouse over text.

data-swp-other: All other possible HTML attributes. Value of "other" will be inserted into HTML as it is entered.

data-swp-refresh: Refresh Interval for widget property. SemwidgJS uses Later.js for parsing textual interval descriptions.

data-swp-limit: Number of maximum results for a query.

data-swp-cache: The duration query results will be cached. Minimum: 1 minute, Maximum: 7 days.

data-swp-value: Value to display in HTML document. Typically, this is the most important property of every widget.

Widget Property types

Widget properties are classified by four types:

fixed: Once a value was set for this property, it cannot be changed anymore. For instance, this applies for data-swp-id.

static: These properties cannot contain a query but only a regular string value. For instance, this applies for data-swp-endpoint

query: These properties can contain SemwidgQL and SPARQL queries, but also static text or a combination of all these. Most properties belong to this type. Each property of this type creates several additional properties. These properties are listed in the next section.

selector: Selectors are used by interactive widgets (such as the SwInputText widget) that are able to write data to other SemwidgJS elements. The selector describes to which element and to which property the data should be written. For instance, university.uri would select the resource from the previous Resource example and would allow a widget to change its uri value.

Additional Query Properties

For each widget property of type query several additional properties specific attributes exist. Replace the * by the corresponding query parameter suffix (e.g. data-swp-value-endpoint).

data-swp-*-endpoint: Endpoint to use, if query does not define an endpoint.

data-swp-*-order: Comma-separated list of indices and optional order direction. Example: last - 1 asc, last desc

data-swp-*-selector: A selector function.

data-swp-*-transform: A transform function.

data-swp-*-refresh: Refresh Interval for widget property. SemwidgJS uses Later.js for parsing textual interval descriptions.

data-swp-*-limit: Number of maximum results for a query.

data-swp-*-cache: The duration query results will be cached. Minimum: 1 minute, Maximum: 7 days.

Example

<div data-sw-widget="SwLabel"
     data-swp-id="SwLabel-Temperature"
     data-swp-refresh="every 1 minute on the 5th second"
     data-swp-style="font-weight: bold; font-size: 150%; color: #666;"
     data-swp-value="{sensor.^intsys_prop:sensor(intsys_prop:type = 'Temperature').[intsys_prop:measuredAt(@timestart = 'now - 15 min'), intsys_prop:value]} °C"
     data-swp-value-endpoint="sensor_db"
     data-swp-value-limit="2"
     data-swp-value-order="last - 1 desc">
</div>

3. Templates

3.1. Template Definition

3.2. Template Instance

TODO