Building a Quiz Manager for jQuery Mobile

a few weeks ago a reader asked if i had ever designed a quiz for jquery mobile . while i had not, i spent some time thinking about how a quiz could be designed as well as how a generic library could help automate it. i've built a demo i'd like to share with folks. it is definitely "first draft" (but hey, it lints !) so feel free to tear it apart and suggest improvements.

i began by thinking how quiz data could be represented. i figured either xml or json. json has the benefit of being really easy to work with in javascript. xml has the benefit of being really easy to write, even for non-devs. at the end of the day though i settled on json. my library could be updated to handle both though. here is an example quiz i used for my demo.

{
	"introduction":"this quiz tests you about foo and goo", 
	"questions":[
		{"question":"why is the sky blue?", 
		 "answers":["unicorns","fairies","boring science","kittens"],
		 "correct":2},
		{"question":"why are kittens so cute?", 
		 "answers":["magic","fur","meow","more kittens!"],
		 "correct":3}
	]
}

the scheme consists of an optional introduction and an array of questions. each question has a question value (the actual text), an array of answers, and a correct index. this is 0-based but i'm thinking it may make sense to be 1-based. my design only allows for multiple choice questions with one answer, but you could also do true/false of course.

on the jquery mobile side, the library is used by running an execute method. the execute method takes the url of a quiz, a dom element to render the quiz within, and a success callback. my jquery mobile application uses this app.js file to handle that aspect:

/* global $,document,console,quizmaster */
$(document).ready(function() {
	
	$(document).on("pageshow", "#quizpage", function() {
		console.log("page show");
		//initialize the quiz
		quizmaster.execute("q1.json", ".quizdisplay", function(result) {
			console.log("sucess cb");
			console.dir(result);	
		});
	});
}); 

i whipped up a quick jquery mobile application with two pages. the first simply links over to the quiz page.

once you load the quiz page, the code you see above runs the library. here is how the quiz displays the introduction:

and this is the first question:

ok, now let's look at the library.

/* global $,window */
var quizmaster = (function () {
	var name;
	var data;
	var loaded = false;
	var displaydom;
	var successcbalias;

	function nexthandler(e) {
		e.preventdefault();

		var status = getuserstatus();

		//if we aren't on the intro, then we need to ensure you picked something
		if(status.question >= 0) {
			var checked = $("input[type=radio]:checked", displaydom);
			if(checked.length === 0) {
				//for now, an ugly alert
				window.alert("please answer the question!");
				return;
			} else {
				status.answers[status.question] = checked.val();	
			}
		} 
		status.question++;
		storeuserstatus(status);
		displayquiz(successcbalias);
	}

	function displayquiz(successcb) {

		//we copy this out so our event can use it later. this feels wrong
		successcbalias = successcb;
		var current = getquiz();
		var html;

		if(current.state === "introduction") {
			html = "<h2>introduction</h2><p>" + current.introduction + "</p>" + nextbutton();
			displaydom.html(html).trigger('create');
		} else if(current.state === "inprogress") {
			
			html = "<h2>" + current.question.question + "</h2><form><div data-role='fieldcontain'><fieldset data-role='controlgroup'>";
			for(var i=0; i<current.question.answers.length; i++) {
				html += "<input type='radio' name='quizmasteranswer' id='quizmasteranswer_"+i+"' value='"+i+"'/><label for='quizmasteranswer_"+i+"'>" + current.question.answers[i] + "</label>";
			}
			html += "</fieldset></div></form>" + nextbutton();
			displaydom.html(html).trigger('create');
		} else if(current.state === "complete") {
			html = "<h2>complete!</h2><p>the quiz is now complete. you got "+current.correct+" correct out of "+data.questions.length+".</p>";
			displaydom.html(html).trigger('create');
			removeuserstatus();
			successcb(current);
		}
		
		
		//remove previous if there...
		//note - used click since folks will be demoing in the browser, use touchend instead
		displaydom.off("click", ".quizmasternext", nexthandler);
		//then restore it
		displaydom.on("click", ".quizmasternext", nexthandler);
		
	}
	
	function getkey() {
		return "quizmaster_"+name;	
	}
	
	function getquestion(x) {
		return data.questions[x];	
	}
	
	function getquiz() {
		//were we taking the quiz already?
		var status = getuserstatus();
		if(!status) {
			status = {question:-1,answers:[]};
			storeuserstatus(status);
		}
		//if a quiz doesn't have an intro, just go right to the question
		if(status.question === -1 && !data.introduction) {
			status.question = 0;
			storeuserstatus(status);
		}

		var result = {
			currentquestionnumber:status.question
		};
		
		if(status.question == -1) {
			result.state = "introduction";
			result.introduction = data.introduction;	
		} else if(status.question < data.questions.length) {
			result.state = "inprogress";
			result.question = getquestion(status.question);	
		} else {
			result.state = "complete";
			result.correct = 0;
			for(var i=0; i < data.questions.length; i++) {
				if(data.questions[i].correct == status.answers[i]) {
					result.correct++;	
				}
			}
		}
		return result;
	}
	
	function getuserstatus() {
		var existing = window.sessionstorage.getitem(getkey());
		if(existing) {
			return json.parse(existing);
		} else {
			return null;
		}
	}
	
	function nextbutton() {
		return "<a href='' class='quizmasternext' data-role='button'>next</a>";	
	}
	
	function removeuserstatus(s) {
		window.sessionstorage.removeitem(getkey());	
	}
	
	function storeuserstatus(s) {
		window.sessionstorage.setitem(getkey(), json.stringify(s));
	}
	
	return {
		execute: function( url, dom, cb ) {
			//we cache the ajax load so we can do it only once 
			if(!loaded) {
				
				$.get(url, function(res, code) {
					//possibly do validation here to ensure basic stuff is present
					name = url;
					data = res;
					displaydom = $(dom);
					//console.dir(res);
					loaded = true;
					displayquiz(cb);
				});
				
			} else {
				displayquiz(cb);
			}
		}
	};
}());

there's a lot here and i'll try to explain it bit by bit. the end of the code is the public api which - for now - has one method, execute. note how we detect if the quiz is already loaded. this way we can cache the json and not load it after we've fetched it once in the request.

displayquiz is the main handler for rendering the quiz. it begins (ignore the copy statement) by calling getquiz. getquiz handles interfacing with the quiz data as well as the user data. i'm using sessionstorage to remember where you are in the quiz. this is useful if you leave the quiz before finishing it. getquiz also does some intelligent handling of state. so for example, if there isn't an introduction it ensures you go right into the first question. it also recognizes when you're done and checks your work.

back in displayquiz we use the result of getquiz to render one of three states - the introduction, the quiz itself, or the completion. by the way, the success callback is used to allow your calling code to record the results to your server via ajax, or do anything really.

all in all this was fun to write, but as i said, feels very much like a first draft. want to try it yourself? hit the demo link below.