Standalone Client User Guide

The Zegami standalone client allows enterprise customers to leverage the powerful data visualisation and exploration of Zegami from within their own web based applications. The purpose of this document is to guide software engineers and system integrators through the process of installing and configuring Zegami within their application.

Test install of demo Zegami collection #

The zegami zip package contains everything needed in order to get started, including example collections to help with configuration. The package has the following contents:

  • Zegami
    • 📄 zegami.min.js – JavaScript source code for Zegami
    • 📄 zegami.css – CSS including inline logo
    • 📄 EULA.txt – End user licence agreement
    • 📁 img – Required images
    • 📁 example-theme
      • 📄 theme.css – Theme file – send your version to
    • 📁 examples
      • 📁 licenses – Licences collection with third party open source licence types for all bundled software
        • 📄 zegx.xslt
        • 📄 licenses.json
        • 📄 index.html
        • 📄 config.json
      • 📁 diversity
        • 📄 index.html – Example entry point html file
        • 📄 diversity.xslt – Example XSLT
        • 📄 diversitylsit-worldwide-grid.tsv – Example TSV file
        • 📄 config.json – Example config

To get started, host the bundle on a webserver or should you wish to test on your local machine using a local development web server, like servez, http-server, Visual Studio or a different local web server. You will need to make the root folder the entrypoint.

Navigate to: localhost:[port]/examples/diversity/index.html
Alternatively you can just right-click on the index.html file and click open with Mozilla Firefox (Other browsers do not
do this)
Once you load the index.html web page it should look like this:

Standalone client grid view

This collection is loading the config.json file from the /examples/diversity folder. The config file itself is then pointing the collection at the tsv and xslt files in the same folder as described in the config section below.

Open Source Licences #

EULA.txt is included in the zip package. The open source licenses are explorable as a zegami collection at /zegami/examples/licenses/index.html. This collection allows you to see which license kinds are used and what the links are to github/npm.

Set up data and config APIs for Zegami Client #

The Zegami client loads data in the following sequence:

  1. The index.html page with JavaScript and css is loaded by the browser
  2. Zegami.start is called and expects a div with class="zegami-container" to exist in the body Zegami.start( config ); Config can either be provided as a JavaScript object. Alternatively, if the config object contains a field called configUrl, the config will be fetched as a json from this url.
  3. The config endpoint or file is called if applicable, and the config is loaded into Zegami.
  4. The data is downloaded from the dataUrl specified by the config
  5. The XSLT for Zegs is downloaded from the zegXsltUrl specified in the config

The first step in customising the data in Zegami is to open the index.html file and point it at the locations where a config file is to be loaded. If you are offering multiple views on the data or different datasets per user then this endpoint needs to be dynamic.
The dynamic endpoint could be implemented either at the API level – each user gets a different config or at the HTML level – each user gets a templated html file. Alternatively, the dataUrl could be dynamic and the config static.

What does a minimal config look like? #

Two example configs are provided in the Zip file:
Many further properties exist that can be used to tailor how the data is displayed in Zegami.

Our specification is in OpenAPI JSON v3. We appreciate that these are somewhat verbose with many optional variables.
We therefore suggest using the example configs and data types table below as a starting point. You can browse the full API documentation here.

As part of the config you will need to provide:

  • dataUrl – the location of your data file
  • zegXsltUrl – the location of your zeg xslt file
  • dataLoader – either JSON or TSV (see below)
  • loaderOptions
    • fields: a list of fields in the data file with at least name, type and in some cases format

The data type and name of each column must be defined.

How do I format my data file? #

Data should be formatted as linear TSV or JSON. In the above config endpoint / file you will have defined the column data types.

JSON Format #

The data should be formatted as a JSON array with no wrapping object.
The data types supported are listed in the loaderOptions >> columns section of the schema. Example values for common supported data types are listed below.

typeformatExample value as json
stringdefault{“fieldname”: “foo”}
stringuri{“fieldname”: “”}
(data needs to be in ISO 6709 string expression (Annex H))
{“fieldname”: “+48.499998+23.3833318/”}
(data needs to be in ISO 8601)
{“fieldname”: “2011-10-05T14:48:00.000Z”}
numberdefault{“fieldname”: 123.6}

