Zegami is a web based tool built with web standard technologies: JavaScript and CSS. Adding Zegami to a web page requires a base HTML element to attach to and then configuring Zegami to your needs.

Prerequisites

In order for Zegami to be displayed it needs a base HTML element to attach to. Once attached Zegami will then use this element to create the entire user interface.

Zegami also uses the base element to determine its size on the page. It is recommended that this element is sized to fit 100% of the width and height of a page, but if this is not feasible then Zegami will resize to fit in any available space.

An example of a basic page to host Zegami

<!DOCTYPE html>
<html>
    <head>
        <title>Zegami</title>
        <style type="text/css">
            html, body {
                height: 100%;
                margin: 0;
                padding: 0;
            }
            body {
                width: 100%;
                -webkit-touch-callout: none;
                -webkit-user-select: none;
                -khtml-user-select: none;
                -moz-user-select: none;
                -ms-user-select: none;
                user-select: none;
            }        
            /* Set the width and height for the base element */
            #zegami-container { height: 100%; width: 100%; }
        </style>
    </head>
    <body>
        <!-- ZEGAMI CONTAINER -->
        <div id="zegami-container" />
    </body>
</html>

In our example above the base element is called zegami-container

It is important to note that the HTML5 DOCTYPE must be used on page in order for Zegami to work. For more details see Document type declaration.

Scripts and Styles

Now that a page has been created, the core Zegami scripts and styles need to be included in the page. Zegami has a single core script called zegami.min.js and a single core style called zegami.min.css.

In addition Zegami uses Font Awesome for (almost) all of its icons. This will also need to be included on the page.

<!DOCTYPE html>
<html>
    <head>
        <title>Zegami</title>
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0"/>
        <style type="text/css">
            html, body {
                height: 100%;
                margin: 0;
                padding: 0;
            }
            body {
                width: 100%;
                -webkit-touch-callout: none;
                -webkit-user-select: none;
                -khtml-user-select: none;
                -moz-user-select: none;
                -ms-user-select: none;
                user-select: none;
            }
            /* Set the width and height for the base element */
            #zegami-container { height: 100%; width: 100%; }
        </style>
        <link rel="stylesheet" href="zegami.min.css">
        <link href="http://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">
    </head>
    <body>
        <!-- ZEGAMI CONTAINER -->
        <div id="zegami-container" />
        <!-- SCRIPTS -->
        <script src="zegami.min.js"></script>
    </body>
</html>

Next we need to include any additional plugins.

Plugins and Extensions

Zegami has a strong emphasis on extensibility and has a robust plugin architecture that allows developers to easily extend its functionality. Included in the installation package are a range of default plugins that will help you get started. If a plugin doesn’t suit your needs, just create a new one!

As a start it is recommended that the TabDataLoader, DeepZoomTileManger, GridView and GraphView are added. This will allow Zegami to display data sourced from a tab delimited file using Zegami Server as the source of tiles.

We will add references to these at the bottom of the page, just above the closing body tag. All plugins are located in the plugins folder.

<!-- ZEGAMI -->
<script src="zegami.min.js" type="text/javascript"></script>
<!-- DEPENDENCIES -->
<script src="js/lib/react-with-addons.min.js" type="text/javascript"></script>
<script src="js/lib/EventEmitter.min.js" type="text/javascript"></script>
<script src="js/lib/dv.js" type="text/javascript"></script>
<script src="js/lib/pixi.js" type="text/javascript"></script>
<script src="js/lib/tween.min.js" type="text/javascript"></script>
<!-- PLUGINS -->
<script src="js/plugins/loaders/TabDataLoader.min.js" type="text/javascript"></script>
<script src="js/plugins/tilemanagers/DeepZoomTileManager.min.js" type="text/javascript"></script>
<script src="js/plugins/views/GridView.min.js" type="text/javascript"></script>
<script src="js/plugins/views/GraphView.min.js" type="text/javascript"></script>

Next we need to register the plugins we want to use with Zegami. This involves calling the relevent plugin methods on the global Zegami object and registering the name of the plugin and a reference to the plugin object.

<script>
    Zegami
        .tileManager('DeepZoom', DeepZoomTileManager)
        .loader('TabData', TabDataLoader)
        .view('Grid', GridView)
        .view('Graph', GraphView);
</script>

You’ll notice that the Zegami object supports method chaining, which is why it’s possible to write Zegami.tileManager().loader()... and so on. The previous code could also have been written like

<script>
    Zegami.tileManager('DeepZoom', DeepZoomTileManager);
    Zegami.loader('TabData', TabDataLoader);
    Zegami.view('Grid', GridView);
    Zegami.view('Graph', GraphView);
</script>

With the same result

