SLC

Semantic Linked Components

Web Components that show linked data.

Query SPARQL endpoints, RDF files and Solid pods. Make charts from the results with a grammar of graphics. Connect tables, charts and process maps. Do all of this in HTML.

Start Tutorial Build a dashboard Examples
Live example: the first steps of 40 purchase orders in a sankey chart.

What is SLC?

SLC is a set of custom elements. One element tells where the data is. One element contains the SPARQL query. Other elements show the result. The library fetches the data, runs the query in the browser and updates each view. If you can write HTML, you can make a linked-data page without a framework.

Data sources

SPARQL endpoints, Turtle and other RDF files, Solid pods with login, and link traversal. The queries run in the browser with Oxigraph (WASM) or Comunica.

Views in HTML

Tables, bar, line, area, scatter, pie, heatmap and box-plot charts, maps, timelines, sankey charts, process maps and KPI cards. Each view is an HTML element with some attributes.

A grammar of graphics

<slc-chart> makes a chart from marks, encodings, scales and transforms. The same specification is also available as JSON, YAML and RDF. Thus you can keep charts in a pod.

Connected views

Named selections connect the elements. Click a bar, select a range or push a filter button: each view with filter-from shows the same selection. A selection can also be a query parameter.

Process mining

Process maps with coverage sliders, variants, performance spectra, conformance to a target model, and case timelines. The input is an event log in RDF.

Themes and accessibility

One set of --slc-* design tokens sets the style of all elements, in light mode and dark mode. You can operate all controls with the keyboard. On touch screens, the controls are 44 px high.

Start

The packages are not on npm. Download the tarballs from the GitHub releases. Or clone the repository and run the demos on your computer (Node.js 22).

1. Install

npm install ./sparql-web-component-2.1.0.tgz

2. Load the elements one time

import "sparql-web-component/browser";

3. Write HTML

<bar-chart data-json='{"vars":["fruit","n"],"bindings":[…]}'
           x-axis="fruit" y-axis="n"></bar-chart>
Run the demos from the source code 
git clone https://github.com/dorschre/06-semantic-linked-components-for-a-solid-dataspace.git
cd 06-semantic-linked-components-for-a-solid-dataspace
npm install
npm run dev   # then open http://localhost:5173/

Tutorial

All examples below are live. Read the code. Then select Edit, change the code and select Run (or push Ctrl + Enter). The data is a synthetic purchase-to-pay log in Turtle. The log comes with this page, thus all examples work offline.

1 A chart from data

Each view uses SPARQL results: a list of variables and one binding for each row. Put the results in the data-json attribute. Then give the names of the fields to show.

2 Query RDF

A query element fetches RDF and runs SPARQL in the browser. In this example, <wasm-query> loads a Turtle file into Oxigraph. The chart refers to the query with source-id. The chart draws again when new results come in. To query a SPARQL endpoint, replace resources with endpoint.

3 One query, many views

Many views can show the same results. A table can sort, filter and export the rows. A pie chart shows the parts of a total. The views only draw the data, and the query runs one time.

4 The grammar of graphics

<slc-chart> makes a chart from parts: a mark, encodings, scales and transforms. An encoding connects a field to a channel. Change type="bar" to point or line, or add a color encoding.

5 Connected views

Controls write a named selection. Views with filter-from use that selection. The buttons select a vendor. The slider selects a range of throughput times. The table shows the cases that agree with both selections.

6 Process maps

An event log has one row for each event: a case, an activity and a time. A process map shows how the cases move between activities. Use the sliders to hide rare steps. Click an activity to see where its cases come from and where they go.

7 Pipelines and parameters

<slc-document> declares a full pipeline: sources, datasets, queries and views. A SPARQL CONSTRUCT with parameters can make a dataset. A slider can set a parameter. When you release the slider, the dataset makes the graph again. In this example, the graph keeps only the cases that are longer than the number of days that you select.

8 One specification, four forms

Each element is also data. In the gallery and on the demo pages, a switch above each example shows the element in different forms. The forms are its HTML, its IR (JSON) and the IR as RDF (Turtle). You can keep the RDF in a pod and load it again. Try it on this chart:

9 Themes

Elements read --slc-* custom properties. Set them on a parent element. The data colours have names for their roles (--slc-data-primary, -positive, -negative, …). If you change the palette, each colour keeps its meaning.

Build a dashboard

A dashboard answers some frequent questions on one screen: What is the status? What changed? Where must I look more carefully? An SLC dashboard uses the same HTML as above, in a clear layout. Queries fetch the data, and key figures and charts show it. Filters and parameters let the reader decrease the data, and notes tell where it comes from.