Examples values of common supported data types #

There are other formats and types listed in our schema, these are things that we would like to support in future, please let us know if any are of particular importance.

Linear TSV Format #

A tabular data file consists of zero or more records consisting of fields. Data types are formatted as above, quoting is optional. Encoding should be utf-8.
Records are separated by ASCII newlines (0x0a) (unix line endings commonly abbreviated as \n). Fields within a record are separated with ASCII tab (0x09 – tabs commonly abbreviated as \t). It is permitted but discouraged to separate records with carriage-return-newline (0x0d and 0x0a). (A literal carriage return or unix line ending in any other position is non-conforming).
Zegami expects there to be a header line across the top of the file. This should give names to each of the columns and should not contain empty values. Field names should not be repeated.
All tabs, carriage returns and newlines in text fields must be removed and replaced with spaces to allow Zegami to process the data.
Records must contain at least one field. All fields must be present in every record. To indicate missing data for a field,
the field is left blank. or the character sequence \N (bytes 0x5c and 0x4e) is used. Note that the N is capitalized.
This character sequence is exactly that used by SQL databases to indicate SQL NULL in their tab-separated output mode.
If a single backslash is encountered at the end of a field, it is an error. If a backslash precedes another character but does not form a null sequence \N, it is a “superfluous backslash” and is removed from the field on read. Such a “superfluous backslash” must never be written by a conforming implementation.

Authentication #

By default outbound requests to same origin include cookies so these can be used for authentication purposes. We also support authentication using Auth0. If you want to enable this feature, please contact our team for further information.

How do I author a Zeg XSLT? #

Full documentation on how to author a Zeg is included in the separate Authoring Zegs guide.

Error handling #

The default behaviour is to log application level errors to the console. However if this is not the preferred method for logging errors then we can tailor it based on the following options:

  1. Errors should be sent to your own internal system by HTTP, we can configure Zegami to send errors in the format described here.
  2. Errors should be tracked for you by Zegami (requires data to be sent to a third party from user machines).
  3. You are happy for errors to be logged to the console.

Theming Zegami #

It’s possible to style and theme Zegami so that it can match your branding as closely as possible. Refer to the separate guide Theming Zegami to create a theme file.
The theme file cannot be easily edited as it’s been compiled via a build step with a CSS preprocessor. This is due to Zegami using CSS variables which are not supported by IE11. Instead, by supplying a theme file, we will create a new build for you to include the css theme and logo of your choice.

Tag storage #

The Tagging system of Zegami relies upon the implementation of 4 endpoints.
Tags are keyed against the primary key for the collection.
Should this change, tags should be deleted and recreated.
Note that the back end should reconcile the tags that are added via the add endpoint.
Speech marks should be removed as described in the docs and the tags should be deduplicated when served such that no key is matched to the same tag twice.
The tag endpoints are documented in the API docs here

The following configuration variables are required to enable tagging:

"tagEndpoint":"https://my-cors-ready-api/[some collection id]/tags/",
"enabled": true
… other enabled toolbar items

Snapshot storage #

The API for storing of snapshots needs to be able to handle arbitary JSON objects.
The snapshot endpoints are documented in the API docs here

The following configuration variables are required to use snapshots:

"tagEndpoint":"https://my-cors-ready-api/[some collection id]/tags/",
"enabled": true
… other enabled toolbar items

Query string navigation #

Zegami standalone client can be navigated by query string. The current configuration of the viewer is determined by, and reflected in the url’s query string. This includes all view settings and filters as well as the state of the control panels.Tags are keyed against the primary key for the collection.
This unlocks some powerful features:

  • Refresh the page and retain the same view on the data.
  • Share urls which will lead to the exact same view of a collection, without needing to create a snapshot.
  • Navigate through the history of actions using the browser’s back and forward buttons

Usage in an iframe #

When Zegami is embedded in an iframe, some additional steps are needed to surface the changing query string to the containing window. See the example contained within the package for guidance on how to achieve this.

Powered by BetterDocs