Attach

Now that the relevant plugins have been loaded it is now time to attach Zegami to the base element. The attach method takes two parameters, the first is the id of the element to attach to and the second is the options object which is used to configure Zegami. See the section on Options for more details.

.attach('zegami-container', 
    {
        title: 'Zegami',
        serverUrl: 'http://localhost:5000',
        collectionId: '[insert collection id here]',
        loader: {type: 'TabData', options: {id: 'id'}},
        tileManagers: {
            'dz': {type: 'DeepZoom', options: {sources: [
                {
                    name: 'main',
                    sourceId: '[insert image collection id here]'
                }
            ]}}
        },
        views: [
            {name: 'grid', type: 'Grid', options: {icon: 'fa-th', tileManager: 'dz'}},
            {name: 'graph', type: 'Graph', options: {icon: 'fa-bar-chart', tileManager: 'dz'}},
            {name: 'table', type: 'Table', options: {icon: 'fa-th', tileManager: 'dz'}}
        ],
        facetTypes: { string: { itemLimit: 50 } },
        scaleMode: 'nearest',
        colors: { primary: '#006CC2', primaryDark: '#00508f' },
        toolbar: [
            {type: 'snapshot'},
            {type: 'export'},
            {type: 'labels', enabled: false},
            {type: 'grouptag'},
            {type: 'download', visible: false}
        ],
        trackVisited: false,
        baseCSSPath: '../web/static/css',
        baseImagePath: '../web/static/img',
        baseJSPath: '../web/static/js'
    }
);

In the above code, Zegami is attaching to an element with the id="zegami-container". The loader has been configured to retrieve values from the data/example.tab file, the Zegami server is located at http://localhost:5000 and the Grid and Graph views have been set.

Our completed page should now look like this

<!DOCTYPE html>
<html>
    <head>
        <title>Zegami</title>
        <style type="text/css">
            html, body {
                height: 100%;
                margin: 0;
                padding: 0;
            }
            body {
                width: 100%;
                -webkit-touch-callout: none;
                -webkit-user-select: none;
                -khtml-user-select: none;
                -moz-user-select: none;
                -ms-user-select: none;
                user-select: none;
            }

/* Set the width and height for the base element */

            #zegami-container { height: 100%; width: 100%; }
        </style>
        <link rel="stylesheet" href="zegami.min.css">
        <link href="http://maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet">
    </head>
    <body>
        <!-- ZEGAMI CONTAINER -->
        <div id="zegami-container" />
        <!-- ZEGAMI -->
        <script src="zegami.min.js" type="text/javascript"></script>
        <!-- DEPENDENCIES -->
        <script src="js/lib/react-with-addons.min.js" type="text/javascript"></script>
        <script src="js/lib/EventEmitter.min.js" type="text/javascript"></script>
        <script src="js/lib/dv.js" type="text/javascript"></script>
        <script src="js/lib/pixi.js" type="text/javascript"></script>
        <script src="js/lib/tween.min.js" type="text/javascript"></script>
        <!-- PLUGINS -->
        <script src="js/plugins/loaders/TabDataLoader.min.js" type="text/javascript"></script>
        <script src="js/plugins/tilemanagers/DeepZoomTileManager.min.js" type="text/javascript"></script>
        <script src="js/plugins/views/GridView.min.js" type="text/javascript"></script>
        <script src="js/plugins/views/GraphView.min.js" type="text/javascript"></script>
        <script>
            Zegami
                .tileManager('DeepZoom', DeepZoomTileManager)
                .loader('TabData', TabDataLoader)
                .view('Grid', GridView)
                .view('Graph', GraphView)
                .attach('zegami-container', 
                    {
                        title: 'Zegami',
                        serverUrl: 'http://localhost:5000',
                        collectionId: '[insert collection id here]',
                        loader: {type: 'TabData', options: {id: 'id'}},
                        tileManagers: {
                            'dz': {type: 'DeepZoom', options: {sources: [
                                {
                                    name: 'main',
                                    sourceId: '[insert image collection id here]'
                                }
                            ]}}
                        },
                        views: [
                            {name: 'grid', type: 'Grid', options: {icon: 'fa-th', tileManager: 'dz'}},
                            {name: 'graph', type: 'Graph', options: {icon: 'fa-bar-chart', tileManager: 'dz'}},
                            {name: 'table', type: 'Table', options: {icon: 'fa-th', tileManager: 'dz'}}
                        ],
                        facetTypes: { string: { itemLimit: 50 } },
                        scaleMode: 'nearest',
                        colors: { primary: '#006CC2', primaryDark: '#00508f' },
                        toolbar: [
                            {type: 'snapshot'},
                            {type: 'export'},
                            {type: 'labels', enabled: false},
                            {type: 'grouptag'},
                            {type: 'download', visible: false}
                        ],
                        trackVisited: false,
                        baseCSSPath: '../web/static/css',
                        baseImagePath: '../web/static/img',
                        baseJSPath: '../web/static/js'
                    }
                );
        </script>
    </body>
