Stepic Plugins Documentation Release 0 Stepic Team May 06, 2015
Contents 1 Introduction 3 1.1 Quiz Architecture............................................ 3 1.2 Backend Overview............................................ 4 1.3 Frontend Overview............................................ 4 1.4 Frontend/Backend Communication Overview.............................. 4 2 Plugin API 5 2.1 Quiz Design............................................... 5 2.2 Directory Structure............................................ 5 2.3 Server side................................................ 5 2.4 Client Side................................................ 6 2.5 Launching The Quiz........................................... 7 2.6 Advanced Plugins............................................ 7 3 For Impatient 9 4 Naming Conventions 11 5 Plugins documentation 13 5.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 the result back to the user. Common types of quizzes are choice quizzes, which ask user to select one or more options, Code quizzes, which involve 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 what does 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 javascript and executing in browser. Frontend and backend communicate with each other via fixed protocol and custom messages, representing subset of JSON. Files for quiz named foo are stored in the directory quizzes/foo. The directory contents is like this: quizzes/foo init.py tests.py show.hbs show.js edit.hbs edit.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 and presenting 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 with plugin 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 featured implementation 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 describes three 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 types are 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 transform raw dictionaries into parsed objects. 2.4 Client Side Client side is written in javascript, Handlebars and css. It defines two functions editsimplechoicequiz and 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 for showsimplechoicequiz. 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 in quizzes/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.py test.py edit.js edit.hbs show.js show.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 your Nitrous.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.py QUIZ_NAME or play around with one of standard quizzes, for example simple-choice quiz: python dev-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