AVAA Toolkit Developer Guide

Introduction

This guide is intended for developers wishing to extend $ATK functionalities via scripting. Knowledge of HTML and JS are required.

Annotations Formats

$ATK understands the following file formats

Architecture

Overview

While $ATK's core is made with JAVA, most features are actually implemented in javascript. All these scripts are stored in the scripts folder and processed when necessary as the XML-to-HTML conversion advances.

This modularity allows anyone to create custom scripts to extend $ATK and solve specific tasks, without the need for further core $ATK development.

Scripts of common utility could then be shared by their authors and benefit the community at large.

Implementing Views

Implementing Charts

Implementing Operations

Implementing Tags

Prerequisite

The following softwares are required and must be installed:

Installation

Simply extract the latest release zip

It is possible to add other XML folders to the editor by specifying their path as arguments (edit .bat file to see, check the cli arguments)

Update

When you already have $ATK installed and want to update it, follow these steps:

  1. Close $ATK if it is running
  2. Delete these folders: scripts, editor, tests
  3. Download the latest release zip
  4. From the zip, copy to your installation folder (replace existing) avaa-toolkit.jar, include, scripts, editor, tests
  5. Restart toolkit

Editor

An editor for $ATK's XML documents is available in the browser.

To begin, start $ATK by running the launcher, then navigate with your browser to avaa-toolkit.org
If you don't have internet, use the provided offline editor in your installation folder (open index.html)

XML Structure

$ATK will process XML files and convert them to HTML.
It expects a document with the following structure

Queries

$ATK is all about querying and filtering annotations. Inside the VIEW or CHART tag, you can build complex queries to extract only specific annotations. This is done via the SELECT tag, various attributes can be combined to select a curated list of annotations:

Attributes of type regexp (*-match) have additional options:

When multiple attributes are used, the selection will consist only of the annotations fulfilling all the constraints.

##scripts##

Styling

It is possible to change the style via CSS. The HTML code generated makes it easy to target specific elements or apply styling rules for the whole page. Each view has its own structure of elements, and a simple "Inspect Element" from browser will reveal selectors.

Embedded CSS

Styles can be defined directly in the XML file, by using a STYLE tag.

These styles will only apply to this specific HTML document.

<STYLE> .view-timeline td { border-color:red; } .view-timeline tr.tier-header { text-align:right; } </STYLE>

CSS File

Styles can be defined in a separate CSS file, that must be placed in the include folder.

All the generated HTML documents will load this file and have these styles in common.

e.g. my-styles.css h2 { color:green; } section { border-left: 2px solid gray; }

Styling Views

Views generate simple HTML code and try to follow common guidelines so that applying styles is straightforward

Annotations' text labels always have the annotation class, so for instance to change the color of all annotations:

.view .annotation { color:red; }

Making PDF

$ATK can also generate PDF, though interactive features like videos or dynamic charts won't work in this format, for obvious reasons.

Chrome (or Chromium) must be installed on the system, and the cli argument --pdf must be specified.

Chrome executable should be detected automatically, if that fails it is required to provide its path with the --chrome-exe argument.

If everything works correctly, a file.pdf should be generated along the file.html document.

Command Line

$ATK is made for the command line and can integrate seamlessly in any tool chain.

##cli##

Troubleshooting

Installation and first run

Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.UnsupportedClassVersionError:
    org/avaatoolkit/Main has been compiled by a more recent version of the Java Runtime (class file version 55.0),
        this version of the Java Runtime only recognizes class file versions up to X

Solution: Your version of java runtime is outdated, follow these steps


java.net.BindException: Couldn't bind to any port in the range `42042:42042`.
    at org.glassfish.grizzly.AbstractBindingHandler.bind(AbstractBindingHandler.java)
    at org.glassfish.grizzly.nio.transport.TCPNIOTransport.bind(TCPNIOTransport.java)
    at org.glassfish.grizzly.http.server.NetworkListener.start(NetworkListener.java:)
    at org.glassfish.grizzly.http.server.HttpServer.start(HttpServer.java)
    at org.avaatoolkit.server.Daemon.start(Daemon.java)
    at org.avaatoolkit.Main.main(Main.java)

Solution: The toolkit is already started with the --server argument, close it before running a new instance.
Solution: Your firewall has a strict policy regarding localhost port bindings, add a rule to allow localhost:42042

Custom Java Runtime

On some operating systems, the installed java runtime might not be up-to-date and prevent $ATK from executing properly.
To run $ATK, at least java 11 is required. To install a valid runtime only for $ATK:

  • Go to Open JDK and download the archive for your system
  • Extract the archive into $ATK installation's folder
  • Rename the extracted jdk-20.0.x folder to jdk
  • The folder tree structure should be avaa-toolkit / jdk / bin /
  • The launcher should now use the provided runtime in the jdk folder automatically

Scripting API

Overview

While $ATK is made with JAVA, most of the features (views, charts, operations, and tags) are actually implemented in sandboxed javascript. All these scripts are stored in the scripts folder and processed when necessary as the XML-to-HTML conversion advances.

This modularity allows anyone to create custom scripts to extend $ATK and solve specific tasks, without the need for further core $ATK development.

Scripts of common utility could then be shared by their authors and benefit the community at large.

Implementing Views

Implementing Charts

Implementing Operations

Implementing Tags