Stepic Plugins DocumentationRelease 0

Stepic Team

May 06, 2015

Contents

1 Introduction 31.1 Quiz Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Backend Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 Frontend Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.4 Frontend/Backend Communication Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Plugin API 52.1 Quiz Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3 Server side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.4 Client Side . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.5 Launching The Quiz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.6 Advanced Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 For Impatient 9

4 Naming Conventions 11

5 Plugins documentation 135.1 Simple Choice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

6 Nitrous.IO 15

7 Indices and tables 17

i

ii

Stepic Plugins Documentation, Release 0

Contents:

Contents 1

Stepic Plugins Documentation, Release 0

2 Contents

CHAPTER 1

Introduction

Stepic is an educational engine, focused on interactive problems (quizzes).

Please note, that this documentation is a bit obsolete – Stepic Plugins become standalone service in Feb 2015.We’ll update this docs in Feb-March 2015.

Quiz is an interactive component, which can present task to the user, gather user’s solution, evaluate it and present theresult back to the user.

Common types of quizzes are choice quizzes, which ask user to select one or more options, Code quizzes, whichinvolve writing some code or math quizzes, which check formulas.

It is possible to extend Stepic engine with custom quizzes via plugins. Here you can find a general overview of whatdoes it takes to create a Stepic plugin.

1.1 Quiz Architecture

Quiz is an editable and interactive component, so it must support two operations

• Quiz creation and editing (by the lesson author)

• Presentation of the dataset and gathering of the response(of the lesson student)

Quiz consists of two parts, a backend, written in python and executing on the server, and a frontend, written in javascriptand executing in browser.

Frontend and backend communicate with each other via fixed protocol and custom messages, representing subset ofJSON.

Files for quiz named foo are stored in the directory quizzes/foo.

The directory contents is like this:

quizzes/foo__init__.pytests.pyshow.hbsshow.jsedit.hbsedit.js

3

Stepic Plugins Documentation, Release 0

1.2 Backend Overview

To implement a quiz backend, define a base.BaseQuiz subclass in quizzes/foo/__init__.py.

The responsibilities of a backend:

• specification of the message format to communicate with frontend

• creation of a quiz instance from quiz source

• creation of datasets

• evaluation of submissions

1.3 Frontend Overview

To implement a quiz frontend, you need to write handlebars templates and javascript functions for editing the quiz andpresenting it to user.

The responsibilities of a frontend:

• display edit interface, which allow author to edit quiz source(edit.js, edit.hbs).

• display view interface, which allow student to view dataset and create a submission(show.js, show.hbs).

1.4 Frontend/Backend Communication Overview

Frontend and backend communicate via messages JSON. There ara three types of this messages:

• source represents all the quiz data. Sources are generated via edit interface.

• dataset is send to a student, when he attempts a quiz. Datasets are generated by backend.

• reply is send from students browser to backend. Replies are created by view interface.

A typical interaction looks like this:

• Edit part:

– an author opens edit interface and creates a new slide with a quiz.

– the quiz source is send to the backend, where it is validated and, if it is valid, it is persisted.

– a quiz instance is created from the source and several datasets are generated.

• View part:

– a student opens a slide with a quiz and pushes start quiz button.

– dataset generated during previous part is send to the student’s browser.

– view interface presents the dataset to the student.

– the student interacts with the quiz and creates a submission.

– the student pushes the submit button and the submission is send to the server.

– a quiz instance is created from source afresh.

– the instance evaluates the submission

– the student sees the result

4 Chapter 1. Introduction

CHAPTER 2

Plugin API

This document demonstrates plugin API with the example of simple-choice quiz. It should be read alongside withplugin source at quizzes/simple_choice.

2.1 Quiz Design

Author specifies a list of options, one of which is correct and all others are wrong.

Student is presented with a shuffled list of options. He should pick the correct one.

This design can be extended in a numerous ways, but for the sake of simplicity we won’t do this. Full featuredimplementation of a choice quiz can be found at quizzes/choice.

2.2 Directory Structure

Directory quizzes/simple_choice consists of the following files:

• __init__.py – server part of the quiz is defined here.

• tests.py – server part tests.

• edit.js, edit.hbs – this pair of files describes edit interface for teacher.

• show.js, show.hbs – this pair of files describes interface for student.

• style.css – css styles for frontend.

2.3 Server side

Server side is written in Python3 and consists of one file – __init__.py. In this file SimpleChoiceQuiz class is defined.It inherits from BaseQuiz and implements several abstract members.

name is quiz type in dasherized-case.

Schemas is a specification of a communication format between python backend and javascript frontend. It describesthree types of objects.

Source is the data needed to create quiz instance. It is created and rendered in edit.js.

Dataset is presented to the student for solving. It is created in __init__.py and rendered in show.js.

5

Stepic Plugins Documentation, Release 0

Reply is the student’s solution to the dataset. It is created and rendered in show.js

