The Karma Project: Code Less, Teach More

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.

//lesson.js

 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.audio.correct, 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(k.audio, function(audio) { audio.play();});

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 k.audio or k.canvas

k.audio.correct.stop().play();
k.svg.capitals.getElementById('capitalMontevideo').setProperty('display', 'none');
k.canvas.scorebox.clear().drawImage(k.image.monkey.media, 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:

 assets/
           audio/
           image/
           svg/
           video/

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.

Advertisements

4 Comments »

  1. […] Introduction to karma.js […]

    Pingback by Tutorial III: Digging into Inkscape « Karma Project Learn.Teach.Everything — December 18, 2009 @ 3:34 am

  2. […] Introduction to karma.js […]

    Pingback by Tutorial IV: The Adventure Continues – JavaScript and SVG « Karma Project Learn.Teach.Everything — December 18, 2009 @ 3:36 am

  3. […] Karma version 0.2 Released Filed under: News — Tags: html5, javascript, karma, svg — bryanwb @ 4:23 pm We are proud to release Karma version 0.2 today. You can test out the demos here. You need Firefox 3.5 or Google Chrome/Chromium to run the demo. You can download the Karma-2.xo bundle here. We now have a well-documented API and a four part tutorial. […]

    Pingback by Karma version 0.2 Released « Karma Project Learn.Teach.Everything — December 20, 2009 @ 4:23 pm

  4. […] 8. Bryan Berry announced the release of Karma Version 0.2 (See http://karma.sugarlabs.org). “The Karma Project aims to create high-quality open-source educational software using openweb technologies for the Sugar desktop educational environment. karma.js is a Javascript library for manipulating HTML 5 and SVG in any context.” Please note that you will need Firefox 3.5 or Google Chrome/Chromium to run the demos. The Karma-2.xo bundle is available at karma-2.xo. There is a Karma tutorial series as well (See [1],[2],[3],[4]). […]

    Pingback by ep - Sugar Digest 2009-12-22 — December 22, 2009 @ 6:20 pm


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: