Page tree
Skip to end of metadata
Go to start of metadata

Overview

In this hands-on-tutorial you'll learn about the basic workflow of creating a custom data visualization with Archer. We'll work through a simple example that demonstrates how to use the Archer Editor to create a dynamic graphic and how to include this graphic in a web page using the Archer Runtime.

Our example is an analog clock:

A clock that doesn't move...yet.

This is a vector graphic that our designer has drawn and exported as a SVG. Our task is to make it display the current time. So what we have to do is get the current hour, minute and second and rotate each of the clock hands accordingly. As it turns out this is really easy with Archer!

But before we get started, here is a list of things that you'll need for this tutorial:

  • Download the Archer Editor
  • Download the clock.svg example graphic
  • A plain text editor (I'm going to use Atom, but you can use any other editor that you prefer)
  • A file server (If you don't know what that is or don't have one - we'll get to that later)

 

This tutorial will be demonstrated on a Mac, however Archer works on Windows and macOS. All steps in this tutorial are the same for both systems, unless explicitly stated.

 

Creating the graphic

Initializing the project

We start by opening the Archer Editor, which brings up the project list. In the project list click on the Plus  button to create a new project.

This opens a dialog where we have to enter several things about the new project:

  • Project name - The name of the project, for example clock-example
  • SVG File - The SVG file that Archer imports when creating the project, should point the clock.svg that you have downloaded

The dialog should now look something like this:

After clicking on Create you'll see an empty project with the imported clock graphic.

Transforming the clock hands

Next we want to make the graphic dynamic by rotating the clock hands when the current time changes. The graphic has three hands, for displaying the current hour, minute and second.

We'll start with the hour hand. First we have to select the hour hand in the editor. We could do that by simply clicking on the hour hand in the graphic canvas, however in their initial position all hands are layered above each other which makes selecting the correct one difficult. Instead we can use the SVG structure pane on the right, where all elements in the graphic are displayed in their hierarchical order. Just click on the hours element in the SVG structure and the hour hand gets selected.

Next we want to rotate the hand. To do this we select the Rotate  transformation from the top toolbar. This opens a dialog which asks us for a context.

A context defines how a graphic should react when a data value changes:

  • It defines some kind of data like current time, speed, a text status or a binary flag
  • It defines the value range that this kind of data can assume
  • It defines how elements in the graphic should be changed (transformed) when that kind of data assumes a certain value by mapping data values to a rotation, color or opacity value

Since there are no contexts yet, we have to create a new one. In our case we want to rotate the hour hand when the current hour changes. The current hour is a numerical value, so we select Number  below Add to new context.

This creates a new context plainly named Number context 1 with a rotate transformation for the element hours. To better represent what kind of data we are dealing with, we set the Name of the context to Hours and name the Variable hours. While the context name is informative only, the variable name will come into play when we use the graphic in our web page. The Context editor should now look like this:

We can see that a number context is displayed as a linear scale with two defined boundaries, a minimum and a maximum. Currently selected is the minimum boundary on the left which has a Value of 0. If we select the maximum boundary on the right by clicking on the triangle , we can see that its value is 100. This is just the default value range that Archer initializes the context with, however we want to define our own. We want to display the current hour of the day which can have a value range from 0..24. The minimum already matches our range, so we select the maximum, enter a new Value of 24 and confirm with [Enter].

Now that we have defined the range for our values we can care about the actual rotation. With the maximum still selected we enter an angle of 720° into the input field of the rotate transformation (right next to the Rotate label) and confirm with [Enter]. That would be two full rotations for a clock with a twelve hour display. We haven't entered a value for the minimum, so Archer uses a default angle of , which is what we need. With that we have created a value mapping of 0 degrees at 0 hours and 720 degrees at 24 hours. By default Archer uses linear interpolation for all values in between which means at 3 hours we automatically get an angle of 90 degrees, at 6 hours an angle of 180 degrees and so on.

To verify this, we can drag the red value scrubber in the Context editor around to simulate an hour value, while the graphic canvas immediately updates to rotate the hour hand by the calculated angle. The mapping of the current hour to an angle seems to work, however something is off:

The clock hand rotates around its center, which is not what we want. Instead we need to tell Archer that we want to rotate the element around the center of the clock. With the hours element that is still selected, we can change the Registration point in the Inspector pane to the edge at the bottom center . That seems to have fixed our problem:

Note that this only works because the artist was clever and drew the clock hands so that their bottom center is at the exact same spot as the center of the clock. If that wasn't the case, we could also have changed the rotation center by dragging the little crosshair on the graphic canvas or manually entering a position in the inspector pane.

 

After that we are already done with the hours hand. Now we need to repeat the same steps for the minutes and seconds. I'll just give a short rundown of the steps so that you can reproduce the results:

Minutes

  • Select the minutes element in the SVG structure
  • Add a Rotate  transformation
  • Create a new Number  context
  • Rename the context
    • NameMinutes
    • Variableminutes
  • Select the maximum
  • Enter a Value of 60
  • Enter an angle of 360° into the input field of the rotate transformation
  • Change the Registration point to the bottom center edge

Seconds

  • Select the seconds element in the SVG structure
  • Add a Rotate  transformation
  • Create a new Number  context
  • Rename the context
    • NameSeconds
    • Variableseconds
  • Select the maximum
  • Enter a Value of 60
  • Enter an angle of 360° into the input field of the rotate transformation
  • Change the Registration point to the bottom center edge

 

Now we have defined all transformations we might want to save our results before moving on. To do this, hit [Cmd+S] (macOS) or [Ctrl+S] (Windows) or use the File -> Save command from the application menu.

Publishing the graphic

In order to use our graphic in a web page we need to publish it first using the File -> Publish... command from the application menu. This opens a file dialog where we need to select the location where the published graphic should be stored. I'm going to use:

<User Home>/Documents/archer-publish/clock-example

After confirming the file dialog Archer should show a small notice that the publishing succeeded and where the files are located:

By clicking on Open we can open the graphic folder. Here we can see that Archer has created several files in it:

  • archer.graphic.svg - This is just our old clock.svg file with a fancy new name
  • archer.config.json - This is a configuration file for the Archer Runtime that describes the behaviour of our clock
  • example.html - This is a simple auto-generated example on how to use the graphic in a web page
  • libs/archer.min.js - This is the Archer Runtime library itself
  • assets - This is where images for a graphic would be stored, however our clock doesn't use any so the folder is empty

Using the graphic in a web page

Our next step is to actually display the clock in a web page. We are going to create a HTML page and write some simple JavaScript code to load our clock and provide it with the current time so it can rotate the clock hands accordingly.

Displaying the graphic

For this we now switch to our text editor. We create a new HTML file called clock.html in the graphic folder (next to the example.html) and paste the following HTML markup:

<!DOCTYPE html>
<html>
<head>
    <title>clock-example</title>
    <style>
        body { margin: 0; }
        #container { position: absolute; width: 100%; height: 100%; }
    </style>
</head>
<body>

<div id="container"></div>

<script src='libs/archer.min.js'></script>

<script language='javascript' type='text/javascript'>
  // Our code goes here...
</script>

</body>
</html>

This is just a basic HTML page with a div element named container that stretches over the whole page. This is were we are going to display our clock. The first script tag includes the Archer Runtime library which provides us with an API for loading and interacting with an Archer graphic through JavaScript. The second script tag is still empty, here we are going to add our example code.

To initialize a new Archer graphic in our container we enter the following code into the empty script tag:

var container = document.getElementById('container');
var graphic = archer.create(container);

The first line simply gets a reference to the container element while the second line prepares the container for displaying an Archer graphic.

Next we can load the graphic using:

graphic.loadUrl('archer.graphic.svg', 'archer.config.json');

This is going to load our graphic files from the specified URLs and displays the graphic in our container.

To make the graphic fit stretch over the whole page we add:

graphic.on('ready', function() {
  graphic.view.zoomToFit();
});

This code waits for the ready event which indicates that the graphic has finished loading and calls zoom to fit to resize the graphic to match its container bounds.

Testing the example page

At this point we can already check if the graphic is loading. However simply opening the clock.html in a browser still only shows an empty white screen. The problem is that we are opening the clock.html from the file system (file protocol), and because of that the Archer runtime will also try to load the SVG and JSON from the file system. However your browser prevents that, and for good reason - otherwise any web page could just read random files from your disk.

So what we need here is a file server that serves our example files through the HTTP protocol which in turn lets the Archer Runtime load the required files through HTTP - with which browsers are actually OK. Depending on your previous experience with web development this might be an extremely easy or extremely daunting task to do. If you don't know where to start, you can use one of the following instructions to set up one.

If you already have a file/web server or know how to set up one you may skip the following part. Instead make sure that the folder with the clock example is accessible through a file server.

 

 How to set up a file server (cross-platform, requires installation of 3rd party software)

First we are going to install Node.js which is a multi-platform solution for writing apps / servers in Javascript. You can get Node.js from here. Download the version for your operating system and follow the installation instructions.

Node.js comes with a tool called npm which allows us to install other tools written for Node.js, such as a file server. To install a file server using npm open a Terminal / Command Line and enter:

npm install fileserver -g

This command might require elevated security, which means macOS users need to prepend the command with sudo and Windows users should start the Command Line as Administrator.

Next navigate to the directory where your example is located:

cd ~/Documents/archer-publish/clock-example (macOS)
cd /d %USERPROFILE%/Documents/archer-publish/clock-example (Windows)

Now you can start the file server using the command:

fileserver 3000

If you open the URL http://localhost:3000/clock.html in your browser you should now see the clock graphic.

When you don't need the file server anymore you can press [Ctrl+C] in the Terminal window.

 How to set up the bundled Apache Web Server (macOS only, does not require installation of 3rd party software)

macOS comes bundled with an installation of the Apache Web Server that can be used to test Archer graphics.

First we have to start the web server. To do so, we open a Terminal and run the following command:

sudo apachectl start

Next we have to copy the published graphic into the web servers root document folder. The root document folder is located at:

/Library/WebServer/Documents

Which means we have to copy the graphic folder to:

/Library/WebServer/Documents/clock-example

If you open the URL http://localhost/clock-example/clock.html in your browser you should now see the clock graphic.

Please note that all further changes to the clock.html have to be made in the copy that is located in your web server:

/Library/WebServer/Documents/clock-example/clock.html


When you don't need the web server anymore, you can stop it by running the following command in a Terminal:

sudo apachectl stop

 

Assuming you got the file server set up, open the clock.html in your browser and you should see the clock graphic although nothing is happening so far because we haven't actually changed any data values.

Passing data to the graphic

To actually rotate the hands we have to get the current time and pass the values for the current hour, minute and second to the graphic. Let's add a new function which does that:

function updateTime() {
  
  var now = new Date();

  var seconds = now.getSeconds();
  var minutes = now.getMinutes() + (seconds / 60);
  var hours = now.getHours() + (minutes / 60);

  graphic.setValue('hours', hours);
  graphic.setValue('minutes', minutes);
  graphic.setValue('seconds', seconds);
}

The function gets the current time by creating a new Date instance and then calculates the current hour, minute and second as it would display on an analog clock. Next it passes these values to the graphic by calling setValue for each kind of data. Note that when calling setValue we pass a key (hours, minutes, seconds) to indicate which kind of data we want to change. These keys are the variable names that we have defined earlier in the Archer Editor for each context. Calling setValue will automatically trigger an update of the graphic with the clock hands being rotated.

Now we still need to call this function. We add a new piece of code to the ready event listener that we have defined earlier:

graphic.on('ready', function() {
  graphic.view.zoomToFit();
  // Add the following line
  setInterval(updateTime, 10);
});

This just calls our updateTime function every 10 milliseconds which should be more than enough to animate our clock smoothly.

Now we can refresh the clock.html page in our browser and see that the clock hands are rotating to display the current time. Well done!

Check out this CodePen for a working demo:

See the Pen Wiki Clock Tutorial by Archer (@archer-graphics) on CodePen.

Summary

In this tutorial we've learned the basic workflow of creating an Archer graphic and using it in a web page.

We took a static vector graphic of a clock and imported it into the Archer Editor. We added rotations for the clock hands and mapped time data values to angles. Then we published the graphic for later use in a web page. We created an HTML page and displayed the graphic using the Archer Runtime. Then we provided the graphic with data for the current time and the graphic updated itself by rotating the clock hands into the correct position.

If you haven't been following the tutorial step by step you can download the results here: