The Karma Project: Code Less, Teach More

February 18, 2010

Introducing the Karma Lesson Template

Filed under: News — Tags: , , , , , , , , — bryanwb @ 8:19 am

I have created a simple template for individual karma lessons. In this post, I will explain how to use the template and what still needs to be implemented. The template still has some rough spots that I would very much appreciate feedback on.

Before reading on, you should download the lesson template directly or use git to clone the repository.

$ git clone git://

What the Template Provides

  • Layout that matches the XO’s screen resolution
  • Navigation bar – with links to help text, lesson plan, and teacher’s note
  • Viewer for lesson plan and teacher’s note
  • Scoreboard, timer, Start, Stop, Restart buttons all in the footer
  • Helpers to make your lesson event-driven rather than using a single control loop
  • Basic i18n for strings, but this is still in flux

Most Important Files in the Template

These are the files that will modify to create your lesson

  • index.html – the markup for your lesson
  • js/lesson.js – the code for your lesson
  • css/lesson.css – the layout for your lesson

Meet index.html


The html markup in index.html is quite simple

        <div id="kHeader">

	<!-- Put the help text inside #kHelp -->
	<div id="kHelp" title="Help Title"> Help text here</div>
	<div id="feedback"></div>
	<!-- #kMain is where the magic happens, the main frame where your lesson
              its stuff -->
	<div id="kMain">
	  <strong id="itWorks">It Works!</strong>
	<div id="kFooter">

That is very little html for actual page that is rendered. That is because #kHeader, #feedback, and kFooter are just scaffolding that we use to hang jQuery UI widgets on.

Here is a wireframe of index.html that will help you understand the dimensions and layout

As you can see from the wireframe, the lesson has a default width of 1200px and height of 900px. This gives you 1200px X 760px in #kMain to use for your lesson.

This is to match the dimensions of the XO. We could default to a smaller resolution that matches most desktops, like 1024 x 760 or 800×600 and scale up the lesson on the XO. We don’t do this for two reasons. First, scaling up is cpu-intensive and slow as molasses on the XO and second, scaled up raster images (.png, .jpg) ‘pixelate’ and look like crap. If we only used SVG images throughout the template, this would be a non-issue, as SVG scales up and down without performance cost.

I have created a function in the Karma.scaleWindow that will scale down the entire lesson to 950px X 760px. This leaves you only 950px X 460px. Please don’t develop a Karma lesson at this resolution if you intend it to run on the XO. I created this function to scale down your lesson to run on non-XO’s with the resolution 1024 x 760. With a bit of work you can make sure your lesson works at both 1200px X 900px. By far the easiest way to do this is to only use SVG.

Karma.scaleWindow();   /*scales window to 1024 x 760 if current browser window is narrower than 1150px */

If anyone has a better idea how to handle different screen resolutions while still accommodating the XO’s performance issues, please let me know.

Additional files that may be of special interest

  • start.html
  • kDoc.html
  • lessonPlan.html
  • teachersNote.html

The start.html page is an introductory page to the lesson that provides big obvious links to the Lesson Plan and Teacher’s Note. It also indicates very clearly which grade and academic subject the lesson is for. The Lesson Plan describes how to lead the children through the lesson in a classroom. The Teacher’s Note explains what the purpose of the lesson is and where it fits into the curriculum. index.html also has quick links to the Lesson Plan and Teacher’s Note but they are harder to find. The start page may seem unnecessary to some, but the teachers in Nepal tell us that they like it.

I have created a simple viewer kDoc.html for viewing the lesson plan and teacher’s note.
I cannot understate the importance of the lesson plan and teacher’s note. Figuring out how to use educational software effectively with 30+ energetic kids is not a trivial task.


Remember the minimalist markup for kHeader, kFooter, feedback. All three are jQuery UI widgets that have to be attached to HTML <div> elements.

A jQuery UI widget typically consists of a JavaScript file and a CSS file. Here are the widgets and the files that make them up:

  • kHeader — js/ui.kHeader.js and css/ui.kHeader.css
  • feedback — js/ and css/
  • kFooter — js/ui.kFooter.js and css/ui.kFooter.css

