This page tries to explain how to quickly and (as) correctly (as possible) use
Processing sketches on webpages. The information is based on the work done by
the processing.js group.

This information on this page reflects the best of my knowledge anno March
2011, using Processing.js version 1.1, but as Processing.js becomes more and more
complete, it is possible that the information on this page becomes outdated.
Should you spot any incompletenesses or blatant mistakes, please contact me at
pomaxҨnihongoresources．com,
with the obvious substitutions in place to make it a legal email address.

The "Processing" language (also referred to as "P5", think "Proce55ing") is a programming language (emphatically not "a program") with a focus on data visualisation. Of course, "data" is a loose concept, and Processing can be used for anything from drawing a few lines and circles on a screen, to full blown interactive animations. In fact, a basic Processing program is two lines of code, and will already play an animation:

void setup() { size(..., ...); }
void draw() {}

Of course this program doesn't show you anything, because all it does is set up the visual context to have a certain width and height (indicated in the setup method as the size(...,...) instruction) and then calls draw() every few milliseconds. Of course, draw() is empty, so it won't actually show you anything. A more useful minimal program would be a "hello world" program, but I hate those because they only show a programming language can write text, and that's pretty much the least interesting feature of any programming language. Instead let's look at a minimal program that makes sense for a data visualisation language:

This looks a bit long for a minimal program, but then again, this actually does something: it shows us a ball that bounces up and down, taking one second for each bounce. It shows a few aspects of Processing too: every variable is strongly typed. So you have to indicate what you'll be using a variable for, and you can choose from:

boolean, a binary value that can be either true or false

byte, an 8-bit value

char, a byte representing an ascii character

color, a type specific to Processing, representing an on-screen color

int, a 32 bit signed integer number

long, a 64 bit signed integer number

float, a 32 bit signed decimal number

double, a 64 bit signed decimal number

And of course there are also the typical complex data types:

Object, a catch-all data type for things that are complex data types.

String, a text string (stored as UTF-16).

ArrayList, a list structure for arbitrary values with add/remove functionality.

Coming back to the minimally functional example of a Processing program, or "sketch", there are also some examples of Processing' own API at work. The following methods are native Processing calls:

size(int, int), sets the drawing area dimensions, and the global "width" and "height" values.

frameRate(int), sets the refresh rate for the drawing area, and the frameRate value.

stroke(color), sets the shape outline color.

fill(color), sets the shape fill color.

abs(number), computes the absolute value of any number.

sin(number), computes the sinoid value based on any number (treated as radians).

background(color), sets every pixel of the drawing area to the specified color.

ellipse(int, int, int, int), draws an ellipse on the drawing area.

The Processing API is in fact quite expansive (See http://processing.org/reference for the full list), but it can't cover everything. Luckily it supports object oriented programming, so that our previous example can also be written as an object oriented sketch:

Instead of doing everything in the draw() function, the object oriented approach tucks all the code that relates to computing the ball's position in the definition for what we consider a "Ball". To be good object oriented programmers, we've also said that things that are a Ball are also a Bouncer, and this lets us extend our sketch very easily to instead of a bouncing ball, have a bouncing box by keeping almost everything the same, and adding a new class Box that's a Bouncer:

All of a sudden we have a bouncing box, that starts from a falling position instead of from the ground, and we didn't have to modify the master draw() function for it! In fact, let's just use a group of bouncing things:

Fantastic, two bouncing balls and a bouncing box, bouncing counter-point to each other. But it's not very interactive yet. Let's change it so that we can "hang on" to bouncing things until we let go of them again. Processing allows interaction with the keyboard and mouse, using what are known as "event handlers", methods that Processing automatically calls for you when you use the keyboard or mouse. In this case we care about mouse interaction, so we'll look at mousePressed and mouseReleased events:

Because the Ball and Box classes will do the same thing on mouse interaction, the interface Bouncer has been changed to an actual class too, to take care of some of the shared functionality. Now if you click on anything that's a Bouncer it'll stop moving until you let it go. Let's go one step further an just allow us to move the bouncing things around, too.

The great thing about Processing is that it can be used on webpages. Traditionally, you would convert your sketch to a java applet, and embed that on a page, but the processing.js project has changed this: you can now use your sketches directly without turning it into an applet at all. In the same way that you include a javascript file, or a CSS stylesheet, you can simply link to your sketch and magic happens.

Let's say we save the previous sketch, with the bouncing and the mouse interaction, as "mysketch.pde", and we want to show this on a webpage. Using processing.js, this is a trivially simple trick:

And we're done. In fact, I went ahead and made sure this page already uses processing.js, and that there is a mysketch.pde to load. If you click on the play control for the sketch on the right, it will start running, and do exactly what you would expect it to do based on what it does when you run it from the Processing environment.

While not recommended, you can also put your sketch directly on a page, much like how you can put javascript or CSS styles directly on a page. However, in order for processing.js to properly load your code, you'll need some extra help in the form of the "init.js" file that is included with the processing.js examples archive from the processing.js downloads page

There are several reasons for why this is not a very good practice, but the most important one is that this way you can't be sure whether or not you've written a bug-free sketch. By writing it directly on the page, you might in fact have written some buggy code, which you will then find is terribly hard to debug because the browser is not equiped with a debugger for Processing code. In fact, processing.js rewrites your sketch into pure javascript (using some terribly clever tricks that we won't go into), so even if when it tells you where the error is in a javascript debugger, it will tell you where it went wrong in the converted javascript object, not the actual place in your source code. So keep it as a separate file, and make sure to test your code in the Processing IDE!

Just running a sketch on a page is fine, but the benefit of a webpage is that it offers the kind of user interaction that you can't get from within the sketch itself. Pretty buttons, text areas that fold away, pop up, etc. make it very attractive to have your sketch do all the animation graphicsy work, but have all the information about the sketch, as well as controls for it, on the webpage. This is entirely possible - in fact, the "stop" and "play" buttons for the sketch above are examples of javascript telling the sketch what to do. Because a webpage offers more than a plain sketch can, processing.js has a few special tricks up its sleeve, so that you can get the most out of your creative work. Arguably the most important of these is the "get the sketch" function:

var mysketch = Processing.getInstanceById('mysketchid');

This is the pivotal function on the javascript side of things. It gives you a direct reference to your sketch, and everything in it, so that you can call any function and examine and modify any
variable that is in the sketch.

We can make this sketch draw a different text based on some text we have on our webpage, using javascript. This is in fact really easy: first, let's save this processing code as mysketch2.pde, and load it onto a page in the same way as earlier in the article. Then, we use javascript to ask for our sketch instance, after which we call the "drawText" function with some text that we get from the web page that the sketch is running on:

This has the same effect as the sketch that's running on the right. Simply fill in a bit of text, and hit the ▶ button to see the sketch render it on the drawing area.

So far so good, but what if we also want to make Processing code call javascript? In order for us to do so, while making sure the sketch keeps running both on your page an in the Processing environment, we have to do a bit more work

You can't just stick plain javascript in your sketch and hope everything goes well because it's "on a web page". A better approach is to neatly separate your sketch and your on-page javascript, and ensure that whatever you want to do on your page runs through a javascript function. How do we do that? Let's say we have the following page:

What we've done is we've told Processing: "There are things that follow the JavaScript interface. This means that whatever else they can do, they'll have a function called "showXYCoordinates" and that function takes two arguments, both of type int." - of course, the sketch will not magically know our on-page javascript, so we also define a function that lets us tell the sketch what actually counts as javascript, which is what the bindJavascript(...) function is for.

This leaves us with needing to make sure that we really do tell the sketch what javascript is, which we'll do as follows on the page:

This defines a function that checks whether processing.js has loaded our sketch yet. If not, it tries again 250ms later. If the sketch is loaded, the reference to the sketch is used to tell it what "javascript" should be. This is achieved by virtue of processing.js trusting that you wrote valid code. As such, as long as you're on the javascript side of things, you can pass the sketch whatever you like, and the sketch will trust that it conforms to what the method says the type should be. In this case we pass the javascript "this" value (which refers to the global javascript environment for the current window), and tell processing "this thing conforms to your JavaScript interface, so it has loads of things but the only thing you need to be concerned about is whether or not it has a showXYCoordinates(int, int) function, which it does."

So, our final sketch looks like the sketch behaves like the sketch on the right, and our final page source looks like the following:

This leaves us with one last topic that we need to cover, simply because it's so common: using javascript to get some data into a sketch. There are a number of ways in which to achieve this, so let's look at every way I can think of that achieves this goal.

One interesting thing that processing.js allows us to do is to create objects as we defined them in our sketch, in javascript, and then hand them over to the sketch to deal with. To give an example, let's use the following sketch, which lets you draw points by clicking with the mouse, and links up all the points with lines:

Another way to get data from javascript into a sketch is by way of a JSON description. JSON is particulary interesting because javascript can read a JSON text string and immediately turn it into a full-fledged javascript object. Let's look at our point-drawing sketch again, this time with a dedicated "addPoint" method:

Now what if -- instead of using mouse clicks, or predetermined javascript -- we want to load points based on some data on a remote server? We change our web page so that it can deal with JSON data from a remote server, and then make our javascript tell the sketch what to do:

Another favourite is the XML document. This is where the Processing data type "XMLElement" comes into play. Rather than trying to use javascript to parse the XML, we pass the xml data straight on to our sketch, which will know exactly what to do with it:

One last thing you may want to pass to a sketch is a real javascript object. Say we have a physics library that we want to take advantage of in our sketch, and for Processing it's a .jar file, but there's a javascript version too. This thing lets us create a javascript "Physics" object that we can call functions on for computing momentum and force transfer when we make two things hit each other. Since processing.js does not support .jar libraries (because it's precompiled binary java class code, and pjs cannot unpack a jar file, reverse engineer the .java source, transform it to Processing API calls, then confirm all calls are supported) we'll use this convenient javascript library. But how to do this cleanly?

We have to do three things:

Write an interface for the object we're using, so our sketch will know what it even is,

use a javascript binding so that we can ask javascript to make these objects for us, and

write a javascript function to make these objects for us.

So let's get cracking! First we determine which functions in the javascript Physics object we actually make use of. We could write an interface that has correct method signatures for every function in the library, but this would be overkill. After reviewing our code we see that we actually only make use of three of the objects functions: collide_objects(forcevector1, forcevector2, collisionangle), get_force_vector(startpoint, distancevector, accelleration) and get_trajectory(startpoint, objectmass, initialvector, gravityvector, gravitystrength). Let's build our interface:

First job done. Now to bind javascript. We've already looked at how to do this, so just follow the standard procedure and job's a good'n. In addition to whatever javascript functions you want to expose, however, we must add one more:

This last step seems silly, but we have to delegate the task of building a javascript object to javascript. If we tried to do this inside our sketch, processing.js will not complain, but Processing will. To make matters worse, it also obscures the point of failure: if something goes wrong in the sketch, did it go wrong because processing.js has a bug, or because you were sloppy with javascript inside a Processing sketch? Golden rule: keep the different languages separated as much as possible.

We're almost set to use our javascript library for Processing purposes now. The only thing left is to create these objects and then use them in our sketch:

As last point of business, you can of course also use Processing.js as a pure graphics library, by
invoking it for some canvas and then calling Processing API calls directly. Let's jump right in! The following
code is what you would write on-page, although of course as ever it's far better practice to link to your
source files, so you should really place what's in the script tags in a file myPjsSketch.js and link to it using
src="..." instead.

This binds a new Processing instance to the indicated canvas. The function(p) {}
bit is actually completely unimportant, but must be used until ticket
1,111 lands in Processing.js 1.2 (March 2011). Once 1.2 is out, the binding will simply be
var pjs = new Processing(canvas).

// let's write a sketch
var value=0;
// Definition for the initial entry point
pjs.setup = function() {
pjs.size(200,200);
// we want to turn off animation, because this is a demo page and it
// would use cpu while not being looked at. Only draw on mousemoves
pjs.noLoop(); }

This setup() function defines the entry point for our sketch. It sizes the canvas, and tells it not to animate by default.

If you run into the problem that your processing.js sketch doesn't work, and you checked Firebug (for Firefox),
Dragonfly (for Opera) or webkit developer tools (for Safari and Chrome) while running your sketch, but they didn't
help you figure out what's going wrong, what should you do?

Following the next 11-step plan, you should be able to either fix things yourself, or if you make
it to step 8, you have every right to come to our doorstep and ask us to fix whatever's wrong
because there's a genuine problem with the Processing.js library!

Before you start

Before you start debugging, you want to make sure your code is in a state that will allow you to effectively debug it. The following three questions are intended to make sure you have done everything you need in order to use the tools required for prodding your code with the debugging stick.

Debugging

The following six steps will run you through the basic debugging and possible fixing steps when something goes wrong with your code. It is possible that while running through these steps you actually fix the problem you were having, in which case hurray! Your code is fixed! If, however, you get to step eight, there is a genuine problem and you'll want to move on to getting us involved.

no: Reduce your code to a minimal example that still works in the Processing IDE, but goes wrong when using Processing.js, and read on...

Bringing it to our attention

At this point you've discovered a deficiency or bug with the Processing.js library, and we would very much like to hear from you so that we can fix it. The following three steps will make sure that we hear about it, so that we get the chance to improve compatibility between Processing and Processing.js.

9) If it works in Processing, but not in Processing.js, we screwed up! Do you use IRC?

yes: Drop by the #processing.js channel on irc.mozilla.org to let us know about it. Proceed to step (10).

no: If you've heard about IRC but never used it, now is an excellent time to start! Install an IRC client
(there are many clients, but here are some common ones for windows, Mac
OS X, GTK *nix, and terminal *nix) and visit our channel. However, if you
are emphatically opposed to using IRC (which would be a shame), skip to step (11).

This article was written by Mike "Pomax" Kamermans from nihongoresources.com. You can contact me at the fairly simple "pomax@" prefixed to the just mentioned domain, or just drop by the IRC channel for a more immediate kind of dialog.