command API

The Conzept Command API is a LIPS scheme based domain-specific language (DSL) interface, for accessing various Conzept capabilities.

The API is currently being used for:

  • Auto-creation of presentations for topics.
  • Various bookmark-selection actions.

goals

  • Provide an easy environment for creating entity and media processing workflows in Conzept.
  • The DSL should be usable for:
    • Data visualization (some support: list, 2D/3D map, network graph, images, …)
    • Storytelling (some support: presentations, object fragments)
    • Education (not supported yet, ideas: gradual learning, experiences and quizzes)
    • Data analysis (not supported yet, ideas: statistical plots, heatmaps, etc.)
  • Design priorities:
    • useful
    • intuitive, simple, elegant
    • composable, coherent
    • robust, durable
  • Aimed at Wikidata (but could perhaps also made suitable for use with other SPARQL-endpoints in the future)

getting started

You can start building and running Conzept commands by opening the command-editor (located in the tools-tab).

Then execute the commands:

  • By typing: [CTRL] + [ENTER]
  • Or by clicking the ▶ run button

Open your browser console, to see any logging (if needed).

Check this example to get started: (show 'topic '( Q333 ) )

Autocompletion of the Scheme-based command-language symbols (including the Wikidata properties and entities) are available by pressing: [CTRL] + [SPACE] (note: there are still some autocomplete and editing issues)

commands

system commands

data fetching commands

data rendering commands

  • text-to-speech
    • (say "All that glisters is not gold") (speak some text)
    • (say 'Q206400) (speak a Wikipedia-article using an entity ID)
      • note: currently there is no UI for controlling the command-API TTS-speaker, but any other TTS-buttons in the UI can stop the speaking, or simply close the tab)

presentation commands

presentation example

Presentations can be constructed using the commands: presentation, slide and fragment. 

( presentation

  ( slide  "title 1"
    ( <list-of-fragments-and-commands> )
  )

  ( slide "title 2"
    ( <list-of-fragments-and-commands> )
  )
  
)

Each slide can contain multiple commands, but most of the time you should only use one-command per slide (so these commands don't interfere with each other). You can use multiple fragments per slide.

Fragments can contain Markdown text. A special link-shortcut syntax is available when linking to Conzept by entity ID: 

( fragment "aka [\"Devil's Bible\"](Q212180)" )

The presentation can contain “meta-data”, such as:

  • background (All the RevealJS background types, except color-names, are supported).
  • color (Any valid CSS color)
  • autoslide (Slide-timer in milliseconds. This also makes the slide fragments show at once.)

Example: 

( presentation
 ( set '( 'background "https://conze.pt/app/explore2/assets/video/backgrounds/005.mp4" ) )
 ( set '( 'color "#ffffee" ) )
 ( set '( 'autoslide "20000" ) )
 ( slide "Universe"
   ( show 'topic '( Q1 ) )
 )
 ( slide "Milky Way galaxy"
   ( show 'topic '( Q321 ) )
 )
 ( slide "Sun"
   ( show 'topic '( Q525 ) )
 )
)

Slides can contain action commands (for data fetching, rendering, etc.) and fragments (which are on or more click-through elements on a slide).

Fragment syntax: 

( fragment "[plaintext|markdown]" "<goto:[seconds|text|index|...]>"

Simple fragment example:

Fragments examples with “goto-triggers” (FIXME):

presentation examples

  • Auto-generation of topic presentation (work in progress)

notes

  • Implement correct URL-parameter quoting for these special-characters: ? & # > < (double encoding needed?)
  • Todo: Create a “meta-object format” for attribution and other things (see also: Dublin Core)
    • copyright license
    • copyright owner(s)
    • creators(s)
    • publisher(s)
    • title
    • description
    • date
    • attribution link
  • Improve editor experience
    • Autocomplete:
      • Can we use autocomplete for multi-words (strings containing spaces)?
      • Make property-autocomplete results have a higher priority (as there are fewer of them)
      • The Ace-editor should not cancel the autocompletion, when it runs out of local options! (leave it open and let the user type)
      • Add autocompletion for the custom function-names
      • See also: federated-sparql-search-widget - SPARQL-store source-selector and autocomplete example
    • todo:
      • highlight entities?
      • add presentation/section/fragment button? allow for right-click insert?
  • Presentation issues:
    • BUG: in fullscreen the autocomplete-menu is not visible
    • BUG: slow loading pages may overwrite next slides/actions (especially when the user clicks quickly on “next slide”)
      • todo: research ways how to prevent this render-output clobbering.
    • BUG: Ace-editor: sometimes there are only a few lines visible in the editor!??
    • BUG: Parentheses in background-color/gradient strings are stripped.
    • research: How to auto-create an 'interesting' presentation from just a topic ID (optionally with an “topic lens” definition, to give some more semantic direction).
    • Could we make truly multi-lingual presentation text using Bergamot? (client-side translation)
  • Add Schema.org “potentialAction” command-links to JSON-LD (if useful).
  • Assess any security implications from running command-URLs code.
    • What are the potential risks?
    • How can these risks be minimized (if serious): CSP rules, …?
  • Research DSL workflow for more complex query-output-types:
  • Audio-waveform app:
    • Add start-time / start-end-time URL-parameter support
    • Allow a user to right-click to copy: start-time (in seconds) or start-end-time (in seconds)
  • Chemical command:
    • Generally note: This is an interesting topical DSL example.
    • Add support for using an entity-ID (besides the PubChem Cid)
    • Could we handle multiple elements?
    • Expand range of supported chemical structures, properties and relations: proteins, genes, gene pathways, etc.?

revealjs docs

deeplinking