See the API documentation online or at docs/index.html in the template

Attaching a widget to a page

var $kFooter = $('#kFooter').kFooter();  //where #kFooter is a <div> element

Using different initialization parameters

var $kFooter = $('#kFooter').kFooter({'winningScore': 6, timer: true, scoreboard: false,
						pauseButton: true, startButton: true});

Notice that II assigned the result of the kFooter method to the variable $kFooter. This variable is cached reference that I can use to call new methods on the kFooter later and it is much faster than using a fresh jQuery selector each time like $('#kFooter').kFooter(/* some method */);. The naming convention for such variables is to prefix them with the ‘$’ character to signify the variable refers to a jQuery object.

All three widgets have their own methods that you can use to interact with them. The kFooter widget, for example, has methods getScore(), inc(), dec(), setScore(), startTimer(), stopTimer(), and more to manage its built-in scoreboard and timer

Calling methods on jQuery UI widgets is bit different. You pass the method name as an argument in order to call it. Here are examples of calling methods on the kFooter widget:

$('#kFooter').kFooter('inc');   //increments the score
//or if u have a reference

// To pass arguments to the method, simply append them as additional arguments
$kFooter.kFooter('inc', 2);  //increment score by 2 rather than the default of 1

Event-Driven User Interface

When you create your first lesson, it is very tempting to use a loop like


  if(/* user does X */){
       exit the loop


This code, while well-intentioned will cause your browser to display the horrible “Unresponsive script” message. The code also makes the user interface sluggish and generally unresponsive.

You can avoid this terrible message by making your code event-driven. This is a big word for using events and flags to control the behavior of your lesson.

Here is some code that look event-driven but actually is just a modified for loop and should be avoided. It can also cause the dreaded “Unresponsive script” message.

var timerId;

var game = function(){
      /* do stuff */
      timerId = setTimeout(game, 10);

if(/* user wants to quit */){

Here is a good example of event-driven code, modified code take from ui.kFooter.js

var timerRunning = true;
var runTimer = function(){
	if (timerRunning) === false){
	    return;  /* setting timerRunning to false stops the timer */
        /* code for manipulating the time displayed */
	timerId = setTimeout(runTimer, 1000);

//start the timer

//to stop the timer, set the flag timerRunning to false
timerRunning = true;

Things to Remember:
* Use setTimeout rather than setInterval
* Set flags to stop a background animation or timer rather than clearInterval()

Triggering custom Events and listening for them

If you initialize the kFooter widget with a winning score, it will emit a custom event “kFooterWinGame” event when that score is reached.

var $kFooter = $('#kFooter').kFooter({'winningScore': 6});

//show congratulations message when kFooterWinGame event is emitted

The API documentation details the events that each widget emits.

Unresolved Issues

Here are some unresolved issues that I will continue working on and would most appreciated help with.

  • Scaling – scaling and raster graphics (.png, .jpg files) just don’t play well together
  • Icons – jQuery UI icons are all png’s, which means they scale poorly. They are also too small and hard to override
  • Sound plays poorly on chromium on linux — pls up vote this issue in the chromium bug tracker to encourage the chromium guys to fix it.
  • internationalization — still in flux, doesn’t integrate with pootle
  • Firefox 3.6 performance is pretty sluggish on the XO. We really need to figure out how to get chromium running on the XO. I believe it will be at least 2x faster.

Internationalization is still very much in flux – I have created a basic jQuery plugin for handling it but it leaves much to be desired. I just recently discovered google chrome’s i18n mechanism for chrome extensions and I believe that it is far superior. I hope to port it to jQuery, which should take some time. I really think that chrome, jQuery, and Firefox’s jetpack should agree on a common API for i18n. Integration with pootle will be a pain but there more incentive for others to integrate with it if all three platforms used the same tooling.


December 17, 2009

Tutorial IV: The Adventure Continues – JavaScript and SVG

Filed under: News — Tags: , , , , — bryanwb @ 7:08 pm

This article is the fourth in a series of four

  1. Introduction to karma.js
  2. This article,Comparing HTML 5 Canvas and SVG
  3. Digging into Inkscape
  4. This article, JavaScript and SVG

Section II: Writing the HTML . . . 5!

Step 1: It’s all about the !DOCTYPE

It all starts with the doctype, please make sure document starts with the following doctype declaration

<!DOCTYPE html>

DO NOT USE the following


Karma will throw a big fat ugly error message and be otherwise unkind

Step 2: Put the JavaScript in

    <script type="text/javascript" src="../../js/jquery-1.3.2.min.js"></script>
    <script type="text/javascript" src="../../js/karma.js"></script>
    <script type="text/javascript" src="../../js/jquery.svg.js"></script>
    <script type="text/javascript" src="../../js/jquery.svgdom.js"></script>
    <!-- Put your code in lesson.js, please -->
    <script type="text/javascript" src="js/lesson.js"></script>

Step 3: You should <object>

Please use <object> tag to embed your SVG into the HTML

Step 4: Don’t put style information into the document, put it in lesson.css

Please don’t do the following

<div id="badDiv" style="display:inline;font-size:bigger;"> Karma Rulez! </div>

The “Karma Rulez!” part is excusable but please don’t use the
style attribute. It is not only bad practice but it
will totally screw up the as-yet-unwritten internationalization
library mundo.js

Section III: The Presentation Layer with CSS

Good News, you can use the same CSS file for both your html and SVG
To use an external css file in your SVG, you need to link it in just above the first <svg> tag.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?xml-stylesheet href="../../css/lesson.css" type="text/css"?>
<svg ......

We want to make sure that the text on the map and the spaceship are invisible. Let’s also make the cursor become a pointer when it moves over a capital icon.

.text { display: none; } { cursor: pointer;}
.spaceship { display: none;}

Much of our program logic will be to reveal elements of the map and the spaceship when the user answers correctly.

CSS is a complicated, tricky beast that I can’t begin to explain here. Let’s move onto something easy, like JavaScript!

Section IV: Writing the game logic with JavaScript

Step 1: Meet jQuery, jQuery meet you

jQuery is a fantastic library for interacting with the HTML Document
Object Model or DOM. What is this &^&$$! DOM? The DOM is the
programming interface for HTML in the browser. Working with it
directly is pretty painful but jQuery abstracts it to something that
is actually quite pleasant to work with. We start with jQuery using the following:

        //Once the HTML on this page has fully loaded,
	// run my code here

$(document).ready doesn’t mean that everything is ready. It only means that all the html and <img> elements have finished downloading. It does not mean than any <audio>, <video>, or <svg> elements have finished downloading. This is important as your program will fail if it tries to manipulate any of these elements before they are ready.

Step 2: Tell Karma about your assets and Karma will put them into collections

	var k = Karma({
			  svg :[    
                              {name:'capitals', domId: 'capitals'},
			      {name:'alien', domId: 'alien'},
			      {name:'spaceship', domId: 'spaceship'},
			      {name: 'help', domId: 'helpScreen'},
			      {name:'playAgain', domId:'playAgain'},
			      {name:'helpIcon', domId:'helpIcon'},
			      {name:'quitIcon', domId:'quitIcon'}
			      {name:'correct', file:'correct.ogg'},
			      {name:'incorrect', file:'incorrect.ogg'}

The Karma() method initializes Karma.karma object with assets we pass
to it. During this initialization, the svg array we pass in is
converted to the “collection” object k.svg. You can access any of the values k.svg
using the name you passed in as the key. The ‘name’ property is arbitrary. I use this instead of the filename or domID because those can often be lengthy.

var mySvg = k.svg.helpIcon  //same as <svg id="helpIcon">
var myHeight = k.svg.helpIcon.height;
var myWidth = k.svg.helpIcon.width;

var name = 'playAgain';
var mySvg2 = k.svg[name];  //you can reference different assets programmatically

//You can even loop through the entire collection, but remember a collection
//is an object and not an array
$.each(k.svg, function(mySvg){ mySvg.css('display', 'none');

Accessing these items using the collections has an optional
performance benefit. Every time you use a css selector such as
document.getElementByid(‘someId’) or $(‘#someId’), you run a search
through the entire DOM.

Karma currently supports five different collection types,,
k.canvas, k.svg, and Please note that the prefix ‘k’ is an
arbitratry shortcut to Karma.karma and not by default part of the
global scope.

Karma will also throw errors if any of these assets can’t be
loaded. You will probably find this very helpfulin debugging your
application. Karma() also attaches helper methods and properties.

You do not have to tell Karma about all the images, svg images, and audio files in your application. You only need to tell Karma about the ones you want to helper methods for and to be fully loaded when you call Karma.ready()

Step 2: Get Ready!

Most likely, you won’t want to start our program until all of our assets are ready. $(document).ready only makes sure that the HTML and images have loaded. For this reason, Karma provides Karma.ready(), which blocks your program from running until all the assets you told it about in Karma( ) have fully loaded.

	var k =	Karma({ /* tell Karma about your assets */});
	k.ready(function (){

        //Once the HTML on this page has fully loaded,
	// run my code here

You have to wrap your code in function () { } otherwise it will
execute immediately, without waiting for Karma to be ready().

Step 3: Attach Event Handlers to the capitals on the map

 $.map($('', capRoot), function(elem){
		$(elem, capRoot).bind('click', function(event) {
                        if (isActive){
                        } else {
// $('', capRoot)  is a CSS selector that matches every city icon on the map
// $.map( )  executes the anonymous function on each matching item
// .bind() is a jQuery method that attaches an Event Listener
// isActive is a global variable, when the game is paused, it is false
// When the game is paused rather than removing the event handler, simply set isActive to false

Step 4: Make the alien talk

This is easy, use jQuery’s text() method to change the text

The CSS selector ‘foreignObject #alienQuestion’ matches an element with the id alienQuestion preceded by a foreignObject tag. For some reason it doesn’t work without including foreignObject in the selector. Perhaps this is a quirk having to do with using the foreignObject tag.

 $('foreignObject #alienQuestion', k.svg.alien.root).text('some Text');

Step 5: When user makes correct choice, display text and reveal part of the spaceship

//complex command that splits out a part name from those not yet displayed
var part = parts.splice(0,1)[0];  

//previously display for these items was set to 'none', 'block' makes them visible again
$('#' + part, spaceshipRoot).css('display', 'block');
$('foreignObject #alienQuestion', k.svg.alien.root).text("Correct! " + question.capitalName               
    +  " is the capital of " + question.deptName);
//display the text of State and capital 
$('.text.' + question.dept, capRoot).css('display', "block");

Step 6: Make the spaceship fly away

	    var flyAway = function(){
		var isLaunching = true;
		var startEngines = function(){
		var shipFire1 = $('#shipFire1', spaceshipRoot);
		var shipFire2 = $('#shipFire2', spaceshipRoot);
		var toggle = true;		    
	   //this animation alternates the display of two images
           //to simulate rocket propulsion
	    var toggleFires = function(){			
				shipFire1.css('display', "none");
				shipFire2.css('display', "block");
				shipFire1.css('display', "block");
				shipFire2.css('display', "none");
			    //toggle fires
			    toggle = !toggle;
			    setTimeout(toggleFires, 400);


		var fly =  function(){
			    "complete": function(){ 
				isLaunching = false;

		var blastOff = function(){
		    setTimeout(fly, 2000);				   


Step 7: Dialog Boxes

This part is actually quite easy

A ‘dialog box’ is nothing more than an absolutely positioned <div>

The following code takes a div element that previously hidden and centers it in front of everything else in the screen using the ‘z-index’ property

$('#helpScreen').css({"position": "absolute",
				"width": "420px", "height": "360px",
				'top': '25px', 'left': '20%',
				'z-index' : 20,  'display':'block', "opacity": 1});

For further exploration, I highly recommend reading through the original source code.
I haven’t explained every part of this exercise in detail so please leave me comments with what you don’t understand or think should be explained in greater detail.

Tutorial III: Digging into Inkscape

Filed under: News — Tags: , , , , — bryanwb @ 5:10 pm

This article is the third in a series of four

  1. Introduction to karma.js
  2. Comparing HTML 5 Canvas and SVG
  3. This article, Digging into Inkscape
  4. JavaScript and SVG

In the previous two tutorials I introduced you to the karma.js library and to working with HTML 5 <canvas> and <svg>. In this tutorial, I will walk you through creating a geography lesson from scratch using Inkscape. Tutorial #4 will cover manipulating our SVG graphics using JavaScript

This lesson will teach how user the location of the different
states of the country Uruguay.

I confess, I did not create this lesson from scratch. The excellent original “Conozco a Uruguay” (I know Uruguay) was created by Gabriel Eirea and his friends at CeibalJam!, a grassroots organization developing educational software for Uruguay’s nationwide OLPC
implementation. The original version of Conozco a Uruguay was written entirely in Python, using the excellent pygame library, a python wrapper around the animation library SDL. Why rewrite it using HTML5 and JavaScript? The reasoning is simple. CeibalJam! spends a lot of its time teaching Uruguayan volunteers how to write educational software using Python. At the same time, there are a large number of web developers in Uruguay who could start developing with Karma with only minimal training. This situtation holds true for Nepal as well. We spend a lot of our time teaching developers how to program in flash when there are lots of local developers who already know HTML and JavaScript.

The Plot

A poor alien has crash-landed on earth. The pieces of his spaceship have scattered across Uruguay. The user must help him locate the correct state where individual pieces are located. Once all the parts are found, the friendly alien can fly home.

Before we go any further please play the game at least once. You can browse all the source code for this example here.

How we are going to do it

We will have three main graphical elements, a political map of Uruguay, a spaceship, and an alien that asks the user questions. We will use SVG images for all three. The main action through out this application will be alternately showing and hiding text that happens to be superimposed on graphical images. SVG particularly shines in
this use case.

Section 1: Digging into Inkscape

In creating the Karma version of Conozco, I cheated. I didn’t create all the graphics from hand. In fact I didn’t draw a single one of them. I converted the original .png images to .svg using inkscape’s Trace Bitmap feature. I added a few images such as the help and exit icons. Those are GNOME icons that I copied.

You may find this section frustrating if you have never used inkscape before. I highly recommend you run throught the Inkscape Basic tutorial. You can find it through the Help menu in inkscape. Help > Tutorials > Inkscape:Basic

Step 1: Convert the map

File > Import
Choose the image in folder tutorial3/mapStates.png

Path > Trace Bitmap

Select Edge Detection and then click OK

Tracing the Bitmap

Tracing out the map

The Trace Bitmap dialog doesn’t close automatically so just click the X in the upper right corner.

Now click on your image and drag it to the right. You have two maps! The one on top is the SVG version. The one below is the old png. Delete the one below it.

maps superimposed

The one below is png and the one on top SVG

You may find that the white rectangle does not line up with your map. You can fix this with File > Document Properties then click the button “Fit Page to Selection.”

fit page to selection

Fit the page to the map

Step 2: Create the Capitals and the States

The great thing about SVG is that you don’t have to remember any x,y coordinates. Just put something on the map, set the element ID, and you can always access it later using a CSS selector statement.

Let’s create the marker for the state capitals

Click the button with the circle icon in the left vertical tool bar, then create a little circle

Next, right click on your circle and choose the option “Fill and Stroke”

At the fill tab, set all values to 255, to fill the circle with white

Set the color for the fill

Then go to the “Stroke paint” tab, make the R, G, and B values 0, 0, 0

Set the color for the Stroke/Outline

Now drag your little capital into place on the map.

Drag onto map

Click the “Text” icon on the left vertical toolbar. We are going to create two <text> fields, one for the state and one for the state capital. Make sure the font size isn’t too big for the area you highlighted

Create the text elements

Step 3: Add element ids and class names to the states and capital cities

Click on the icon you created for the capital, then click on the icon “Edit XML Tree” in the upper menu bar.

Edit the XML Tree manually

Highlight the “id” attribute in the upper right box. Then type in a new id in the bottom blank area. MAKE SURE YOU CLICK SET otherwise your change will not stick.

Set the id to “cap” + yourCapitalName

Set the element id

Now we are going to create a new attribute “class”

Go to the box where there currently is id and type “class” in its place. For the value, type in:

capital city yourCapitalName yourStateName

make sure you click SET!

Type in class names

Repeat the above for your capital icons

Set the id’s for all the capital text areas with “text” + CapitalName
and the id’s for the States with “textDept” + YourStateName. Using
these prefixes and camelCase consistently will save your tuckus later.

For each state text area, add the following class names

text dept yourStateName yourCapitalName

For each capital text area, add the following class names

text capital yourCapitalName

You may notice that I use “dept” frequently. That is because Uruguay calls their states “departamentos.” It was easier for me to continue using their convention rather than using “state.”

I can’t overstate the importance of setting the id and class properties correctly and to do it consistently.

Using these properties I can do operations such as the following

//hide all text on the map
$('.text', k.svg.capitals.root).css('display', 'none');

//show the text only for yourState and yourCapital
$('.text.yourStateName', k.svg.capitals.root).css('display', 'block');

Wow! Them css selectors aRrrre powerful stuff!

Step 4: Put it into the directory assets/svg

If you haven’t created a project folder yet, now is a good time. Here is a good template


Step 5: Convert the alien

File > Import choose alien.png

Path > Trace Bitmap…

Go to the area “Multiple Scans: create groups of paths” and select the option “Colors”

Next Click OK.

Trace the Colors

Delete the image underneath as you did before.

Delete the Image Below

Step 6: Create the Word Bubble

Click the button “Create Rectangles and Squares” and drag out a nice big rectangle

Create the Word Bubble

Give the rectangle nice rounded corners, set the values in the Rx and Ry boxes to 50

Round the corners

If you can’t see the Rx and Ry boxes, click the “Create Rectangles and Square” box again

Click on Text in the left vertical icon bar and type some text in the word bubble area. Make text area as big as the word bubble.

Create the Text Area

Go to File > Document Properties and click “Fit Page to Selection”

Fit the page to your image

Save your SVG as alien.svg and close Inkscape

Step 7: Text Don’T Wrap in SVG! A Beautiful Hack

In previous, tutorial I explained that inkscape does not support word wrapping in <text> elements. Let’s put into practice the hack I discussed last time.

Open up alien.svg in a text editor

Go to the portion of your file with the text in it. If it is
surrounded with <flowPara> tag, it should be fine. Leave it as
it is. If it is in a <text> element, delete the entire <text> element and replace it with the following:


Step 8: Convert the spaceship

There may be a much easier way to do this. If you know of one, please leave a comment.
Import ship.png

Path > Trace Bitmap

Select Multiple Scan, Grays and click OK

Multiple Scans with Grayscale

Drag out your grayscale version of the rocket

In the left vertical bar, click paint bucket

Select the red color from the lower color bar

Pick a color

dump paint into the left wing in the grayscale image, then drag it away

Paint the Wing

Drag out the wing

repeat for the rest of the space ship to reassemble your ship

Delete the original image and the grayscale

Highlight each individual piece of the ship then choose “Edit the XML tree” and set the id

Set the Id on the left wing

There are other SVG images in the Karma version of Conozco a Uruguay but there is nothing more advanced in them than what we have covered so far. Whatever you do, please put all the your SVG elements into the folder assets/svg/

Next up is manipulating SVG using JavaScript.

December 14, 2009

An Introduction to karma.js – Making HTML 5 Easy

Filed under: News — Tags: , , , , — bryanwb @ 10:04 am

This is the first in a series tutorials about karma.js

  1. This article, an Introduction to karma.js
  2. Comparing HTML 5 Canvas and SVG
  3. Digging into Inkscape
  4. JavaScript and SVG

While the Karma Project is a broad initiative to develop education software using openweb technologies, at its core is a relatively simple JavaScript library. The karma.js library has three primary functions

  1. Preload assets such as images, svgs, canvases, audio, and video and do some basic error checking on them
  2. Put those assets into collections where they can easily be referenced
  3. Attach helper methods to the individual references.

What Karma Doesn’t Yet Do

  1. It doesn’t provide animation functions. The current mix of Karma lessons use a hodge-podge of HTML 5 canvas, Raphael.js, and jQuery SVG to provide animation. Raphael.js is perhaps the most fully-featured and most robust of these three methods. I personally find that jQuery SVG is the least mature but the easiest to use. We may later promote a particular tool as the default for animation.
  2. Doesn’t fully support internationalization. You can use the _() GNU gettext function with karma lessons but there is currently no open-source mechanism for internationalizing the strings embedded in html markup. GNU gettext only supports localization of strings in application code. The main goal for version 0.3 of karma.js will be support for localizing inline text.
  3. It doesn’t support video yet

What Karma isn’t

Karma’s name is not a religious reference but to the first two syllables of Rabi Karmacharya’s last name. The logo for Karma means “om” or “everything” in Sanskrit. It is in not the character for karma. I made the logo “om” after Om Prakash Yadav, the amazing graphic designer/artist/manager at OLE Nepal. I

First Things First

Your first step in using karma.js is to make sure you set your document type to HTML 5. karma.js will throw a big fat error if you try to use your good ‘ol html 4.01 or XML declaration.

<!DOCTYPE html>

That’s it! Who would have thought migrating to HTML 5 would be so painless?

Next, include the karma.js file, which you can get here . Also, you should put in a link to your application code. Let’s say for the sake of this article you put your application code in js/lesson.js though karma.js does not require you to use that convention.

 <script type="text/javascript" src="js/karma.js"></script>
<!-- Your application code in lesson.js -->
 <script type="text/javascript" src="js/lesson.js"></script>

While we are at it, let’s add in a css file called lesson.css. Again, karma doesn’t require you to use that convention. In the future, our team here in Nepal will probably put the lesson specific styles in lesson.css and styles for all the lessons we use in Nepal in nepal.css. Iran, Bolivia, Equatorial Guinea, etc. may want to do the same.

    <link rel="stylesheet" type="text/css" href="css/lesson.css" />

Initializing Karma

karma.js only adds the value “Karma” to the global namespace. All of the Karma library lives within the Karma namespace.

The Karma() function initializes the Karma.karma object and its “collections” of images, audio, svg, videos, and canvases. During this initialization step karma.js creates the collections and does basic error-checking on them. For example, Karma( ) will throw errors for invalid properties passed in to it. In essence, you tell the Karma about the assets you want it to know about and Karma will 1) start loading them and 2) throw errors if there are problems accessing those assets. In the future, the Karma() constructor will support loading different locales and a variety of other options.


 var k = Karma({
	image: [
	    {name: "ball",   file: "ball37px.png"},
	    {name: "balloon", file: "balloon37px.png"},
	    {name: "banana", file: "banana37px.png"},
	    {name: "chilli", file: "chilli.png"},
	    {name: "fish"  , file: "fish64px.png"},
	    {name: "flower", file: "flower37px.png"},
	    {name: "normalChimp", file: "normalChimp_120x125.png"},
	    {name: "happyChimp", file: "happyChimp_120x125.png"},
	    {name: "sadChimp", file: "sadChimp_120x125.png"}],
	audio: [
	    {name: "correct",  file: "correct.ogg"},
	    {name: "incorrect", file: "incorrect.ogg"},
	    {name: "trigger", file: "trigger.ogg"}
         svg :[    
                              {name:'capitals', domId: 'capitals'},
			      {name:'alien', domId: 'alien'},
			      {name:'spaceship', domId: 'spaceship'},
			      {name: 'help', domId: 'helpScreen'},
			      {name:'playAgain', domId:'playAgain'},
			      {name:'helpIcon', domId:'helpIcon'},
			      {name:'quitIcon', domId:'quitIcon'}
         canvas: [
			      {name:"topLt", domId:"topLtCanvas"},
			      {name:"topRt", domId:"topRtCanvas"},
			      {name:"bottomLt", domId:"bottomLtCanvas"},
			      {name:"bottomMd", domId:"bottomMdCanvas"},
			      {name:"bottomRt", domId:"bottomRtCanvas"},
			      {name:"timer", domId:"timerCanvas"},
			      {name:"scorebox", domId:"scoreboxCanvas"},
			      {name:"chimp", domId:"chimpCanvas"}

I include both svg and canvases in this example but in a real application you would likely only use one or the other.

Notice that every asset has the “name” property. You define the name property. It is not tied to any actual characteristic of the asset. Its purpose is to give you a short, easy identifier for the asset. DOM and file ID’s are frequently long, descriptive, and painful to type repeatedly.

You access the asset from each collection like so:

k.image.ball,, k.svg.alien

You can also iterate through the collections using jQuery’s $.each function. You cannot use JavaScript’s map, forEach, and filter methods because each collection is an object, not an array.

$.each(, function(audio) {;});

The Karma() function attaches helper functions specific to each asset type. The helper functions support function chaining. Here are a few examples. For details please see the API documentation. I have not yet done a good job of documenting the helper methods for or k.canvas;
k.svg.capitals.getElementById('capitalMontevideo').setProperty('display', 'none');
k.canvas.scorebox.clear().drawImage(, x, y).strokeStyle('#000000').fillStroke(); 

As you might have guessed, this can save a lot of typing. I intend to rapidly add helper functions as I work more with karma.js

I have added helper functions for almost the entire HTML 5 canvas API but not yet documented it.

How does Karma locate your assets?

Well the location of some of these assets will be specified inside your html but others may not be, particularly audio and video. karma.js requires you to put your assets in the following directory structure:


If your image chilli.png is in pictures/ instead of assets/image/ , Karma will throw an error. However, this is only true for the assets you tell Karma about in the Karma() constructor. You can locate images that are not passed in to Karma anywhere that you want

Get Ready

Before you proceed with your application, you need to wrap your application code with Karma.ready() much like you would with jQuery’s $(document).ready(function () { …});

// lesson.js
Karma.ready( function () {
      // your code here

Karma.ready blocks your program from running until all the assets you passed to the Karma() constructor are fully loaded.

If you are using jQuery, simply wrap your the Karma.ready() within your $(document).ready

// lesson.js
$(document).ready(function () {
    var k = Karma ( { /* your assets */ });
    k.ready( function () {
         // your code here

So that is karma.js in a nutshell. Very soon I hope to have a extended tutorial that walks you through an example lesson. If you are curious about the internals of karma.js please checkout the code, run the tests, and play with the demos.

September 15, 2009

Karma version 0.1 Released

Filed under: News — Tags: , , , , — bryanwb @ 7:35 am

We are proud to release Karma version 0.1 today. Please download the code and try it out for yourself. You can also test out the demo here. You need Firefox 3.5 to run the demo and you will need to tweak Firefox 3.5 on the XO or you can download this Karma XO bundle Karma-1.xo


  • Chaining of operations
  • Wrappers for drawing functions
  • API documentation
  • simple mechanism for pre-loading images and audio

Known Bugs:

  • You cannot access the Adding_Up lesson from google chrome or chromium. It does work if you have the lesson stored on your local machine. This is because chromium does not yet support loading media over HTTP.
  • Knavbar with adding up.
  • The links on ‘kstart’ page to Teacher’s Note and Lesson Note don’t go anywhere
  • The css on stages 2 and 3 of Chakra are all screwed up

Features that didn’t make it into Release 0.1:

  • Internationalization mechanism
  • SVG manipulation
  • Addition of knavbar to adding_up_to_10
  • A refactored version of the Quadrilaterals lesson


  • Bryan Berry
  • Felipe Lopez Toledo
  • Christoph Derndorfer
  • Om Prakash Yadav
  • Rabi Karmacharya
  • Roshan Karki
  • Saurav Dev Bhatta
  • Devendra Khadka
  • Pavel Mocan

Please test out Chakra and our first lesson “Adding up.” We would most appreciate it if you report any bugs you find to our bugtracker on launchpad

Create a free website or blog at