</html>

Zegami is now ready to use!

Options

The options object is passed in to Zegami's attach method and it used to configure all aspects of Zegami. In most cases Zegami provides default values for any of the options, which can be overridden.

title: String

The title of the collection which is displayed in the top tool bar.

serverUrl: String

The URL of the Zegami Server

collectionId: Stirng

The Id of the collection to display

loader: Object

Used to configure the loader plugin. A loader is responsible for retrieving the collection data from the server and laoding it into Zegami.

Zegami Server uses the TabData loader by default {type: 'TabData', options: {id: 'id'}}.

tileManager: Object

A tile manager is responsible for retrieving the images that make up the collection. By default Zegami comes with the DeepZoom tile manager.

views: Object

The views enabled in the toolbar.

views: [
    {name: 'grid', type: 'Grid', options: {icon: 'fa-th', tileManager: 'dz'}},
    {name: 'graph', type: 'Graph', options: {icon: 'fa-bar-chart', tileManager: 'dz'}},
    {name: 'table', type: 'Table', options: {icon: 'fa-th', tileManager: 'dz'}}
]

baseImagePath: String

Default: /img

The path to the images directory which is used to store the Zegami logo and other icons.

baseCSSPath: String

Default: /css

The path to the stylesheets directory.

baseJSPath: String

Default: /js

The path to the JavaScript directory.

debug: Boolean

Default: False

When True debug mode is avaliable. Additional debug and trace information will be logged to the console. Also displays the performance monitor.

logging: String

Default: none

Debug logging levels. Possible options include: debug, info, warn, error and none

tagsEnabled: Boolean

Default: True

Enable or disable item tagging

trackVisited: Boolean

Default: True

Enable or disable the item visited border

toolbar: Object

Default:

toolbar: [
    {type: 'snapshot'},
    {type: 'export'},
    {type: 'labels', enabled: false},
    {type: 'grouptag'},
    {type: 'download', visible: false}
]

Options to configure the toolbar buttons

colors: Object

Default:

{
    primary: '#CC78CE',     
    // Primary colour
    primaryDark: '#9766AD', 
    // Darker primary
    deselected: '#AFAFAF',  
    // Deselected
    blankSprite: '#BBBBBB', 
    // Blank sprite color
    scatterSelect: '#F2570A'
    // Scatter plot selected
}               

Colour configuration settings. These are additional colours that are not specified in the css.

langs: Object

Default:

{
    en: {
        'filters': 'filters',
        'graph': 'graph',
        'grid': 'grid',
        'sort-by': 'sort by',
        'group-by': 'group by',
        'search': 'search',
        'sort': 'sort',
        'range': 'range',
        'scatter': 'scatter',
        'expand': 'expand',
        'layer': 'Layer',
        'snapshot-tooltip': 'Save and manage snapshots',
        'export-tooltip': 'Export current filter as a table',
        'labels-tooltip': 'Toggle item labels',
        'legend-tooltip': 'Toggle legend',
        'source-tooltip': 'Change pictures source',
        'fullscreen-tooltip': 'Full screen',
        'help-tooltip': 'Zegami help',
        'range-label': ' to ',
        'fraction-label': ' of ',
        'snapshots-input-placeholder': 'Type name...',
        'snapshots-submit-button': 'Take Snapshot',
        'snapshots-remove-button': 'Remove snapshot',
        'snapshots-link-button': 'Share snapshot link',
        'snapshots-title': 'Snapshots',
        'snapshots-default-msg': 'No snapshots yet! Take a snapshot to save the current state.',
        'search-placeholder': 'Search...',
        'group-legend-label': ' legend',
        'group-legend-total': 'total:',
        'tags-label': 'tags',
        'itemcount-label': '{0}% of {1} items',
        'metadata-nav-left-tooltip': 'Previous item',
        'metadata-nav-right-tooltip': 'Next item',
        'loader-loading': 'Grabbing:',
        'loader-loaded': 'Grabbed:',
        'loader-ready': 'Loading data...',
        'loader-data-ready': 'Data loaded',
        'loader-tilemanger-loading': 'Loading picture data...',
        'string-filter-breadcrumb-limit': ' ... and {0} more'
    }
}

All text strings for Zegami. The language used can be defined using lang attribute of the HTML object the to support any language. For example to set the default language to Australian English <html lang="en-au">. This would require a matching en-au object.