Special Nodes reference¶

This page describes every Special Node of the story editor: what it does, how to fill it in, what ends up in the Markdown, and what to check when testing it. Each one has a ready-made example in Example stories, with a .lodeon.zip to import into the editor.

Most nodes that read data offer a choice of Source. SPARQL result always runs a query against the node's profile. The query runs in the editor when you press Run, and either again when the story is read or never again, depending on the node:

SPARQL Query¶

Shows: a SPARQL query and a table of its results. Example: story/sparql-query.

In the editor:

• Write the query in the code editor and press Run. The table can be paged, searched, set to 10–1000 (or all) rows per page and downloaded as CSV.
• The node uses the profile that was selected in the top bar when you inserted it.
• If the profile has a Sparnatural configuration, the node also has a Visual Query Builder button. Build the query by choosing classes and properties, then Use query to copy the generated SPARQL into the node. You can keep editing it by hand afterwards.

On the published page, the reader's browser runs the query again through /api/sparql/<profile> and shows the results in a sortable, paged table.

Test: the table appears; IRIs link to resources; changing the query and pressing Run in the editor changes the result; Preview shows the same table.

Plotly Visualization¶

Shows: an interactive Plotly chart. Example: story/plotly.

Sources:

Chart types: table, bar, horizontal bar, grouped bar, stacked bar, line, area, pie, scatter, bubble, histogram, box plot, heatmap, treemap, sunburst, Sankey, timeline and map. The editor guesses which columns to use (x/y, label/value, colour, size, lat/lon, …), and you can change the mapping. The Data, Layout and Config tabs show the Plotly JSON, which you can edit freely, for example to set axis titles or colours.

The finished figure is stored in the story. Readers see the chart without the query being run again.

Test: switch chart types; edit the layout JSON (for example "title": {"text": "…"}) and see the chart change; hover, zoom and download the chart as PNG on the published page.

RAWGraphs Visualization¶

Shows: a chart made with RAWGraphs, as SVG. Example: story/rawgraphs.

1. Make a chart in RAWGraphs and use Save project to download a .rawgraphs file.
2. In the node, upload the file (RAWGraphs project file) or paste its JSON (RAWGraphs project JSON).
3. The editor renders the chart with RAWGraphs' own code and stores the SVG.

The node shows a summary: chart type, number of rows and columns. Readers see the stored SVG.

Test: change visualOptions (for example the width or height) in the project JSON and render again; paste a project of another chart type (alluvial, treemap, …).

Leaflet Map¶

Shows: a Leaflet map with markers, lines and areas. Example: story/leaflet-map.

Sources:

Settings: Tile layer (map background), Height, Initial view (Fit map to data, or Configured center and zoom), Cluster points, Show legend with title and position, Popup fields, and the marker radius, colours, opacity and border width. Markers are coloured by category.

The features are stored in the story. Readers don't run the query.

A Wikidata query for a map: the collections that hold paintings by Rembrandt, coloured by country.

SELECT DISTINCT ?resource ?label ?geometry ?category WHERE {
  ?painting wdt:P170 wd:Q5598 ;       # created by Rembrandt
            wdt:P31 wd:Q3305213 ;     # a painting
            wdt:P195 ?resource .      # in the collection of
  ?resource wdt:P625 ?geometry ;      # coordinates (WKT)
            wdt:P17 ?country .
  SERVICE wikibase:label {
    bd:serviceParam wikibase:language "en".
    ?resource rdfs:label ?label .
    ?country rdfs:label ?category .
  }
}

Test: popups show the chosen fields; the legend lists the categories; clustering groups nearby markers; fit map to data frames all features.

Graph Explorer¶

Shows: an interactive network (D3) of resources and their neighbours. Example: story/graph-explorer.

Sources:

• Direct resources: one or more IRIs (or blank-node labels).
• SPARQL result: a query; set the IRI variable (default resource) and the Label variable (default label).

Settings: Direction (outgoing, incoming, both), Depth, Max nodes, Max edges per node, show Predicate labels, Literals, Types and Blank nodes, Color scheme, Height and Caption. Defaults come from the profile's graph_explorer: settings.

On the page, readers click a node to expand it. SHMARQL fetches the neighbours through /api/explorer/<profile>/expand. You can zoom, pan, drag nodes (they stay where you drop them), toggle predicate labels and go fullscreen. Hovering a node shows its label, IRI and type.

