So — what's a mixin?

Basically, a mixin allows you to extend your Backbone components with utility functions. Let's, for example, say that we have pagination which is similar in many views, but not in all. How should we include this functionality?

We have the following API for adding extra functionality:

UsersView.mixin(Pagination);
AppView.mixin(Transitions);

We have, however, taken the concept of mixins one step further than what I've seen before. In addition to including all the properties which are present in the mixin, our implementation enable mixins to include their own initialize which will extend the existing initialize. When mixing into views a mixin can also include its own render and events. Let's take a look at what this means in practice:

var UserView = BaseView.extend({
    events: {
        "click h1": "user"
    },
 
    initialize: function() {
        console.log("user init");
    },
 
    user: function() {
        return this.model.get("name");
    }
});
 
// This is our mixin:
var Pagination = {
 
    // expects the view it's mixed into to have a link with class `next`
    // present in the DOM
    events: {
        "click a.next": "next"
    },
 
    initialize: function() {
        console.log("pagination init");
    },
 
    next: function() {
        return "next for: " + this.model.get("name");
        // yeah, you would absolutely use a collection as it's named
        // pagination, this was just to keep the example short ;)
    }
};
 
UserView.mixin(Pagination);
 
var model = new Backbone.Model();
model.set("name", "Kim");
 
var view = new UserView({ model: model });
// this initialization console logs (in order):
// "user init"
// "pagination init"
 
console.log(view.user()); // "Kim"
console.log(view.next()); // "next for: Kim"
console.log(view.events); // {
                          //   "click a.next": "next",
                          //   "click h1": "user"
                          // }

As we can see from the code, a mixin has access to this in the same way as the model, collection or view itself. Additionally, mixins can potentially be self-contained, i.e. because initialize, render and events can be extended the component we mix into does not need to know anything about the the mixin. This makes it especially easy to include a new mixin or remove one that is in use.

Implementation

Let's have a look at an example of how these mixins can be implemented. Specifically we will take a look at an implementation of mixins for views:

Utils = {};
 
Utils.viewMixin = function(from) {
  var to = this.prototype;
 
  // we add those methods which exists on `from` but not on `to` to the latter
  _.defaults(to, from);
  // … and we do the same for events
  _.defaults(to.events, from.events);
 
  // we then extend `to`'s `initialize`
  Utils.extendMethod(to, from, "initialize");
  // … and its `render`
  Utils.extendMethod(to, from, "render");
};
 
// Helper method to extend an already existing method
Utils.extendMethod = function(to, from, methodName) {
 
  // if the method is defined on from ...
  if (!_.isUndefined(from[methodName])) {
    var old = to[methodName];
 
    // ... we create a new function on to
    to[methodName] = function() {
 
      // wherein we first call the method which exists on `to`
      var oldReturn = old.apply(this, arguments);
 
      // and then call the method on `from`
      from[methodName].apply(this, arguments);
 
      // and then return the expected result,
      // i.e. what the method on `to` returns
      return oldReturn;
 
    };
  }
 
};

Now we need to include this mixin in such a way that this means the correct thing and we can use it like we saw in the example above. This can be done in two ways, both of which utilize the viewMixin method we created above:

1. As mentioned in the Backbone docs it's okey to add methods directly to a Backbone component. We can use this idea and add mixin like this:

   Backbone.View.mixin = Utils.viewMixin;

2. If you create a layered architecture you can include viewMixin in one of your layers. In our project we had a BaseView which we created all our views from. Remember, this is how Backbone views are defined:

   Backbone.View.extend(properties, [classProperties])

   So, in order to create our desired API we can add mixin as a class property on our BaseView, for example:

   var BaseView = Backbone.View.extend({
     // lots of methods
   }, {
     mixin: Utils.viewMixin
   })

In my project we chose to go for the latter solution as we already had a BaseView.

Testing

Mixins can be tested both by themselves and when mixed into a component. We'll take a look at how the latter can be done.

Jasmine has a great way to include similar tests several places. Davis W. Frank of Pivotal Labs wrote a great blog post about this a year ago. Basically, the point is to write a function that contains regular Jasmine specs. For example:

