Skip to content

Kiosked/vulpes-ui

Repository files navigation

Vulpes UI

Web-based GUI for Vulpes

Build Status

Vulpes UI

About

Vulpes-UI is a plugin for the Vulpes platform that provides a web-based user interface to manage Vulpes jobs. Vulpes provides a Service which can be used to connect with Vulpes-UI to display jobs and their properties. Vulpes-UI provides a basic API (not related to Vulpes-API) for handling UI events.

This UI provides many useful features:

  • Add jobs to a Vulpes service
  • Start/Stop/Delete jobs
  • Track inheritance and job chains
  • Generate lightweight reports
  • Batch import jobs (using templates)

Installation

Install by running npm install vulpes-ui --save. Vulpes-UI depends on vulpes as a peer dependency, so you must have that installed as well.

Usage

Usage is simple enough - we recommend attaching the Vulpes UI router to the root / route:

const express = require("express");
const { Service } = require("vulpes");
const { createVulpesRouter } = require("vulpes-ui");
const app = express();
const port = 3000;

// Create a new service
const service = new Service();

service.initialise().then(() => {
    app.use("/", createVulpesRouter(service));

    app.listen(port, () => {
        console.log(`Application listening on port ${port}`);
    });
});

The method createVulpesRouter takes a Vulpes Service instance:

// Returns an Express router instance
createVulpesRouter(service);

The returned value is a router instance from express-promise-router.

Data Aspects

Vulpes UI reacts to various states of job data, many of which you can affect by setting result data or something similar.

Job Progress

Vulpes UI can render a progress bar on jobs that are:

  • Running
  • Returning progress metrics as they proceed

Job progress metrics are to be stored in result data, which can be set even while the job is running. The properties are as follows (note the hidden-property prefix %):

  • %progressCurrent: The current progress value - a number greater than or equal to 0.
  • %progressMax: The maximum progress value - a number greater than or equal to 0, but greater than or equal to %progressCurrent.

For example: if a job was processing images, and 108 out of 165 had been processed, you might set %progressCurrent to 108 and %progressMax to 165 which would render 65% in the UI.

Attachments / Assets

The UI can display attachments when added to result data correctly. An attachment's property key must be in the following format: %attachment:facbe41f-7889-426b-9388-20da2ad667fc. The latter part after the colon is a v4 UUID.

The value of these properties must be an object with the following properties:

Property Type Required Description
title String Yes The title of the attachment
created Number Yes JS timestamp of when it was created
mime String Yes The MIME type of the attachment
data String Yes Base64 encoded data of the attachment (data URI)