This object’s types are expressed with the help of JSON specification mini language. In this language, objects typesare specified as python dictionaries, JSON arrays as lists and primitive types like int, str, etc.

For example, an object with field numbers which is an array of ints is specified as:

{'numbers': [int]

}

Source of simple_choice quiz can be specified as a list of text options with correctness marks:

{'options': [{'is_correct': bool, 'text': str}]

}

Dataset should be a list of strings:

{'options': [str]

}

Reply should be a list of booleans:

{'choices': [bool]

}

__init__(self, source) instantiates quiz from source.

generate(self) generates a (dataset, clue) pair. clue is used to check user’s response.

clean_reply(self, reply, dataset) validates and transforms user’s reply.

check(self, reply, clue) checks valid and transformed reply.

Tests for backend can be found in tests.py. Note the use of SimpleChoiceQuiz.{Source, Dataset, Reply} to transformraw dictionaries into parsed objects.

2.4 Client Side

Client side is written in javascript, Handlebars and css. It defines two functions editSimpleChoiceQuizand showSimpleChoiceQuiz. This functions create necessary UI and return an object with submit method.This method should return an object representing quiz source for editSimpleChoiceQuiz and reply forshowSimpleChoiceQuiz.

editSimpleChoiceQuiz function takes three arguments:

• target – jQuery object representing parent DOM element.

• template – a compiled handlebars template.

• source – null, if it is a new quiz, or existing quiz source.

showSimpleChoiceQuiz function takes five arguments:

• target, template – same as edit.

• dataset – dataset, conforming to SimpleChoiceQuiz.Schemas.dataset

• reply – an existing reply(SimpleChoiceQuiz.Schemas.reply) or a null.

6 Chapter 2. Plugin API

Stepic Plugins Documentation, Release 0

• disabled – a boolean flag. If it is on, UI should be rendered in disabled state.

2.5 Launching The Quiz

To check the quiz, start development server first:: $ python3 dev-server/server.py simple-choice

And then open 127.0.0.1:5000 in your browser.

2.6 Advanced Plugins

Plugin can specify async_init method. It is used for time consuming initialization and checking.

Fork of [CodeJail](https://github.com/bioinf/codejail) is used for untrusted code execution.

It’s possible to use CoffeeScript to create frontend.

Ember components can be used to create frontend.

Check existing quizzes for examples of this features.

2.5. Launching The Quiz 7

Stepic Plugins Documentation, Release 0

8 Chapter 2. Plugin API

CHAPTER 3

For Impatient

• click this image to create server in Nitrous.IO

• when server is ready enter IDE via your dashboard

• start server by running workspace/stepic-plugins/stepic_plugins/conf_nitrous.sh

• find out server’s public URL from your dashboard

• now you can play with Simple Choice Quiz from http://XXXXXX.nitrousbox.com:5000

• experiment with frontend in quizzes/simple_choice/{show,edit} and with backend inquizzes/simple_choice/__init__.py

• start creating your own quiz, just copy files from quizzes/template to quizzes/your_quiz

9

Stepic Plugins Documentation, Release 0

10 Chapter 3. For Impatient

CHAPTER 4

Naming Conventions

Files for quiz “foo bar”:

quizzes/foo_bar/

__init__.pytest.pyedit.jsedit.hbsshow.jsshow.hbs

in quizzes/foo_bar/__init__.py:

from stepic_plugins.base import BaseQuiz

class FooBarQuiz(BaseQuiz):name = 'foo-bar'...

in quizzes/foo_bar/edit.js:

function editFooBarQuiz(...) {

...}

in quizzes/foo_bar/show.js:

function showFooBarQuiz(...) {...

}

11

Stepic Plugins Documentation, Release 0

12 Chapter 4. Naming Conventions

CHAPTER 5

Plugins documentation

Contents:

5.1 Simple Choice

5.1.1 Summary

A simple plugin used as an example.

source

5.1.2 Details

Simple choice exercise asks student to select one correct choice from a range of options, specified by instructor.

13

Stepic Plugins Documentation, Release 0

14 Chapter 5. Plugins documentation

CHAPTER 6

Nitrous.IO

Nitrous.IO is a cloud application platform that helps you create and configure the infrastructure in just seconds.

You can spin up server side for Stepic plugins in Nitrous.IO for free. Just follow this link. A minute later, when yourNitrous.IO box is ready just run this commands:

• virtualenv hack-stepic -p python3.3

• source hack-stepic/bin/activate

• cd workspace/stepic-plugins/

• pip install -r requirements.txt

• cd stepic_plugins/

Now server is ready! You can implement your quiz and start server with python dev-server/server.pyQUIZ_NAME or play around with one of standard quizzes, for example “simple-choice” quiz: pythondev-server/server.py simple-choice.

To use this server from front end find out server’s public URL from your dashboard.

15

Stepic Plugins Documentation, Release 0

16 Chapter 6. Nitrous.IO

CHAPTER 7

Indices and tables

• genindex

• modindex

• search

17