Visual Essay Tags

Text Formatting with Markdown

Visual Essay Tags

Essay visualizations are created (and optionally controlled) by a couple of special HTML tags that are added to the essay markdown text. Two HTML tags are currently used.

The param tag is used to define visualizations that are associated with an essay section or paragraph. The param tags all start on a new line and include attributes defining the specific visualization to create and all required options.
The span tag is used to wrap sections of text in the essay to associate the text with an entity or to use the text as a interaction trigger. An example of an interaction trigger would be connecting a location reference in the essay text to an interaction that causes the map to "fly to" a specific location when the user clicks on or hovers over the "spanned" text in the essay.

HTML tags begin with the < character and end with the > character. The text after the < character and before the first space define the tag name. The HTML language defines many tags but the visual essay tool only uses the param and span tags. Both of these are standard HTML tags that have been extended for use by the visual essay tool. In the case of the param tag a visual essay type attribute and optional options attributes are used to define the type of visualization generated. The visual essay type attribute starts with ve- and defines the specific component used to render the visualizaiton. Below are a few commonly used ve type attributes.

- ve-image
- ve-map
- ve-video

Visual Essay Meta Tags

The two tags in this section, the ve-config and ve-entity tags, do not directly correspond to a specific visualization but rather are used to provide general data that guides the overall rendering of the essay. The ve-config tag is used to define overall formatting and essay-level metadata such as title and author name(s). The ve-entity tag is used to identify entities (people, locations, organizations, taxon elements, etc) that are referenced in or otherwise applicable to the essay text. Data associated with entities identified by a ve-entity tag is retrieved from an external knowledge graph.

Config - A Config tag (ve-config) is added to an essay to define essay-specific attributes, metadata, and behaviors. For example, this tag is often used to define a title and banner image for an essay.
Entity - TODO

Visual Essay Component Tags

The tags in this section are used to declare and configure one or multiple visualizers that are associated with an essay section or paragraph.

Graphic - The Graphic tag (ve-graphic) is used to display images that do not require IIIF capabilities, such as JPG and PNG files, as well as GIFs and SVG.
IFrame - The Iframe tag (ve-iframe) is used to embed any arbitrary web page into the visualization viewer.
Image - The Image tag (ve-image) is used to display an image file (.jpg or .png) in an International Image Interoperability Framework (IIIF) viewer.
Knightlab Timeline - The Knightlab-Timeline tag (ve-knightlab-timeline) displays an interactive timeline visualization developed using [Knight Lab utilizes TimelineJS](https://timeline.knightlab.com](https://timeline.knightlab.com), an open-source tool that enables anyone to build visually rich, interactive timelines.
Map - The Map tag (ve-map) tag can be used to add an interactive map (using the Leaflet library) to the essay with multiple options provided for custom overlays, including GeoJSON feature layers and georeferenced images. Map overlays are added using the ve-map-layer tag.
Map Layer - The Map Layer tag (ve-map-layer) is used to add an overlay (layer) to an interactive map that is added using the ve-map tag.
Network - The Network tags (ve-vis-network, ve-d3plus-network, and ve-d3plus-ring-network) are used to display interactive network graphs.
Plant Specimen - The Plant specimen tag (ve-plant-specimen) is used to display a high resolution image for a plant type specimen retrieved from the Global Plants database.
Table - The Table tag (ve-tablulator) displays tabular data in an interactive component that supports data sorting. Delimited text files (comma or tab separated values) are used for input.
Video - The Video tag (ve-video) provides viewing of streaming video from services such as Youtube.