Test: the start node appears; clicking expands it; the direction setting is respected; fullscreen and zoom buttons work.

IIIF Object¶

Shows: deep-zoom images (OpenSeadragon) from IIIF resources. Example: story/iiif.

Sources:

• Direct URL: one or more IIIF Presentation manifests or Image API info.json URLs, one per line.
• SPARQL result: a query returning ?manifest or ?imageInfo, with optional ?label and ?resource. Wikidata has many manifests under property wdt:P6108 (IIIF manifest URL).

Settings: View and Gallery strip, Height and Caption. Single object shows one image (the first image of a manifest, or the selected result). Gallery shows all images of all results in sequence, with previous/next buttons and a reference strip (horizontal, vertical or none). Manifest labels and rights statements are shown when available.

Images are never copied into the story. The reader's browser loads them from the IIIF server, which must therefore allow cross-origin requests (CORS) and use HTTPS. Allowed servers are set by nodes.iiif.originPolicy in the LODEON settings (all HTTPS servers by default).

Test: the image loads and zooms; in gallery view the strip and the previous/next buttons switch images.

Embed Remote Content¶

Shows: a page from another website in a frame (<iframe>). Example: story/embed.

Sources:

• Direct URL: one or more URLs, one per line.
• SPARQL result: a query returning ?embedUrl, with optional ?label and ?resource.

Settings: View (Single object or Gallery), Gallery strip, aspect ratio (16:9, 4:3, 1:1 or custom with a height), loading (lazy or eager) and Caption.

Only sites listed in nodes.embed.allowedOrigins (in the file named by LODEON_CONFIG_PATH) are shown. Any other URL shows a warning instead. The frame's sandbox and allow permissions also come from those settings. By default the list is empty, so no embeds are shown until the site operator allows an origin. The example configuration allows the Wikidata Query Service, whose embed.html page shows query results as a table, map, chart, timeline or graph.

Test: an allowed URL shows; a URL of another site shows the warning; the gallery strip switches frames.

Media Asset¶

Shows: an image, audio or video file that is part of the story. Example: story/media-asset.

Upload a file into the node: JPEG, PNG, WebP or GIF images; MP3, M4A, OGG, WAV or WebM audio; MP4 or WebM video. The file is stored in the browser with the project, exported in the assets/ folder of the .lodeon.zip, and published next to the story (assets/images/…, assets/audio/…, assets/videos/…).

Metadata is edited in tabs: title, alternative text, caption, description, creator, date, source, licence, rights and more. Embedded XMP metadata is read from images. A caption line is built from the main fields. Switch on Display extended metadata to also show a collapsible table with all fields.

The asset overview in the metadata panel lists the media files stored with the project.

Test: the image shows with its caption and links to its source; the extended metadata table opens; the file is in the exported package.

Music Notation¶

Shows: engraved music, rendered by Verovio, with playback. Example: story/music-notation.

Sources:

• Direct input: paste MEI or Plaine & Easie code (PAE, the notation of RISM incipits). The format is detected automatically; add a label and a resource.
• Text file: upload an .mei or .pae file.
• SPARQL result: a query that returns ?data (the notation), and optionally ?format, ?label, ?resource and ?resourceLabel. Other variables can be shown as metadata.

Settings: View (single, list, grouped by resource, or compare two items side by side), Document layout (responsive or paginated), Initial zoom, Visible metadata fields, Caption, and for playback the speed, volume and loop. In compare mode you choose two items, a playback sequence and optionally a target key to transpose to.

The notation is checked by Verovio in the editor, and stored in the story. Readers' browsers engrave and play it.

A PAE example (Frère Jacques):

@clef:G-2
@keysig:
@timesig:4/4
@data:4'CDEC/CDEC/EF2G/4EF2G/

Test: the score is engraved; play, pause and the tempo work; zoom works; an invalid input shows a validation message.

Story Metadata¶

Shows: the story's metadata as a box in the text: contributors with affiliations and identifiers, description, keywords, language, licence, persistent identifiers, publishing date and a download link to the project ZIP. Example: story/story-metadata.

The node has only a title. Its contents come from the metadata panel and are filled in when the Markdown is written, so publish again after changing the metadata. Fields that are switched off in the metadata panel configuration are left out.

Test: all filled-in fields appear; changing a contributor changes the box in Preview; the download link works after publishing with Publish Story ZIP.