function sharedBehaviorForPagination() {
  describe("pagination", function() {
    it("should be able to paginate to the next page", function() {
      // ...
    };
 
    it("should not be able to paginate to the next page when on the last page", function() {
      // ...
    };
  });
}

In the specs for the component we mix into we can then call this function:

describe("users", function() {
  // ... lots of users specific specs
 
  sharedBehaviorForPagination();
});

We have now included the shared set of specs into our regular tests for "users". If some shared state is needed, we can change sharedBehaviorForPagination to receive arguments in order to share state. We found this to be a great technique for ensuring that our mixins works as expected in all the components which include them.

When?

Mixins are a simple but potentially very powerful abstraction. We used them for mainly for three things: pagination, local error handling and handling transitions between pages. Basically, we used mixins when we found them to help decouple our code and make each component more focused. The right time to use them appears to be when a component does more than one thing and when we can better separate concerns when splitting to the code.

In this blog post I've only looked at using them for views, but they are also great for breaking up models and collections.

To give credit were credit is due, this blog post, and our solution to the mixin problem, was heavily influenced by Dmitry Polushkin's gist on mixins.

iTouch

App’en som skal lages er et spill, hvor poenget er å taste en gitt tekst feilfritt, raskest mulig. Spillet skal støtte flere samtidige spillere, og alle spillere skal fortløpende se hvordan konkurrenter ligger an underveis, samt status på egen tasting i form av fargekoding av tastet tekst.

Jeg ser for meg en arkitektur der vi kjører JavaScript på server, JavaScript+HTML på klienter, og sanntidsoppdatering av konkurrentstatus over Web Sockets.

Tanken er at på hvert tastetrykk, sender klienten inntastet tekst til serveren for validering. Serveren sender så tilbake et statusobjekt som sier noe om hvorvidt tastet tekst er feil, hvor mye av tekst som gjenstår osv. Det blir så opp til klienten presentere denne statusen til brukeren.

Litt om teknologi

Til Web Sockets-kommunikasjonen skal jeg bruke rammeverket NowJS, som er ganske fascinerende. Det lar deg synkronisere JavaScript-variabler og -funksjoner mellom klient og server, slik at man kan kalle funksjoner på server direkte fra klient, og faktisk også funksjoner definert på klient(er) direkte fra server. NowJS baserer seg på veletablerte SocketIO.

Serverkoden kjører på Node.js, som er blitt en defacto plattform for serverside JavaScript.

Testdrevet utvikling

I JavaScript er det p.t. en rekke testrammeverk tilgjengelig. Jeg har valgt å bruke Jasmine, mest fordi jeg liker BDD-syntaksen, og at man kan benytte rammeverket til å teste både klient- og serverkode. I dag ville jeg nok gått for Buster.JS, men mer om Buster senere.

Man kan fint kjøre Jasmine-tester standalone i en nettleser, men det er fornuftig å benytte seg av en test runner, eksempelvis JS Test Driver. Bloggpost’en til kollegaer Torstein og Børge: ”Getting started with JS and TDD”,  gir en grundig innføring i hvordan Jasmine er i bruk, samt hvordan man integrerer med JS Test Driver.

Det avgjørende her er å få lastet ned riktige biblioteker, lagt disse inn i en fornuftig mappestruktur, og fått satt opp en jsTestDriver.conf-fil til å reflektere denne.  I tillegg kan det være fornuftig å installere “jstdutil”. Dette verktøyet lar deg kjøre kommandoene “jstestdriver” og “jsautotest” fra kommandolinja. Sjekk siden til Christian Johansen for installasjonsbeskrivelse.

Prosjektet mitt benytter altså Jasmine som testrammeverk, og JS Test Driver for å kjøre testene. Når disse tingene er på plass, er man klar til å skrive første test!

Første test

Dette blir litt som å skrive første setningen i en bok, eller i denne bloggposten for den saks skyld. Jeg tenker det enkleste å teste i min kode måtte være mekanismen som validerer inntastet tekst. Jeg ser for meg at vi oppretter en scoringobjekt som tar inn en tekst, og returnerer et statusobjekt som sier noe om hvilke bokstaver i teksten som evt. er feil.

Vi spesifiserer forventet oppførsel i filen spec/scoring.spec.js:

it("should validate text with 2 errors",
function() {
    var typedText = "DeTte Er en test";
 
    expect(scoring.validate).toBeDefined();
 
    var results = scoring.validate(originalText, typedText);
 
    expect(results.errors.length).toEqual(2);
    expect(results.errors).toEqual([2, 6]);
});

og kjører kommandoen ”jstestdriver –tests all –reset”, eller enda bedre ”jsautotest”. Vi får beskjed om å opprette scoring-modulen i namespacet TDD, med funksjonen “validate”. Og etter litt TDD’ing ender vi opp med en mer eller mindre komplett scoring.spec.js  med tilhørende implementasjon scoring.js.

Arkitektur

Før vi går videre med tester, kan vi titte litt på kodearkitektur. I tillegg til scoring-modulen, trenger vi funksjonalitet for å administrere selve spillets gang. La oss gi denne modulen navnet “game”. På klientsiden trenger vi en modul som styrer kommunikasjonen med server og oppdatering av skjermbilder; game_controller.js

Hvis vi skisserer opp systemet, så har vi et avhengighetsbilde som ligner dette:

Vi vet at game benytter NowJS-rammeverket for å formidle sanntidsinformasjon, i tillegg til scoringmodulen for å kalkulere status. Samtidig skal game_controller.js kommunisere med game.js vha. NowJS.

Når man nå skal sette sammen disse bitene, er det viktig å tenke at de skal være løst koblet. Dette kan man få til ved å spesifisere eksterne avhengigheter ved opprettelse av modulene. F.eks., får game.js sprøytet inn en referanse til scoring og NowJS når den blir opprettet, og kode for å opprette et game-objekt blir:

var game = TDD.game.create({
    originalText: "En tekst",
    scoring: TDD.scoring.create(),
    everyone: this.everyone
});

Dette gjør det lett å enhetsteste game.js, da man enkelt kan stubbe/mocke disse avhengighetene.

Mer testing

Nå har det liten hensikt å gå i gjennom all kildekode og tester i teksten her, men vi skal se litt mer på hvordan utvalgt funksjonalitet er implementert og testet.

Når det gjelder game-modulen, skal denne bla. ha funksjonalitet for å

• registrere deltakere
• sette i gang en ny omgang
• distribuere forløpende status til alle deltakere

Hvis vi ser nærmere på det siste punktet, så skal status sendes fortløpende til alle deltakerne i sanntid over Web Sockets vha. NowJS. Web Sockets-kommunikasjonen er fullstendig abstrahert bort av rammeverket, og alt man trenger å gjøre er å legge til funksjoner i det spesielle ”now”-objektet som blir synkronisert mellom server og klient. Rammeverket fungerer slik at man kan adressere server via now-objektet på klienten, samt adressere alle klienter via everyone.now-objektet fra serveren.

Når man vet hvordan dette rammeverket fungerer, er man i stand til å spesifisere testen:

it("should validate text and distribute scores upon validation request",
function() {
    var typedText = "Dette er en";
    var status = {
        "errors": [1],
        "percentage": 98
    };
    spyOn(this.game.scoring, "validate").andReturn(status);
    spyOn(this.everyone.now, 'receiveScores');
 
    this.game.validate(this.everyone.now, typedText);
    expect(this.everyone.now.receiveScores).toHaveBeenCalledWith({
        clientId: "123",
        name: undefined
    },
    status);
});

Her bruker vi spy-egenskapene til Jasmine, til å legge til en forventning om at når man kaller ”validate”-funksjonen på serveren, så skal ”receiveScores”-funksjonen kalles på alle klienter.

Selve this.everyone.now er en stub vi selv spesifiserer:

this.everyone = {
    now: {
        validate: function() {},
        receiveScores: function(clientId, score) {},
        startGame: function() {},
        displayTextToBeTyped: function() {},
        hideStartButton: function() {},
        showStartButton: function() {},
        clearText: function() {},
        gameOver: function() {},
        user: {
            clientId: "123"
        }
    }
};

Igjen, er det bare å implementere spesifikasjonen og kjøre testene:

Firefox 10.0 Mac OS [PASSED] Game.should massage original text
Firefox 10.0 Mac OS [PASSED] Game.should validate text and distribute scores upon validation request
Firefox 10.0 Mac OS [PASSED] Game.should NOT end game when text is errornous
Firefox 10.0 Mac OS [PASSED] Game.should end game when text is complete with no errors
Firefox 10.0 Mac OS [PASSED] Game.should start game on request
Firefox 10.0 Mac OS [PASSED] Validation of text and scoring.should validate typed text
Firefox 10.0 Mac OS [PASSED] Validation of text and scoring.should validate text with 2 errors
Firefox 10.0 Mac OS [PASSED] Validation of text and scoring.should calculate score when typed text is 100% complete
Firefox 10.0 Mac OS [PASSED] Validation of text and scoring.should calculate score when typed text is 0% complete
Firefox 10.0 Mac OS [PASSED] Validation of text and scoring.should calculate score when typed text is incomplete
Total 10 tests (Passed: 10; Fails: 0; Errors: 0) (8.00 ms)
  Firefox 10.0 Mac OS: Run 10 tests (Passed: 10; Fails: 0; Errors 0) (8.00 ms)

Hva med klienten?

Det er like enkelt å teste klientkode som serverkode, selv om man må hanskes med en DOM. Det avgjørende her er å gjøre klientkoden ”unobtrusive” og ikke mikse JavaScript og HTML-markup mer enn nødvendig.

Vi kan begynne med å tenke litt på hvordan markup’en på klienten skal se ut. Da spillet går ut på taste en gitt tekst, trenger vi i hvert fall et editerbart felt, og et element til å presentere tekst som skal tastes. I tillegg kan vi legge til en knapp for å starte en omgang, samt et element for å vise progress bars. Grensesnittet kan f.eks. se slik ut:

med tilhørende HTML:

<!DOCTYPE>
<html>
  <body>
    <div id="wrapper">
      <h1>iTouch</h1>
      <input id="name" type="text" placeholder="Skriv inn navnet ditt her og trykk ENTER"/>
      <button id="startButton">Start ny omgang (vent til alle er klare da)</button>
      <div id="text-to-be-typed"></div>
      <div id="typed-text" contenteditable="true"></div>
    </div>
  </body>
</html>

Med disse antakelsene, kan vi utvikle klientlogikken – test først.

Eksempelvis kan vi spesifisere at spillet skal startes når noen klikker på ”Start ny omgang”-knappen på følgende vis:

it("should do start game when start button is clicked",
function() {
    spyOn(this.game, "startGame");
 
    this.startButton.trigger("click");
 
    expect(this.game.startGame).toHaveBeenCalled();
    expect($(this.startButton).is(':hidden')).toBeTruthy();
});

Denne testen spesifiserer at startGame-funksjonen skal kalles, og at knappen skal skjules.
$(this.startButton) er et jQuery-wrappet element som er definert slik:

this.startButton = $("<button></button>", {
    id: "startButton",
}).appendTo(document);

og sprøytet inn i game_controller-modulens create-funksjon.

Slik kan vi fortsette; ta f.eks. koden som tester at tekst fargelegges korrekt. Ganske avansert GUI-messig, og ganske enkelt å teste da man kan simulere nettleser-eventer, kjøre css-spørringer osv.:

it("should color text upon text validation and update progress bar",
function() {
    var self = this;
    var originalText = "Dette er en test";
    var typedText = "Dette er En";
    var errorIndex = 9;
    var clientId = "123";
 
    spyOn(this.now, "validate").andCallFake(function() {
        self.now.receiveScores({
            clientId: clientId,
            name: "Snorre"
        },
        {
            "errors": [errorIndex],
            "percentage": 95
        })
    });
 
    this.game.now.displayTextToBeTyped(originalText);
 
    this.typedTextElement.text(typedText);
    this.typedTextElement.trigger("keyup");
 
    expect(this.now.validate).toHaveBeenCalled();
    expect($(this.textToBeTypedElement).find(":nth-child(1)").css("color")).toEqual("rgb(0, 128, 0)");
    expect($(this.textToBeTypedElement).find(":nth-child(" + (errorIndex + 1) + ")").css("color")).toEqual("rgb(255, 0, 0)");
    expect($(this.textToBeTypedElement).find(":nth-child(" + (typedText.length + 1) + ")").css("color")).toEqual("rgb(0, 0, 0)");
 
    expect(this.wrapperElement.find("#" + clientId).attr("value")).toEqual(95);
});

Når man lager JavaScript-koden “unobtrusive” (i mangel av et bedre norsk ord), blir man kvitt all spagettikode man ofte ser i $(document).ready(), og sitter igjen med en ryddig index.html.

Hmmm, hvorfor kjører vi alle testene i Firefox?

Inntil nå, har vi kjørt klientestene og servertesten i kontekst av en nettleser via JS Test Driver. Da vi at vet at serverkoden skal kjøre på Node, gir det ikke mening å la ymse nettleser-JavaScript-motorer - og ikke Nodes Google V8-baserte kjøretidsmiljø, tolke koden vår. Vi kan bote på dette ved å kjøre server testene med jasmine-node. Dette er en Node.js-modul, som installeres med npm (som nå bundles med Node-installasjonen). Da kan vi kjøre servertestene våre med:

~/dev/faggruppe/iTouch(git::master):➔ jasmine-node spec/server --verbose
Started
..........
Spec Game
  it should massage original text
  it should validate text and distribute scores upon validation request
  it should NOT end game when text is errornous
  it should end game when text is complete with no errors
  it should start game on request
Spec Validation of text and scoring
  it should validate typed text
  it should validate text with 2 errors
  it should calculate score when typed text is 100% complete
  it should calculate score when typed text is 0% complete
  it should calculate score when typed text is incomplete
Finished in 0.005 seconds
2 tests, 24 assertions, 0 failures

Dette fremprovoserer også det faktum at vi er nødt til å gjøre om scoring.js-modulen til å være Node/CommonJS-kompatibel, da Node krever dette. Dette gjøres ved å legge til disse linjene i scoring:

if (typeof module === 'object') {
    module.exports = TDD.scoring;
}

Man kan da “hente” ut en referanse til scoring-modulen som en vanlig Node-modul slik:

TDD.scoring = require("./src/server/scoring");

Buster

Her kommer vi tilbake til Buster.js. I tillegg til å være et flott testrammeverk på andre måter, gir Buster deg mulighet til å kjøre klient- og servertester med samme test runner. Buster.js er snart ute av beta, blir spennende å sjekke det ut nærmere.

Skru alt sammen

Når all JavaScript-logikken er ferdig implementert, gjenstår konfigurasjon av Node, slik at vi kan begynne å teste spillet. All denne konfigurasjonen gjøres i filen app.js. Her ser vi hvordan vi oppretter et game-objekt, med alle dets avhengigheter.

Her er et artig lite avbrekk i en ellers hektisk prosjekthverdag:

Oppsummering

Å komme fra en typisk hverdag der jeg skriver “mvn clean install” altfor mange ganger i løpet av en dag, er det utrolig frigjørende å se hvor raskt disse JavaScript-testene kjører. Når man først kommer inn i det, er JavaScript en fornøyelse å jobbe med, spesielt med tanke på egenskapene ved språket. TDD i JavaScript er definitivt ikke vanskelig, og det er like greit å lære seg teknikkene først som sist.

On a side note:

Magnar Sveen snakker om zombietdd-prosjektet sitt i morgen på Framsia at CiA 2012 – Responsive, realtime and Zombies! Meetup’en omhandler forøvrig Web Sockets og Node.js, så det er ikke helt urelatert til det som blir tatt opp her!

Are you working on unmaintainable JavaScript code? Are you afraid to make changes to your 5000+ lines long JS file? If so, you’ve probably not written tests or done TDD. Fear not! Read on, and we will show you how to get started with writing tests and setting up the needed tools. We will show by example how to create a small, yet complex, JS web application using TDD.

JavaScript is becoming increasingly popular for developing full-fledged applications – both server and client side. Looking at the current trend of how JS is used, we can see that it’s being used for business critical applications and large-scale applications. With all this popularity and extensive use, we are under the impression that the testing and quality focus is lagging behind.

After reading this blog post, you will know how to get started with JS TDD using tools and frameworks we consider easy to use and relatively mature. If you already know why you should test your JS code, feel free to skip the background.

If you want to take a closer look at the example application, feel free to check out the entire project from GitHub @ http://github.com/bekk/jstdd.

Background

JavaScript has received a popularity boost from browser vendor’s quest to write the fastest JS engine, as well as the popular programming language node.js. In addition, jQuery has simplified the way we interact with the DOM and smooths over annoying browser differences – making JS more accessible for everyday developers. Focus have been primarily on producing functionality, and not on testing and good design/clean code. We believe that one reason is the lack of standardized or commonly available testing tools and frameworks. Another reason might be that traditionally JS have been written by UI and UX developers, who’s focus have been primarily on functionality – not on Clean Code and testability.

JS and all other dynamic programming languages is in dire need of tests since there is no compile-time checking. Tests can be used to ensure that the application behaves as expected, and gives developers confidence to make changes to existing code. Despite the obvious need for testing, many developers skimp on writing tests when developing large JS applications. All the advantages of TDD that applies for other programming languages, also applies for JS. Who does not want testable, maintainable, readable, well-designed, modular and working code? It’s well established that TDD has positive effects on code quality (read the chapter on TDD by Robert C. Martin in The Clean Coder).

Other popular programming languages like Java and C# have mature and well-documented testing-tools. At the time of writing, JS has several testing frameworks available, but only a handful mature. Looking at the options, no one really stands out as a clear choice. To make things worse, getting started with JavaScript TDD can be challenging. There are so many ways of going about setting up a complete test-environment for JS. We have looked into this and had some experience with what works and what doesn’t.

The runner

JsTestDriver is (as it’s name implies) a tool that let you run your JS tests. You can run your tests directly from your favorite IDE (at least in theory) to get into your TDD rhythm. It runs from the command line and even on your continuous integration server. In our examples we’ll be running it from the command line.

A quote from their home site says it all: “The goal of JS Test Driver is to make JavaScript unit test development as seamless as and easy as Java unit tests.”

JsTestDriver supports testing in different browsers through capturing browsers as a slave machines. It includes it’s own limited assertion framework, but also supports add-ons, which opens for a wide range of third party assertion frameworks. We will be using Jasmine BDD through an adapter.

As with everything else, there is room for improvement. JsTestDriver’s configuration can sometimes be too simple, and advanced users may feel limited. In our simple example it works great, but expect some issues when scaling up. As a note, we did not get the IDE integration in IntelliJ IDEA to work properly.

Recently Buster.js was released as beta, and is worth checking out as an alternative to JsTestDriver.

The framework

We’ve picked out Jasmine because it is a mature (compared to most other frameworks) and a popular testing framework for JS. It features BDD syntax, which gives clear and readable tests with functionality in focus. It does not depend on any other framework and does not require a DOM. It can be run in the browser, through JsTestDriver or through node.js. It is well documented and is easy to get started with.

There are a few things to consider. They don’t separate between mocks, stubs and spies. All of that is packed into what Jasmine describes as a spy. The bundled matchers are good, but few. To get readable tests, it’s often necessary to write custom matchers to match the domain language. Still, we consider this one of the few viable options for doing TDD in JS.

Installing, setting up and using Jasmine is easy, and will not be detailed here. We’re using Jasmine through JsTestDriver, and have configured it thereafter.

QUnit was considered as an option, but it’s syntax did not help us achieve as readable and clear tests as Jasmine. It’s simplicity makes it very attractive and useful for beginners, but more advanced users will want more.

Demo application

As stated in the introduction, we’ll make a little application that does an “I feel lucky” search from Flickr. One of the choices we made was to have a minimal setup. No jQuery and third-party libraries in the production code, with the intention to reduce complexity and make the example more transparent as to how things work.

Pre-requisites

If you want to use the same setup as us, we recommend doing the following.
(Or you can check out the entire project from GitHub @ http://github.com/bekk/jstdd).

Download these libraries:

• https://github.com/ibolmo/jasmine-jstd-adapter (version 1.1.1)
• https://github.com/pivotal/jasmine (version 1.0.1)
• http://code.google.com/p/js-test-driver/ (version 1.3.2)

Create the following folder structure:

.
├── lib/ # 3rd party libs lies here
│   ├── jasmine.js
│   ├── jasmine-jstd-adapter/
│   └── JsTestDriver-1.3.2.jar
├── spec/ # test/specs lies here
├── src/  # application source lies here
├── server.sh # Starts a JSTD server (symlinked)
├── test.sh # Runs the test (symlinked)
└── jsTestDriver.conf # JSTD configuration for our project

server.sh and test.sh are just shortcuts to scripts bundled with js-test-driver.

Configure jsTestDriver.conf to match your setup.

Getting familiar with the framework

We started off with a simple test to get familiar with the syntax and to verify that everything is set up correctly. Consider it a warm-up exercise.

describe("Jasmine", function() {
    it("makes testing JavaScript awesome!", function() {
        expect(true).toBeTruthy();
    });
});

Running it

Running it the first time might seem a bit overly hard, but once you’re set up it’s easy to run the tests. Before you start the server, you need to write a little config file. Take a look at ours if you need an example.
Starting the server can seem a bit tedious, but we found a shell-script that starts the server. All we had to do was modify the path to suit our project structure (see server.sh). Running it is just a matter of typing ./server and seconds later the server is up and running.

Example output from a test run:

Running all tests
Chrome: Runner reset.
....
Total 1 tests (Passed: 1; Fails: 0; Errors: 0) (1.00 ms)
Chrome 12.0.742.112 Mac OS: Run 4 tests (Passed: 1; Fails: 0; Errors 0) (1.00 ms)

Next task is capturing browsers. We spun up browsers on each others computers and went to http://[my address]:9876/capture and the browser became a slave. Excellent! We used Safari, Firefox and Chrome to test. Make sure to keep the browser running while testing.

Captured browser

JsTestDriver supports distributed test-running, but that is not something we will explore in this blog post. Now all that is left is telling the server to ask the browsers to run the tests. With the scripts, it’s just a matter of typing ./test in the shell and the tests are run.

The flow for starting the first time is the following:
1. Start server
2. Capture browsers
3. Run tests

After than you just type ./test each time you want to run the tests.

Working on LuckyFlickr

Start with the tests

We decided to start with writing tests to verify output on the result page. The simplest possible test we could think of was to test for a message when no result was found.

Next, we added a new test to verify that if a result were received, the parser would pick the first result and display the image on the result page. Since we were doing unit testing we didn’t want to go all the way to Flickr when we ran the test, so we created a simple stub that returned some JSON data on the expected flickr format so we could run the test in isolation. The specs for the parser read:

• “outputting result”
• “should not output an image when there are no results”
• “should output the image from the result”

Note: When reading these specs, read them like “Outputting result should not output an image when there are no results”.

When pondering what to do next, we figured we could create a test for the component that would fetch data from flickr. Since we wanted to get out data from another site, we decided to use JSONP to overcome the cross-site problem. We also wanted the component to send the flickr request asynchronously, so we had to write a test that would handle that. To fix this we created setup code to temporarily replace the default XMLHttpRequest implementation in JS with our own. That way we could control what the response would be. We decided to let it respond with the same JSON stub as in the parser test.

• “when querying flickr”
• “should create a global function that handles the JSON-P callback”
• “should do a search and call the callback function”

The last step was to create some tests to make sure the GUI was displaying the result in the right container in the result page. On this step, we saw that some of the components came together, and introduced the need for mocking. We mocked the result given by the “fetcher”. Doing so, we’re not dependent on a connection to flickr.com. We created 2 tests for this. The first asserts that the result from flickr is displayed in the result container, and the second one asserts that “Loading” is displayed while it is fetching data from flickr.

The result

Since our focus was unit testing, our implementation ended out with three separate “units” that each did one important thing. We have a “fetcher” that goes out and fetches the result from Flickr, a “result parser” that knows how to parse the JSON data structure from Flickr and finally the component that enables the user to do a search. No enterprisy patterns, no unneeded complexity, no silver bullets. Just enough to make things work. Also, the design emerged from writing the tests first.

Our experiences

We experienced a couple of notable challenges when doing TDD in JS. Doing TDD in it self is not a problem. Some challenges appear when doing browser-specific things with JS. Such as asynchronous callbacks, handling the DOM and the AJAX browser API.

The DOM is an issue. When not using jQuery, there are a lot of quirks that can mess up tests in specific browsers. Also, doing DOM-operations without jQuery results in a lot of ugly code that affects readability.

Testing AJAX without support from the test framework is problematic, and is why several tools exist and mitigate this (Sinon.js, Mockjax, etc.). Before we changed to JSONP, we wanted to do this with no extra support, and ended up with an extremely simplified version of what the mentioned tools provide. But for most people it would be simpler to use an existing tool to help you do AJAX-testing.

But all these things mentioned above are relatively easy to overcome and the upside of being able to write tests for your JS code easily outweighs the small quirks you may experience. And you won’t regret spending time on writing tests when your code base is expanding and you need to make a change.

Give me more!

Sinon.JS – Standalone test spies, stubs and mocks for JavaScript. Works with any unit testing framework.
QUnit – alternative to Jasmine. Developed by the jQuery-team
Cucumber.JS – early stages. Could be good.
Buster.js – a new test framework (currently in beta) from Christan Johansen (the man behind Sinon.js)

I disse dager hvor server-side er ut og klient-side er kult har det dukket opp mange avanserte JavaScript-rammeverk som flytter kompleksitet fra serveren til nettleseren. Backbone, Knockout og JavaScriptMVC er alle gode eksempler som kan brukes til å lage komplekse applikasjoner, uten antikvariske operasjoner som lasting av hele sider eller rendering av HTML på serveren. I denne nye verden tilbyr serveren et REST-API, og all koden for å bruke dette API-et er Javascript som kjøres av brukerens nettleser.

Vi vil gjerne presentere én metode for å strukturere komplekse JS-applikasjoner, sammen med to flotte biblioteker: Sammy og Handlebars.

Sammy er ikke like kjent eller kraftig som de tidligere nevnte rammeverkene, men er likevel svært godt til sitt bruksområde og fortjener en vurdering ved valg av rammeverk. Hovedsakelig brukes Sammy til routing, hvor en URL besvares av en JS-funksjon, og til å rendre HTML-en som skal vises på den aktuelle siden. Biblioteket er i seg selv svært lite, og delegerer det meste av funksjonalitet til sin strålende plugin-arkitektur. I dag er Sammy tungt avhengig av jQuery.

Handlebars har den siste tiden fått masse oppmerksomhet, og bygger på det allerede kjente template-rammeverket Mustache. Handlebars brukes til å sammenflette data og HTML på en enklere og strukturert måte. Hensikten er å skille HTML- og DOM-maipulasjon fra resten av applikasjonen, og Handlebars inneholder mange hjelpemetoder som gjør dette ganske elegant.

Model-View-Controller (MVC) er en type arkitektur som kan brukes til komplekse klient-side JS applikasjoner. I vår (svært) løse definisjon av MVC får vi følgende struktur:

• Datamodellene håndterer entiteter og kommunikasjon med serveren.
• View-modellene står for oppførselen og strukturen til HTML-elementene.
• Controllerene knytter datamodeller og view-modeller sammen mot spesifikke URL-er.

God struktur er vanskelig i komplekse JS-applikasjoner. Språket gir store muligheter og få begrensninger, og ingen forslag til hvordan strukturen bør være. Det hele kan fort bli uoversiktelig hvis man ikke baserer seg på velkjent struktur, som for eksempel MVC. I denne teksten bygger vi deler av en slik applikasjon.

I eksempelet har serveren en liste personer, som vi ønsker å få tak i, instansiere som modeller og vise en liste av i nettleseren. All kode i denne bloggposten kommer fra en minimal eksempelapplikasjon du finner på Github. Last den gjerne ned og prøv resultatet i din nettleser. Koden kan også brukes som refferanse om det er noe som er uklart i teksten.

Datamodeller og API-kall

Datamodellene tar seg av kommunikasjon med serveren via Ajax-baserte HTTP-kall mot et REST-API. Det er mange måter dette kan gjøres på, det finnes ingen fasit, men her kommer ett eksempel. Her har vi kodet modellene selv, men merk at på samme måte som Handlebars tar seg av templates, og Sammy tar seg av controller-ene, kunne vi brukt et tredje bibliotek til å ta seg av datamodellene. Men la oss lage noe selv.

Noen vil kanskje reagere på at datamodeller her potensielt defineres to steder — hos klienten og på serveren — men det er viktig å huske at disse modellene har lite felles funksjonalitet. Datamodellene på klientsiden er der utelukkende for å hjelpe view-modellene, ved å abstrahere bort funksjonalitet for kommunikasjon med serveren, formatering av modelldata og lignende.

Det er to oppgaver som kan skilles i datamodellene:

• Selve datamodellene som instansieres og har metoder for å jobbe med hver entitet,
• og statiske metoder for hver klasse av modeller, som blant annet gjør API-kall.

Vi har valgt å bruke standard prorotype-baserte JS objekter. I dette eksempelet lager vi en modell kalt “person”, lagt under namespacet “myapp.models”.

/* prototype for alle data-modeller. */
myapp.model.datamodel = {};
 
/* Metode for å instansiere en modell. */
myapp.model.create = function(prototype, properties) {
    return myapp.model.merge(Object.create(prototype), properties);
};
 
/* Prototype for person-instanser. */
myapp.model.person = myapp.model.create(myapp.model.datamodel, {
    name: function() {
        return this.firstname + " " + this.lastname;
    }
});
 
/* Instansiering. */
var person = myapp.model.create(myapp.model.person, { 
    firstname: “Foo”, 
    lastname: “Bar” 
});

Som sagt kan API-kall tilhørende hver modell skilles ut i egne moduler. Dette er flott når man skal teste systemet, og hjelper holde kompleksiteten nede. Her er et enkelt eksempel på API-kall for modellen:

/* Metode for å lage mange instanser. */
myapp.model.createAll = function(prototype, propertiesList) {
    return propertiesList.map(function(properties) {
        return myapp.model.create(prototype, properties);
    });
};
 
/* Metoder for å gjøre kall mot person-API. */
myapp.api.person = {
    all: function(callback) {
        /* Hent listen over alle personer fra serveren. */
        $.ajax({ 
	    success: function(serverdata) {
                callback(myapp.model.createAll(
                    myapp.models.person, 
                    serverdata));
            },
            ........
        });
    }
};
 
/* Bruk */
myapp.api.person.all(function(people) {
/* “people” er her et array av person-instanser. */
});

Dette kan virke som mye kode for enkle operasjoner, men etterhvert som applikasjonen blir større er det fint å ha alt som har med serverkommunikasjon og datamodeller skilt fra resten av applikasjonen. La oss nå se hvordan disse datamodellene kan kobles sammen med rendring av HTML.

View-modeller med Handlebars

View-modellene knytter data sammen med HTML. Disse modellene holder på dataene som trengs for å vise en side, representert av datamodellene. I tillegg legger view-modellene på oppførsel, animasjoner og hendelser på siden-, eller delen av siden de representerer. Dette kan for eksempel være ting som skal skje når brukeren klikker på en link, flytter på elementer eller vil lagre eller endre data.

Poenget med å bruke view-modeller er å abstrahere bort alt som omhandler hvordan HTML skal produseres og oppføre seg. På samme måte som datamodellene innkapsulerer alt som har med entiteter og server-kall, tar view-modellene seg av all JS-kode som manipulerer DOM-en direkte. Målet er som alltid å ende opp med veldefinerte og klart avskillte moduler med hver sine oppgaver. Her er et eksempel på en view-modell:

myapp.view.people = myapp.model.create(myapp.model.viewmodel, {
    compile: function() {
        return { people: this.people };
    },
    apply: function() {
        $("#people li").click(function(event) {
            alert($(this).text() + " clicked!");
        });
    }
});

En view-modell jobber i to faser og trenger to forskjellige metoder. For det første har vi compile-metoden, som returnerer alle variabler som skal kunne brukes fra template-filen. Deretter har vi apply-metoden, som kalles etter at template filen har blitt renderet.

Den første metoden gjør altså klar variabler som skal brukes, mens den andre tar seg av all DOM-manipuilasjon etter at HTML-en er rendret. Apply-metodene til view-modellene er altså de eneste stedene i applikasjonen JS-kode jobber direkte med HTML-elementer, noe som gjør det hele svært ryddig. Se eksempelapplikasjonen på GitHub [g] for mer av koden som jobber med view-modeller.

View-modellen jobber med en eller flere template-filer, som spesifiserer strukturen på markup-en til den aktuelle siden. Her er et eksempel på en slik template-fil:

<div id="content">
{{ >search }}
    <ul id="people">
    {{ #each people }}
        <li>{{ name }}</li>
    {{ /each }}
    </ul>
</div>

I Handlebars bruker man Handlebar Expressions til å hente ut objekter ved å skrive {{ objektnavn }}, eller {{{ objektnavn }}} når man ønsker å un-escape. people er definert av view-modellen og brukes direkte i template-filen. name er definert av data-modellen for person-entiteten, som også brukes direkte i dette templatet.

I templaten har vi også en partial komponent, kalt search. Partials vil bli brukt der man ønsker å dele opp templates og lage gjenbrukbare deler som kan brukes på tvers av andre templates. Partial-templaten vil også ha direkte tilgang til view-modellen og dens innhold, men vil som oftest tilhøre en egen view-modell.

I tillegg til å kunne hente ut objekter og kjøre funksjoner, kan man bruke såkalte Block Expressions. Block Expressions gjør det mulig å kjøre Block Helpers som er hjelpefunksjoner for å eksempelvis gjøre operasjoner med lister og sjekke verdier med if/else spørringer. Handlebars kommer med ett sett innebygde helpers, men man kan også lage sine egne om dette skulle være nødvendig.

Her er et eksempel på en Block Helper, som kjører en loop inntil et visst maksimalt antall ganger:

/* Definering av en egen hjelpemetode kalt “until”. */
Handlebars.registerHelper('until', function(context, block) {
    var max = block.hash.max;
    var ret = "";
    for (var i = 0, j = context.length; i < j; i++) {
        if (i >= max) { return ret; }
        ret = ret + block(context[i]);
    }
    return ret;
});

/* Bruk av denne hjelpemetoden i en template-fil. */
{{ #until persons max="3" }}
    {{ name }}
{{ /until }}

En annen interessant mulighet man har i Handlebars er å gjøre kall mot parent-objektet til det objektet man jobber med. Her er et eksempel hvor vi bruker notasjonen “../” til å aksessere en variabel som tilhører parent-objektet til det vi looper gjennom:

/* Variabel definert i view-modellen. */
this.family = { surname: “I skogen”, members: [
    { name: “Hans”, age: “90” },
    { name: “Grete”, age: “100” },
    { name: “Ulven”, age: “120” },
]};

/* Bruk av variabelen i template-filen. */
{{ #each family.members }}
    {{ name }} {{ ../surname }}
{{ /each }}

Dette er selvfølgelig bare noen få av muligheten man har med Handlebars, men de viser hvordan komplekse templates kan spesifiseres i template-filer som jobber direkte mot en view-modell. Dette sørger for praktisk innkapsulering av alt som dreier seg om HTML og DOM-elementer i applikasjonen.

La oss nå se hvordan det hele kobles sammen ved hjelp av controller-ene og Sammy.

Controllere med Sammy

Controller-ene er selve limet som holder applikasjonen sammen. Disse beskriver hva som skal skje når en bruker besøker en URL. Controlleren bruker datamodellene til å hente data som trengs på den aktuelle siden, og rendrer HTML ved hjelp av de tidligere nevnte view-modellene og deres representative template filer. Vi trenger både routing og template-rendring, altså er dette en perfekt oppgave for Sammy.

Vi ønsker å bruke Sammy-spesifikk kode utelukkende i controller-ene, og ikke i andre deler av applikasjonen. På denne måten vil minst mulig av applikasjonen bli avhengig av dette rammeverket, i tilfelle man skulle ønske bytte det ut på et senere tidspunkt. I tillegg blir applikasjonen enklere å teste, spesielt på enhetsnivå, da vi ikke trenger å bry oss om Sammy annet enn i controller-ene.

Her er en kodebit som kjøres når brukeren gjør en GET-request mot URL-en “/#people”:

/* Jobb på HTML-elementet “#page”. */
$.sammy("#page", function() {
    /* Bruk Handlebars-plugin. */
    this.use('Handlebars', 'hb');
 
    /* Start routes. */
    myapp.route.person(this);
}).run();
 
 
/* Route for person-listen. */
myapp.route.person = function(app) {
    /* Definer en route. */
    app.get("", function(context) {
        /* Gjør et kall mot serveren. */
        myapp.api.person.all(function(people) {
 
            /* Definer hvilken template-filer som trengs. */
            var template = "template/person-list.hb";
            var partials = { searchbox: "template/shared/searchbox.hb" };
 
            /* Instansierer view-modellene */
            var search = myapp.model.create(myapp.view.shared.searchbox);
            var list = myapp.model.create(myapp.view.people, { people: people });
 
            /* Bytt ut innholdet i "#page" med ny HTML. */
            context.renderAll(template, partials, [list, search]);
        });
    });
};

Den første kodebiten sier at Sammy skal jobbe på HTML-elementet med ID-en “page”, definert i den initsielle HTML-filen. Del to tar tak i URL-en ved hjelp av en route-funksjon. En route består av et verb, en sti, og en callback-funksjon. Verbet er et av de velkjente HTTP-metodene POST, PUT, GET eller DELETE. Stien kan enten være en vanlig URL, eller en hash-basert URL som i dette eksempelet.

Hver Sammy-rute tar inn et context-objekt som inneholder mye informasjon om tilstanden til applikasjonen. Dette objektet inneholder også mange nyttige hjelpefunksjoner. For at applikasjonen skal holde seg modulær er det viktig å kunn bruke dette objektet i controllerene. Hvis context-objektet blir med til datamodellene eller view-modellene, vil disse bli avhengig av Sammy-logikk, som igjen vil komplisere testing og vedlikehold.

Det meste skjer i context.renderAll-metoden. Denne rendrer et template, et sett partials og en samling view-modeller ved hjelp av Sammy’s context-render-metode:

context.helpers({
    /* En hjelpefunksjon for å rendre sider med mange view-modeller. */
    renderAll: function(tmpl, partials, models) {
       	var context = this;
       	this.render(tmpl, myapp.model.compileAll(models), function(html) {
            context.swap(html);
            myapp.model.applyAll(models);
        }, partials);
    }
});

context.render tar først inn stien til template-filen man vil bruke. Det neste argumentet er dataene man vil bruke til å rendre template-filen, i vårt tilfelle representert dataene av en view-modell. Denne view-modellen vil da være tilgjengelig for template-filen når den rendres av Handlebars-pluginen til Sammy.

Callback-argumentet context.swap tar imot ferdig rendret HTML, og bytter ut hva som allerede er i elementet som jobbes på (“#page”) med den nye HTML-en.

Det siste argumentet, “partials”, er et objekt som kan inneholde flere deler som hovedtemplaten er avhengig av, for eksempel en topp, meny og bunn. Render-metoden cacher template-filene, uten å laste de på nytt hver gang, slik at operasjonen blir kjappere andre gang denne kalles.

En fin måte å organisere disse Sammy-routene på er å ha én JS-fil pr side (hvis det gir mening i applikasjonens sidestruktur, vel å merke). Metoden $.sammy kan brukes på tvers av filer uten problemer. Hver side får ofte flere routes for forskjellige operasjoner, for eksempel:

/* settings.js: routes for én side. */
 
$.sammy(“#page”, function() {
    // Vise innstillinger
    this.get(“#/settings/profile”,  function(context) { … });
    this.get(“#/settings/friends”,  function(context) { … });
 
    // Lagre innstillinger
    this.put(“#/settings/profile”,  function(context) { … });
    this.post(“#/settings/friends”, function(context) { … });
});

Med controllerene på plass er applikasjonens struktur komplett:

• Datamodellene innkapsulerer alt som beskriver entiteter og serverkall.
• View-modellene innkapsulerer alt som beskriver HTML-en og oppførselen til DOM-elementer, og kobler dette med datamodellene.
• Controllerene tar det hele i bruk og bruker datamodellene og view-modellene til å rendre flott HTML når brukerne besøker forskjellige URL-er.

Oppsummering

Selv om en struktur som den presentert her kan virke overdrevet i starten av et prosjekt, vil det hjelpe etterhvert som kompleksiteten og kodemengden øker. Det viktigste er å starte med et godt utgangspunkt, og deretter kontinuerlig forbedre og utvikle arkitekturen.

Det er selvfølgeilig ulemper med tunge JS-applikasjoner. De setter store krav til nettleserens JS-motor, og til utviklernes testing på tvers av mange nettlesere. Språkets frie natur gjør det enkelt å skrive lite vedlikeholdbar kode, og det er sjelden klare svar på hvordan noe bør gjøres.

Til syvende å sist krever komplekse JS-applikasjoner mye av disiplin innen struktur og testing, men denne friheten betyr også at JS-programmering er veldig spennende. Med gode biblioteker som Sammy og Handlebars blir det hele enda morsommere.

1. april 2011 lanserte Enonic sin CMS som open source i tillegg til sin standard Enterprise utgave. Enonic CE 4.6 (Community Edition) er det offisielle navnet. De har opprettet en egen sone på GitHub der all koden ligger og man kan samtidig følge utviklingen av versjon 5.0 som er under utvikling. Det mest spennende som er å finne på GitHub er pakkemalene. Her kan man plukke funksjonalitet som er gjennomtestet og som funker veldig bra som et utgangspunkt, og det vil også funke 100 % slik de allerede er på et mindre nettsted. Man trenger da kun å endre på designelementer og CSS’en.

Når du har lastet ned Enonic CE fra GitHub og du har installert den lokalt for testing står det veldig greit i dokumentasjonen om hvordan du kommer i gang.

Walkthrough

• Connect to WebDAV and upload the resources.
• Edit your site and set the Internal Resources to ‘/config/*’ where * contains a valid config.xml file
• Set the Public Resources to ‘/_public/themes/’
• Set Device Classification Script to ‘/libraries/resolvers/device-classification.xsl’

Start developing!

Etter du har logget deg inn i adminkonsollet kan du laste ned og konfigurere en del innholdstyper for å teste CMS’et. Eksempler på innholdstyper, som passer med pakkemalene du har lastet opp via WebDAV, finner du her. Disse xml-filene skal ikke lastes opp i WebDAV men du må gjøre litt god gammeldags cut’n'paste inn i konsollet. Når du har dette på plass kan du opprette mapper/kategorier i Innholdsarkivet og komme igang med litt innholdsproduksjon. Å produsere innhold er alltid tidkrevende og kan du i prosjektsammenheng definere innholdet på et så tidlig tidspunkt som mulig og før siten er ferdig kodet opp kan innholdsprodusentene få startet arbeidet sitt så tidlig som mulig.

Sett at du har en del testinnhold klart og skal begynne å implementere maler (xslt). Hvor skal man begynne? På hvilket nivå skal man tenke responsivt? Er det behov for responsivt design? Det er jo ikke helt sikkert at det er det. Hvis det er et eksisterende nettsted som skal lages på nytt kan det være lurt å ta en titt på besøksstatistikken og spesielt da forholdet mellom besøkende med og uten mobiltelefon eller tablet. Når man har en god oversikt over hvilke nettlesere og enheter som besøker siten må man se på målgrupper og strategi. Men det er utenfor scope av denne artikkelen så nå er det på tide å hoppe inn i malverket.

I Enonic CMS ligger det støtte for en device-detektor. Den hekter du på nettstedet ditt i adminkonsollet om du vil bruke denne som utgangspunkt. Det er lurt å ta denne i bruk uavhengig om du skal ha responsivt design eller ikke. Det er her informasjonen til hvilke breddeverdier de forskjellige regionene på sidene dine innehar. Dette brukes igjen til dynamisk skalering av bilder.

I pakkene som du allerede har lastet opp kan du starte med å titte på theme.xml. Denne xml-fila finner du på roten av siten din. Du finner den i dav’en her omtrent:

dav: /themes/<navn-på-demosite>/theme.xml

Når man jobber med denne fila er det greit å ha oversikt over designet som skal implementeres. Man trenger å vite maksbredder på bilder/grafikk i de forskjellige regionene som siden kan deles opp i. Vi tar en liten titt på xml’en

<theme>
    <region-prefix/>
    <accessibility>
        ...
    </accessibility>
    <device-classes>
        <device-class name="pc,unknown,mobile">
            <layout name="default">

                <area width="950">
                    <region name="north">
                        <width>950</width>
                        <margin>
                            <bottom>10</bottom>
                        </margin>
                    </region>
                </area>
                <area width="950">
                    <region name="center" role="main" element="section" class="wide">
                        <padding>
                            <right>30</right>
                            <left>30</left>
                            <top>30</top>
                            <bottom>30</bottom>
                        </padding>
                        <scalable>true</scalable>
                        <system>true</system>
                    </region>
                    <region name="single-sidebar" element="aside" role="complementary">
                        <width>180</width>
                        <margin>
                            <right>10</right>
                        </margin>
                    </region>
                    <region name="east">
                        <width>180</width>
                        <margin>
                            <left>10</left>
                        </margin>
                    </region>
                </area>
                <area width="950">
                    <region name="south">
                        <width>950</width>
                    </region>
                </area>
            </layout>
            <image>
                ... bilder
            </image>
            <styles>
                ... css-filer
            </styles>
            <scripts>
                ... js-filer
            </scripts>
        </device-class>
        <device-class name="pc,unknown,mobile">
            ...... ipad spesifikk kode
        </device-class>
    </device-classes>
</theme>

Strukturen er oversiktlig nok når man er vant til malverket til Enonic men det er regionene her som er interessante.

<region name="single-sidebar" element="aside" role="complementary">
<region name="center" role="main" element="section">

Det er støtte for html5-elementer i malverket og man kan definere det enkelt ved å bruke dette oppsettet her. Dette er da tenkt som globale elementer i html-kilden. Strukturen settes opp her og støttes videre med global css slik at rammeverket sitter dønn selv uten innhold på siden. Det er fint å kunne teste siten så tidlig som mulig.

Disse navnene på regionene, hhv. single-sidebar og center, blir nå hardkodete navn som må gjenspeiles i sidemalen som til slutt skriver ut html-koden på sidenivå. Denne fila heter page.xsl og den finner du på samme nivå som theme.xml. Når du senere skal lage flere siter er det fint å klone disse filene, opprette ny mappe under /themes/, dumpe filene her, opprette nytt nettsted i Enonic og deretter koble de nye malene på nettstedet og sidemalen og du er i gang med å lage site nr 2. Gjenbruk er gull.

Hvis vi tar en titt på page.xsl ser man kjapt hvor regionene defineres

<!-- regions -->
  <xsl:param name="north">
    <type>region</type>
  </xsl:param>
  <xsl:param name="single-sidebar">
    <type>region</type>
  </xsl:param>
  <xsl:param name="center">
    <type>region</type>
  </xsl:param>
  <xsl:param name="east">
    <type>region</type>
  </xsl:param>
  <xsl:param name="south">
    <type>region</type>
  </xsl:param>

Disse navnene må være like som i theme.xml. Når det er på plass kan man starte utviklingen. I theme.xml har jeg satt opp 960px som bredde for standardoppsettet mitt. Hadde jeg konfigurert nettstedet også for tablet og smartphone ville jeg lagt på to device-classes og definert breddene som f.eks. 768px og 320px eller eventuelt ytterpunktene med høyest oppløsning i landscape-modus. Dette vil da være størrelsen som bilder som skrives ut i de forskjellige regionene vil ha. Alt skjer via dynamiske funksjoner som man kan laste opp fra pakkene og bruke fritt i malene. I en artikkelmal kan man tenke seg at man kaller på et bilde slik:

<xsl:call-template name="image">
	<xsl:with-param name="size" select="'wide'"/>
	<xsl:with-param name="image-path" select="image/@key"/>
	<xsl:with-param name="class" select="'list-image'"/>
</xsl:call-template>

Her sier jeg til bildefunksjonen at den skal skrive ut bildet med full bredde i widescreen-format og samtidig legge på en klasse med navn “list-image”. Hvis man bruker standardoppsettet uten noen som helst form for tweaking blir dette en fast størrelse på bildet og ikke så skalerbart. Nå gjelder det å ta en titt på include-fila som skriver ut bilder. Den heter image.xsl og den finner du her: /libraries/utilities/image.xsl

Se etter templaten som heter “image.display-image“. Den er stor og kompleks og du trenger ikke endre så mye her, bare kommentere ut bredden og høyden til bildet som til slutt skrives ut. Se etter:

<xsl:if test="$width">
	<xsl:attribute name="width">
		<xsl:value-of select="$width"/>
	</xsl:attribute>
</xsl:if>
<xsl:if test="$height">
	<xsl:attribute name="height">
		<xsl:value-of select="$height"/>
	</xsl:attribute>
</xsl:if>

Når dette er kommentert ut er det bare å styre bredden til bildene enkelt via css slik:

img {
	max-width: 100%;
	height: auto !important
}

Ganske enkelt egentlig. Nå er det opp til deg og dine CSS-Ninja-egenskaper for å gjøre resten, men husk, vær smart og bruk device-detektoren i malene og scope hva slags enhet du jobber mot. Det vil optimalisere ytelsen og farten på siten. Du kan også justere innholdet og tilpasse siten på en mye enklere måte. Du kan gjøre dette helt ute i rammeverket og inne i portletene. Lag sjekker på device og tilpass bildet ditt. Ikke noe vits i skrive ut et 960px bilde for så å skalere det ned til 320px på en iPhone. Da er det bedre å bruke dette opplegget og skrive ut et bra skalert bilde fra serveren som passer til den devicen du har i målgruppen din. Malverket til Enonic baserer seg på XSLT og er du god på XSLT, XHTML og CSS er det bare moro herfra og frem til siten skal lanseres.

Lykke til.

"QUnit er et lettvektig rammeverk
for enhetstesting i JavaScript"

QUnit er et lettvektig rammeverk for enhetstesting i JavaScript. Denne artikkelen forklarer hva QUnit gjør og hvordan man bruker det. Med QUnit kan du blant annet:

• Enhetsteste din eksisterende kode
• Få testresultatene opp formatert på en side
• Teste asynkron kode, som f.eks. animasjoner eller ajax
• Teste server-side kode
• Fasilitere automatisert testkjøring og resultatrapportering

QUnit bygger på jQuery — det populære Javascript-biblioteket — og blir brukt som det interne testverktøyet på jQuery-teamet. Slik ser testresultater ut i QUnit:

QUnit basics

En demonstrasjon sier mer enn tusen ord. Slik skriver man en enkel test i QUnit:

test('Beskriv testen her', function() {
   var x = Math.max(3, 4);
   equals(x, 4);
   var y = Math.max(3, 4);
   notEquals(x, y, "Beskriv evt. assertion her");
});

Her er equals() og notEquals() assertions som får testen til å feile om de ikke stemmer. Dette ligner kjente testerammeverk som f.eks. JUnit. Tilgjengelige assertions i QUnit er:

ok(a)
Sjekker om a er true.

equal(a,b), notEqual(a,b)
Sammenligner a og b, og viser den spesifikke forskjellen om de ikke matcher. For eksempel:

strictEqual(a,b), notStrictEqual(a,b)
Samme som equals, men sjekker om også typen til a matcher b. (F.eks. strictEquals(2, “2″) feiler.)

deepEqual(a,b), notDeepEqual(a,b)
Sjekker rekursivt feltene inni a og b for å se om hver av dem matcher.

raises(f), raises(f,e)
Sjekker om et exception kastes når funksjonen f kjøres. Evt. kan typen exception spesifiseres i e.

Strukturer testene med moduler

Antall tester kan bli mange, men QUnit har mekanismer for å strukturere tester i grupper og la dem dele felles kode for å sette opp og rydde opp etter testene. Sett inn module() for å separere tester som hører sammen:

module('Touch-komponenten');

test(...);
test(...);

module('Søketjenesten');

test(...);
test(...);

Disse modulene kan også ta imot setup- og teardown-funksjoner som kjøres før og etter hver test:

module("Ajaxtestene", {
 setup: function() {
    // kjøres før test
 },
 teardown: function() {
    // kjøres etter test
 }
});

Test asynkron JavaScript

Mye av moroa med JavaScript er asynkrone metoder. Det vil si at etter at man gjør kall på en asynkron metode fortsetter koden etter kallet å kjøre, mens den asynkrone metoden også kjøres samtidig. Typisk brukes slike asynkrone metoder i ajax-kall og animasjoner, og de får som regel en callback-metode som kjøres når de er ferdig. For eksempel er jQuerys ajax-metode asynkron:

function asynkronMetode(callback) {
    $.ajax({
       url: 'server.php',
       success: callback
    });
}

Hvordan kan man teste asynkrone metoder? Dette er vanskeligere enn man kanskje tror. Om man kjører assertions etter et asynkront kall kan det hende at den asynkrone koden ikke er ferdig enda, og assertionene vil feile. Hva om man heller putter assertions inni callbacken slik at de kjøres når den asynkrone koden er ferdig? Nei, det går ikke fordi hele testen kan samtidig kjøre seg ferdig og dermed vellykket før assertionene får kommet på banen, og da merker man ikke om de feiler.

"Mye av moroa med JavaScript
er asynkrone metoder"

QUnit tilbyr en metode stop() som pauser testen slik at man kan vente på asynkrone kall. Testen startes igjen ved å kalle start(). JavaScript tilbyr allerede en metode setTimeout() som kan sørge for å vente så og så lenge før start() kjøres. Høres ut som vi har det vi trenger for å teste asynkron kode!

Men hva om et asynkront kall henger lenger enn tiden setTimeout venter? Da vil den asynkrone metodens assertions aldri kjøre, og ingen assertions betyr tilsynelatende vellykket test, uavhengig av om det funket eller ikke! Løsningen er å spesifisere antall assertions man forventer å gjøre med expect(). Slik vil testen feile om noe asynkron kode aldri returnerte.

Her er et eksempel som omfatter disse asynkrone mekanismene:

test('Min asynkrone test', function() {
    expect(3); // Vi forventer 3 assertions
    stop();  // Pause testen

    asynkronMetode(function() {
       equals(bla, bla);
    })  

    asynkronMetode(function() {
      equals(bla, bla);
      equals(bla, bla);
    })  

    setTimeout(function() {
       start();  // Fortsett testen etter 2 sekunder
    }, 2000);
});

Automatiser testene og presenter resultatene

Enhetstesting i QUnit ser vel og bra ut, men hvordan får man testene kjørt og testresultatene presentert på en fin måte? Heldigvis følger det med funksjoner og CSS i QUnit for dette. Følgende html-kode kjører testene i mine_tester.js og presenter resultatene slik som sett i skjermdumpen øverst i denne artikkelen:

<html>
<head>
    <script src="http://pre.jquery.com/jquery-latest.js"></script>
    <link rel="stylesheet" href="http://pre.jquery.com/qunit/git/qunit.css" type="text/css" />
    <script type="text/javascript" src="http://pre.jquery.com/qunit/git/qunit.js"></script>

    <script type="text/javascript" src="mine_tester.js"></script>
</head>
<body>
    <h1 id="qunit-header">Min overskrift her</h1>
    <h2 id="qunit-banner"></h2>
    <div id="qunit-testrunner-toolbar"></div>
    <h2 id="qunit-userAgent"></h2>
    <ol id="qunit-tests"></ol>
    <div id="qunit-fixture">test markup, will be hidden</div>
</body>
</html>

"QUnit vil skape strukturert html
med testresultatene"

Som man ser krever QUnit jQuery-biblioteket, og kommer til å fylle html-elementene i med riktig innhold ut fra hvilken id de har. Den medfølgende CSS-en kan såklart byttes ut med ens egne stilark. Og QUnit vil skape strukturert html med testresultatene som så kan analyseres av automatiske verktøy. Slik vil for eksempel oppsummeringen av resultene se ut:

<p id="qunit-testresult" class="result">
    Tests completed in 76 milliseconds.<br>
    <span class="passed">5</span> tests of
    <span class="total">8</span> passed,
    <span class="failed">3</span> failed.
</p>

QUnit API-et tilbyr også en rekke callbacks som kalles i de ulike stadiene av testingen. F.eks. QUnit.begin(), QUnit.testDone() og QUnit.moduleDone(), hvis funksjonalitet bør være selvforklarende. Alt dette fasiliterer automatiske tredjeparts testverktøy.

Konklusjon

QUnit er et enkelt rammeverk for enhetstesting i JavaScript. Det har støtte for assertions slik man kjenner fra andre rammeverk som JUnit, og man kan strukturere testene i modules. Mekanismer for testing av asynkron kode finnes også, samt støtte for tredjeparts automatiserte verktøy for å kjøre testene og presentere resultatene. API-en er liten, men gir deg de verktøyene man trenger for å innføre enhetstester i din eksisterende kode, og det er veldig lett å sette i gang. Les mer om QUnit på nettsidene deres, og sjekk ut denne artikkelen om asynkron testing i QUnit.

Hadn’t been for those re-occuring complaints from the users that “An unknown exception has occured” message with a big warning label pops up from time to time. A nice little feature you made to hide all of those unexpected exceptions that can, but should not, occur in your application. All in all a good thing as we would like to spare the user the experience of reading an unpleasant stacktrace from an external webservice error. But YOU, on the other hand. You would love to get your hands on the stacktrace from that Error that shouldn’t happen. So, how?

In Java-Land this is usually done by incorporating some form of logging that logs messages to file or almost whatever you would like. Most preferred being Log4J. Unfortunately I feel that a just-as-easy solution for Flex/Actionscript has yet to present itself. Until now. As a left-over artifact from the development of Spring Integration, the guys from Prana and Spring has made library called as3commons-logging. The library mimics Log4j in many ways and makes an excellent job doing so. Adding the as3commons-logging swc to your project then makes remote logging a peach. Here’s howto:

Some code

Step 1 of 3
Implement an ILoggerFactory like this. It’s responsibility will be to create Loggers for your classes:

public class RemoteLoggerFactory implements ILoggerFactory
{
        private var remote:RemoteObject;
 
        public function RemoteLoggerFactory(url:String, destination:String="remoteObjectLogger", fault:Function=null)
        {
                remote = createRemote(url, destination);
                remote.addEventListener(FaultEvent.FAULT, fault == null ? onRemoteFault:fault);
        }
 
        public function getLogger(name:String):ILogger
        {
                return new RemoteLogger(name, remote);
        }
 
        /** Creates a RemoteObject using SecureAMFChannel if https */
        private function createRemote(url:String, destination:String) : RemoteObject
        {
                var channelSet:ChannelSet = new ChannelSet();
                channelSet.addChannel(isHttps(url) ? new SecureAMFChannel(null, url) : new AMFChannel(null, url));
 
                var remoteService:RemoteObject = new RemoteObject(destination);
                remoteService.channelSet = channelSet;
 
                return remoteService;
        }
 
        private function isHttps(url:String) : Boolean
        {
                return url.indexOf("https") != -1;
        }
 
        /** Default FaultHandler. Just traces the message. */
        private function onRemoteFault(evt:FaultEvent) : void
        {
                trace("Could not log to server: "+evt.fault.message);
        }
}

Step 2 of 3
And then create the actual Logger which sends log messages to the backend, be that java, php, rails, .NET or name it.

public class RemoteLogger extends DefaultLogger
{
	protected var _level:uint;
	protected var remote:Object;
 
	public function RemoteLogger(name:String, remote:Object)
	{
        super(name);
        this.remote = remote;
	}
 
	override protected function log(level:uint, message:String, params:Array):void {
		if (level >= this._level) {
                        // add datetime
			var msg:String = "[" + new Date().toString() + "]";
			// add the name given to this logger. Usually the Class name
			msg += "[" + name + "]";
			// add message
			msg += " - " + MessageUtil.toString(message, params);
 
			var logLevel:String = LogLevel.toString(level);
			remote.log(logLevel, msg);
		}
	}
}

Step 3 of 3
Next instantiate your factory. Preferably as early as possible, so snapping in something like this at your Main mx:Application will do the trick.

private static var loggerSetup:* = LoggerFactory.loggerFactory = new RemoteLoggerFactory(ROOT_PATH+"messagebroker/amf");

And voila! It is now useable in any of your classes thiswise:

...
private static const logger:ILogger = LoggerFactory.getClassLogger(Jesus);
 
public function Jesus(){
      logger.info("Attention: We constructed Jesus.");
}

A dash of backend

The last but not least is to have a backend that can receive the messages and log them in a human readable way for later error debugging.
Why not splash out a java class with log4j? Well, this will do your trick:
Step 3.5

public class RemoteObjectLogger
{
        private static final String PRE_FLEX = "[FLEX]";
        protected final Log logger = LogFactory.getLog(getClass());
 
        public void log(String level, String message)
        {
                if ("INFO".equals(level))
                        logger.info(PRE_FLEX + message);
                else if ("DEBUG".equals(level))
                        logger.debug(PRE_FLEX + message);
                else if ("WARN".equals(level))
                        logger.warn(PRE_FLEX + message);
                else if ("ERROR".equals(level))
                        logger.error(PRE_FLEX + message);
                else if ("FATAL".equals(level))
                        logger.fatal(PRE_FLEX + message);
                else
                        logger.info(PRE_FLEX + "[" + level + "] - " + message);
        }
}

Try it

Would you like to see it in action? From top to bottom? Well I coded a small example for you to play with using Java as a backend. Svn the code from google-code. Only prerequisite is Maven installed. From there run compileAndRun and you are up and running!

<div id="content">
<div class="left column">
<h2>Velkommen til open.bekk.no</h2>
innhold</div>
<div class="right column">
    <a href="url">En link</a></div>
</div>

#content
  .left.column
    %h2 Velkommen til open.bekk.no
    %p innhold
  .right.column
    %a{:href => "url"} En link

Haml kommer med sin egen versjon av CSS, kalt Sass (Syntactically Awesome StyleSheets). Sass er en oversiktlig og god måte å skrive nøstede regler. I Sass kan man definere variabler, noe som gjør det enklere og raskere å endre verdier.

#header {
  background: #FFFFFF;
}
#header .error {
  color: #FF0000;
}
#header a {
  text-decoration: none
}
#header a:hover {
  text-decoration: underline
}

!error_color = #FF0000
 
#header
  :background #FFFFFF
 
  .error
    :color= !error_color
 
  a
    :text-decoration none
    :hover
      :text-decoration underline

Kombinasjonen Haml og Sass er utmerket for å lage raske prototyper. Selv om dette er laget for ruby, er det ikke noe i veien for å bruke det til ren html/css. Den største fordelen for rask prototyping er Sass. Det er mye raskere og mer oversiktlig å gjøre endringer i sass enn det er i css. Muligheten for variabler føles naturlig for en programmerer, og gjør også koden mer lesbar (!error_color sier leseren myer mer enn #FF0000).

Weblesere forstår ikke haml/sass. Du trenger derfor en server som kan oversette dette. En rask og enkel løsning er å bruke Serve. Serve fyrer opp en instans av Webrick fra katalogen du står i. Ønsker du muligheten til å bruke partials for å redusere duplisering i haml-filene, kan jeg anbefale å bruke Sinatra i stedet for Serve.

Så enkelt er det å komme i gang:

• ruby
• haml (“gem install haml” fra commandprompt)
• serve (“gem install serve” fra commandprompt)
• starte opp serve (“serve” fra commandprompt i ønsket katalog)

JavaScript Object Notation – Det er et enkelt data-format med lite overhead, det er en genial måte å bruke et allerede eksisterende språk på.

På ett av de mange track’ene på Bekks fagdag i Mars 2009, jobbet vi med JavaScript og rammeverk og teknologier knyttet til det. Ett av fokusområdene var JSON. Under følger en kort intro til JSON, samt noen eksempler på tjenester som tilbyr åpne JSON-API’er og kode som viser hvordan man kan importere og bruke dataen.

Hva er JSON

JSON er en måte å representere data på vha. enkel (og standard) JavaScript. Det betyr at man ikke trenger noen plugin eller noe rammeverk hverken på server- eller klient-side for å bruke det.

Et lite JSON-objekt:

var myObject = ({
	"field":"value hmhmhm",
	"childobj":{
		"childfield":"childvalue"
	}
});

For å “vise”  verdien til felter/objektet “field”:

 alert( myObject.field.value );

Eller child-objektet “childobj” sitt “childfield”:

 alert( myObject.field.childobj.childvalue );

Importering av JSON-data

Man kan som kjent bruke AJAX til å hente data dynamisk inn på en side uten å relaste hele siden. En sikkerhetsbegrensning i måten nettlesere behandler AJAX-requester på hindrer henting av data fra en webside som ligger på en annen server enn der hoved-siden ligger. For eksempel går det greit at siden som ligger på http://www.bekk.no/ henter søkeresultater vha AJAX fra http://www.bekk.no/search/ . Men det er ikke mulig for http://www.bekk.no/ å hente noe fra feks http://search.bekk.no/ vha. standard AJAX (uten noen form for proxy).

Derimot er det greiere å få hentet inn JSON fra andre kilder enn sin egen server.  Må kan injecte en ny javascript-kilde-referanse i HTML-dom’en. Følgende kodesnutt viser i klartekst hvordan det går til:

 document.getElementsByTagName("head")[0].appendChild( <em>jsonScriptBlock</em> );

Innholdet i variabelen jsonScriptBlock er HTML og kan være noe ala dette:
<script src=”http://api.flickr.com/services/feeds/news.gne?format=json” type=”text/javascript”/>

Når den linjen settes inn i HTMLdom’en vil browseren laste ned og eksekvere JavaScriptet som mottas. Dette skjer på samme måte som man inkluderer vanlige JavaScript-filer i HTML’en. Den eneste lille forskjellen er at det skjer dynamisk, og typisk etter at siden er lastet og gjerne som en del av interaksjon med brukeren.

Vi har data. Now what?

Første linje i JSON-responsen fra Flickr ser ca slik ut:

 jsonFlickrFeed({...

Ettersom typen på og innholdet i fila som nettopp har blitt lastet ned er JavaScript, vil nettleseren eksekvere innholdet. I dette tilfellet betyr det at den vil kjøre funksjonen jsonFlickrFeed( arg ); Argumentet er JSON-objektet, som representerer dataen vi har forespurt fra Flickr. Men funksjonen  jsonFlickrFeed finnes ikke ennå, og den står vi fritt til å lage (les: vi må, ellers skjer det fint lite):

 function jsonFlickrFeed( json ){
  // Gjør ting med JSON-objektet
}

Hva vi vil gjøre med JSON-objektet avhenger selvsagt litt av hva tilbyderen av dataen har inkludert, og av hvordan datastrukturen ser ut. For Flickr inneholder JSON-strukturen først noen header-felter med litt info om dataen, og deretter kommer en array med items man kan løpe gjennom for å hente ut forskjellige felter fra.

Eksempel

Dette eksempelet forutsettet at vi har javascript-rammeverket Prototype inkludert på HTML-siden, og at man har ett DIV-element på HTML-siden med id=flickrContent.

/**
  En generell funksjon for å sette inn en SCRIPT-tag med gitt src-URL i HEAD
  i HTML-dokumentet.
*/
function injectScript( url ){
	var scriptBlock = new Element( "script", {'src': url,'type':'text/javascript' });
	document.getElementsByTagName("HEAD")[0].appendChild( scriptBlock );
}
 
/**
  Kaller bare injectScript, med vår flickr-URL.
*/
function injectFlickrJson(){
	injectScript( 'http://api.flickr.com/services/feeds/photos_public.gne?format=json&tags=bekk' );
}
 
/**
  Dette er funksjonen som JSON-responsen fra Flickr kaller når den blir lastet av nettleseren.
*/
function jsonFlickrFeed( resp ){
	// For hver item som ligger i arrayen items i JSON-objektet...
	resp.items.each( function( item ){
        	// .. gjør følgende: Put item sin description inn i
		// ett nytt DIV-elemenent og legg det inn i
		// elementet 'flickrContent' som er en DIV i HTML-dokumentet vårt.
		$('flickrContent').appendChild( new Element( "div" ).update( item.description ) );
	});
}

Og det var det hele. Resultatet skal være at en rekke bilder og tekst dukker opp i flickrContent-DIV’en. Ser man nøye på URL’en i funksjonen injectFlickrJson ser man parametert tags=bekk. En enkel utvidelse av denne funksjonen er å la den ta i mot et argument som kan sendes med til flickr. Dermed har man implementert et “søk” blandt alle flickrs millioner av bilder, med ca 9 linjer kode.

Hva kan man bruke denne teknikken til

Flere og flere tjenester som sitter på større mengder data, enten det er nyheter, bilder, værdata, trafikkdata, økonomi-ting, statistikk osv, åpner opp for bruk av hele eller deler av dataen sin. Ved å gi ut slik data til mange kloke hoder kan det komme uventede resultater. Kanskje det finnes sammenhenger mellom tempraturene i Sør-Afrika og økonomien på Island. Kan det være mindre tafikk i Bærum enn i indre Oslo Øst når Storebrand holder pressekonferanse?

Ekstern data kan også brukes til å berike ditt eget innhold. Har du artikler som handler om teknologi, og hvor teknologi-ord går igjen i teksten, kan det kanskje være en ide å knytte disse ordene til nyheter og andre artikler som tagget med den aktuelle teknologien. Disse nyhetene og artiklene kan da være hentet med JSON fra andre kilder og matchet med din artikkel-tekst. Stedsnavn kan knyttes til både værdata og bilder. Selskaper kan knyttes til børs-informasjon.

Kilder og andre ressurser

• http://www.json.org/
• http://www.prototypejs.org/learn/json
• http://flickr.com – http://flickr.com/services/feeds/
• http://twitter.com – http://apiwiki.twitter.com/REST+API+Documentation#TheEasiestWaytoPlayAroundwiththeTwitterAPI
• http://api.yr.no/weatherapi/documentation
• http://www.bbc.co.uk/programmes/developers

PS.

Merk at denne artikkelen ikke berører hverken kode-kvalitet eller sikkerhet. Det man får tilbake fra andre i form av JSON kan inneholde funksjonskall som kan være en sikkerhets risiko. Det man bør alltid utføre santitization på JSON-responsen.