Documentation

#plygrnd documentation

This documentation is setup to quickly help you create your own neato stuff with #plygrnd.

When you've forked/downloaded your copy of #plygrnd and look into the HTML, you'll notice that there are 2 JavaScript files loaded:

<script type="text/javascript" src="assets/javascripts/app.js"></script>
<script type="text/javascript" src="assets/javascripts/site.js"></script>

app.js is the #plygrnd app, the source code, the magic, the sauce, bladibla. No need to go peek in here. This should just work. And if not, fix it and send me a pull request will ya? ;-)

site.js is more interesting. This is the file with the JavaScript code that loads your views and instructs the app to initialize and stuff. Don't take my word for it! Check the source:

var siteApp = new App();

// Add the views:
siteApp.addView('assets/javascripts/views/basic.js');
siteApp.addView('assets/javascripts/views/dots.js');
siteApp.addView('assets/javascripts/views/dots-2.js');
siteApp.addView('assets/javascripts/views/ribbons.js');
siteApp.addView('assets/javascripts/views/lines.js');
siteApp.addView('assets/javascripts/views/bobs.js');
siteApp.addView('assets/javascripts/views/life.js');

siteApp.load();

Now, the siteApp.addView()-command is the most interesting, because it allows you to add your own views to the stack. You can go around and check the views one by one to see how it works, but for some background, let's just look at the structure of a single view:

siteApp.views.push({
    name            : "The name of my view",
    slug            : "the-slug", // This MUST be the same as the basename of the .js-file
    vars            : {
        // This is an object containing variables you want to use in your view.
    },
    initFunction    : function(ctx, vars){
        // This function is executed when the view is loaded
    },
    // Un-initialisation:
    unInitFunction  : function(ctx, vars){
        // This function is executed when the view is unloaded.
    },
    stepFunction    : function(ctx, vars){
        // This function is called with each 'step' of the animation.
    }
});

As you might have noticed, the initFunction, unInitFunction and stepFunction all get a ctx-parameter and a vars-parameter. The ctx-parameter is the Context2D-Object of the canvas element. So this is where you draw your fancy little pixels. The vars-parameter is the variables-object. You can use this parameter to update your variables. The standard basic.js-view gives a nice little example on how to use the vars-object to update a nice little counter. You should totally check it out.

But wait! There is more!

That's right! Next to the default variables you've provided by yourself into the vars-object, there are also some other variables that might interest you:

• vars.mousePosition provides an object with an x- and an y-property which tells you where the mouse is, RIGHT NOW! Wow! And that's not all! It also gives back them coordinates on touch devices! Kablam!
• vars.mouseDown tells you of the mouse is down at this very moment (or if someone is holding it's fat greasy finger on the glass of it's touch device, whatever...).
• vars.click is the same as vars.mouseDown, but it's only true for a single frame. So you can use this as a trigger for a click/touch.

But that's not all! Call now and you'll get...

...extra functions on your ctx-object. That's right! Making drawing and nasty calculations a little bit easier. This is what comes with the package:

• ctx.lineThrough([{x:0, y:0}, {x:10, y:10}, {x:30, y:40}, {x:20, y:80}]);: Give an array with XY-coordinates and draw a line straight through it!
• ctx.curveThrough([{x:0, y:0}, {x:10, y:10}, {x:30, y:40}, {x:20, y:80}]);: The same as ctx.lineThrough but then with a curvy line (quadratic curvy to be precise).
• ctx.direction(x1, y1, x2, y2): Returns the direction/angle in radians between two XY-coordinates.
• ctx.distance(x1, y1, x2, y2): Return the distance between two XY-coordinates.
• ctx.drawCircle(x, y, radius): I can't believe canvas just doesn't have this one out of the box!

Complex stepping and counting

We all now how we can animate a circle by calculating steps and releasing some sin() and cos()-functions on them puppies. But sometimes we want to make complexer movements. Without the hassle.

Gentlemen, meet the StepGenerator: It's a small class that comes with #plygrnd and provides a simple stepping mechanism, returning XY-coordinates as we speak. Setting it up is quite easy:

vars.stepGenerator = new StepGenerator(complexity, minimumIncrementalValue, 
    maximumIncrementalValue, minimumMultiplier, maximumMultiplier);

What it does, it generates multiple steps and increases (you know, the ones your granny used to code when wanting to animate a circle), does some magic number crunching with them, and returns an averaged XY-coordinate which gives your animation a more cool not-circle-like animation. Good examples are bobs, ribbons and dots-2 (where 'ribbons' is the most complex, since it calculates the direction of the next XY-coordinate).

Now, the StepGenerator also comes with it's own functions:

• vars.stepGenerator.step(): Make a step. This is the basic command to increase the step-values and update it all. This should normally be done once at the beginning of your stepFunction.
• vars.stepGenerator.getXY(offset, width, height): Get the XY-coordinates that come with this step. The offset-parameter can be used to get XY-coordinates of a next (or previous) step, without having to invoke the step()-function. The width and height-parameters need to be submitted to determine how big the area is in which the XY-coordinates need to be plotted.

That's it!

Happy coding! And if you've made a view that's spectacularrr, feel free to share it with the rest of us. Heck, it might even end up in the repository itself!