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.
To begin, follow the instructions outlined in the HuddleCanvas API documentation.
This will cover:
- Installing Meteor
- Creating a Meteor project
- Adding HuddleCanvas API
- 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.
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.
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.
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>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
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.