An API to allow the easy inclusion and manipulation of HTML objects on a Huddle Canvas.
JavaScript CSS
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
api
test
.gitignore
.travis.yml
README.md
package.js
versions.json

README.md

Huddle Object API

HuddleObject: An API to allow the easy inclusion of HTML objects on a HuddleCanvas with support for HammerJS multi-touch gestures.

n.b. Use of the HuddleObject API requires use of the Huddle API and HuddleCanvas API.

Getting started

To begin, follow the instructions outlined in the HuddleCanvas API documentation.

This will cover:

  1. Installing Meteor
  2. Creating a Meteor project
  3. Adding HuddleCanvas API
  4. Using HuddleCanvas

n.b. Although this is a four-step process, step 1. is only required for first time users of Meteor. The remainder of the instructions can be completed rapidly, primarily using command line prompts and basic HTML/CSS/JS.

Once the above steps from the HuddleCanvas documentation have been completed, the HuddleObject API can be integrated with the Meteor Project.

Using HuddleObject - The Basics

This section explains the basics of HuddleObject. To demonstrate integration from a clean install, the HuddleCanvas instructions were followed in a new project called "HuddleObjectDemo".

When using the Huddle API's, the main development area consists of three generated files in the root directory of the new Meteor project.

Given the example project title "HuddleObjectDemo", the above mentioned files should be generated as:

  • "HuddleObjectDemo.css"
  • "HuddleObjectDemo.html"
  • "HuddleObjectDemo.js"

If the HuddleCanvas documentation was followed correctly, the files will have been edited to have content similar to the following examples.

HuddleObjectDemo.html

<head>
  <title>Huddle Object Demo</title>
  <!-- Insert below meta tags -->
  <meta name="apple-mobile-web-app-capable" content="yes">
  <meta name="apple-mobile-web-app-title" content="Huddle Object Demo">
  <meta name="viewport" content="minimal-ui, width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no">
</head>

<body>
    <div id="huddle-canvas-container">
        <div id="huddle-layer">
        </div>
    </div>
</body>

HuddleObjectDemo.js

if (Meteor.isClient) {
  var canvas = HuddleCanvas.create("orbiter.huddlelamp.org", 60000, {
    panningEnabled: true,
    backgroundImage: "../../map.jpg",
    showDebugBox: true,
    layers: ["huddle-layer"]
  });
}

if (Meteor.isServer) {
  Meteor.startup(function () {
    // code to run on server at startup
  });
}

The parameters passed into the HuddleCanvas.create() function may vary slightly, in the example it is connected to the HuddleOrbiter simulator and settings have been enabled with a background image assigned.

n.b. A small note to those implementing a HuddleCanvas with a background image: The "backgroundImage" setting may need to be prefixed with "../../", this will access images placed in a folder within your meteor project called "public". This folder may need creating.

Summary

Once this stage in the development is reached, the project should be runnable in the Meteor environment with a pannable background image. Now, let's add objects.

Using HuddleObject - Adding objects

Use the Meteor Package Manager to add the HuddleObject API to the Meteor project.

$ meteor add huddle:object

Adding objects to the canvas is no different to adding HTML div elements to a webpage and styling them with CSS.

HuddleObjectDemo.css

The CSS file needs to be updated with some mandatory and optional styles for any element we intend to add to the canvas.

/* CSS declarations go here */

#test-object {
    width: 200px;
    height: 200px;
    top: 100px;
    left: 100px;
    background-color: yellow;
    color: purple;
}

In the example, the object we add will take the ID attribute "test-object".

Some points to consider:

  • top A default top property must be defined, 0px is fine.
  • left A default left property must be defined, 0px is fine.
  • The rest of the CSS styles are optional!

HuddleObjectDemo.html

The HTML file needs to be updated to include the mark-up for the Huddle Object element.

<head>
  <title>HuddleObjectDemo</title>
</head>

<body>
    <div id="huddle-canvas-container">
        <div id="object-layer">
            <div id="test-object" class="huddle-object can-drag can-scale can-rotate">
                <span>Hello world!</span>
            </div>
        </div>
    </div>
</body>

To add an object we simply create a nested <div></div> element within <div id="object-layer"></div>

Points to consider:

  • ID attribute All parent elements need to be given a unique ID attribute
  • Class attribute All parent elements need to be given the "huddle-object" class attribute

HuddleObjectDemo.js

Finally, we need to update the JavaScript file to include a call to the HuddleObject API function which initialises the Huddle Objects.

if (Meteor.isClient) {
  var canvas = HuddleCanvas.create("orbiter.huddlelamp.org", 60000, {
    panningEnabled: true,
    backgroundImage: "../../map.jpg",
    showDebugBox: true,
    layers: ["object-layer"]
  });

  // code for HuddleObject inside window.onload function
  window.onload = function() {
    HuddleObject.initObjects();
  }
}

if (Meteor.isServer) {
  Meteor.startup(function () {
    // code to run on server at startup
  });
}

The initObjects() call initialises a Meteor Collection to store information about Huddle Objects and sets up the HammerJS event listeners. Following this, a Tracker.autorun() function is implemented that will automatically update Huddle Object's positions based on the transformations applied. This is synchronised across all the devices within the Huddle.

Points to consider:

  • window.onload function is where to make calls to the HuddleObject API from

Summary

Well done! A Huddle Object should now successfully be added to the canvas. Gestures are automatically disabled until the correct classes are applied. Apply them following the instructions in the section below anduse a tablet device available to try them out. See the next section for more information on gestures.

Using HuddleObject - Gestures

Huddle Objects currently support the following multi-touch gestures using HammerJS event listeners to capture information about the gesture.

All transformations are applied through the objectTransform() function in the API.

By default, all gestures are disabled, even after the .huddle-objects has been applied. Simply add the class attributes shown in the sections below for each gesture to enable them.

One finger drag

Dragging a Huddle Object with one finger will move it about the canvas.

Enable class: .can-drag

One finger flick

Gives Huddle Object inertia, allowing you to flick it across the canvas.

Enable class: .can-flick

You can change the friction of the canvas when initialising the objects, the default value if a value is not given is 0.05:

HuddleObject.initObjects({
    friction: 0.03
});

Two finger pinch

Pinching the item will scale it based on the increase or decrease in proximity of the two pointers.

Enable class: .can-scale

Two finger rotate

With two fingers, a Huddle Object can also be rotated.

Enable class: .can-rotate

Elastic

The shape will return to its original position, orientation and scale after temporary manipulation.

Enable class: .is-elastic

Summary

A HMTL div with all gestures enabled will therefore have class attributes similar to the following:

<div id="test-object" class="huddle-object can-drag can-scale can-rotate">
  <span>Hello world!</span>
</div>

Using HuddleObject - Sessions

When an object is first added to the canvas, it won't be added to the Meteor Collection until it is interacted with via touch gesture. Once inserted into the Meteor Collection, an up-to-date set of data regarding co-ordinates, orientation and scale are kept so upon reload, Huddle Objects will be in the same position that they were when last interacted with.

They can be defaulted to their CSS properties by running the following command in terminal:

$ meteor reset

Example Gist

The idea behind HuddleObject is to create an environment where an application can be created with its own scripts and logic, making use of the simplicity of the gestures. For demonstration purposes, see the following gist for an example involving a university map and nearby tube stations.

https://gist.github.com/jonnymanf/92c08bdf4c593650905c

Assets for the map and icon files, referenced in the CSS file, will need to be provided, simply include them within the directory public in the Meteor project's root.