A dashboard in tiers: the overview is at the top and the details are below it.

Plan the dashboard before you write HTML

  1. Who reads it, and what do they decide? One dashboard is for one audience. Write their three to five questions.
  2. Which numbers answer the questions? Each question becomes one SPARQL query. The query calculates the aggregates in the database, not in the page.
  3. How does the reader judge each number? Compare it with a target, a threshold or the previous period. A number without a reference gives little information.
  4. What can the reader change? Filters show fewer of the rows that are loaded. Parameters run a query again. Keep both in the URL, so that readers can share a view.
  5. Can the reader trust it? Give the name of the source. Show when the page received the data. Give a definition for each term that has two meanings.
To…UseStep
show a key number with a target or trend<slc-kpi-card>, <slc-kpi-meter>1
put widgets in tiers, groups and columns<slc-grid>, <slc-panel>2
explain a view, show a reference, give the sourceheading, caption, <slc-annotation>, <slc-note>, <slc-source-note>3
click a chart to filter the other viewsselect-name + filter-from, <slc-quick-filter>4
show details only after a selection<slc-selection-detail>, <slc-list>5
let the reader run queries again with other values<slc-param-select>, <slc-query-parameter>6
put views in tabs and keep the state in the URL<slc-tabs>, <slc-url-state>7

Step by step

These steps make a purchase-to-pay dashboard. They use the same synthetic log as the tutorial. You can edit and run each example. Step 7 puts all of them together.

1 Start with the key figures

An aggregate query gives one row. Each card shows one field of that row. Give each number a reference. target sets the goal. good-direction="down" tells that a lower value is better. The thresholds of the meter make it red, amber or green.

2 Make the layout

<slc-grid layout="stratified"> puts the widgets in order from overview to detail. Use tier="top" for small key figures, "middle" for charts and "bottom" for details at full width. <slc-panel> puts related items in a group with a heading. collapsible and max-height limit the height of long content. On screens narrower than 720 px, the grid has one column.

3 Explain the data

Readers trust a number when they know its context. heading and caption give a title and a description to a view. <slc-annotation> draws a reference line, and info adds an ⓘ hint to a card. <slc-note> gives the definition of a term. <slc-source-note> tells where the data comes from and when the page received it. Its refresh button runs the query again.

4 Connect the views

Click a bar. The chart writes the vendor into the selection d4-vendor (select-name, select-field). The table has this selection in filter-from, thus it shows only the orders of that vendor. The status buttons write a second selection. filter-combine="intersection" keeps the rows that agree with both selections. Filters use rows that are already loaded, thus the result shows immediately.

5 Show details on request

A dashboard is easier to read when it shows details only on request. Select a row. The table writes the order into d5-order, and the list shows the events of that order. <slc-selection-detail> shows the detail panel only while an order is selected.

6 Run queries again with parameters

A filter hides rows that are loaded, but a parameter changes the query. <slc-param-select> writes the parameter d6Vendor. Each query with a related <slc-query-parameter> runs again, with the value in ?vendor. Thus the key figures show the values of one vendor. "All" makes the parameter empty, and the query has no limit. Use parameters when the data is too large to load at one time, or when the aggregates must change.

7 The full dashboard

This is the full dashboard. It has a vendor parameter at the top, key figures, an overview in tabs, details on request and the source at the bottom. <slc-tabs> writes the visible tab into the parameter dashView. <slc-url-state> keeps both parameters in the address bar. Select a vendor and a tab. Then load the page again or share the link: the dashboard opens with the same vendor and tab.

Before you publish

  • Each number has a label, a unit and a reference (target, threshold or trend).
  • When charts show the same category, they use the same colour for it.
  • Each view tells what it shows. The page gives the name of its source and the age of the data.
  • You can see the most important figures on the first screen, also on a phone.
  • Filters and tabs stay the same when you load the page again. Put them in <slc-url-state>.
  • Private data stays in the pod of the reader. Query it after the <solid-auth> login. Do not copy it.

Go further

PatternsPattern galleryAll 43 dashboard design patterns. Each pattern is a live example with its HTML. DashboardHealth overviewA full dashboard of public pod data: key figures, trends and tabs. DashboardExperiment resultsVerdicts, gauges, small multiples and semantic detail pages. Process miningProcess explorerAn analysis dashboard for the event log of the examples above.

The design patterns come from Bach et al., Dashboard Design Patterns (IEEE VIS 2022). In the repository, docs/patterns/ shows the elements for each pattern.