websheets: Online version of coding handouts with blanks
========================================================
Created originally by David Pritchard (daveagp@gmail.com) in 2013.
Released under the GNU Affero General Public License (but see
other licenses for subdirectories/subrepositories).

MIRRORS

Right now there are two mirrors:
 http://www.cs.princeton.edu/~cos126/websheets/index.php (Java 7)
 http://cscircles.cemc.uwaterloo.ca/websheets/index.php (Java 8)

Note that you can link to a particular exercise with
.../index.php#NameAge
or a group of exercises with 
.../index.php?group=HelloWorld+NameAge+NextYear#NameAge

BASIC INSTALLATION

Install these on your server first:
 https://github.com/cemc/safeexec
 https://github.com/daveagp/java_jail 
This requires root access. See the instructions therein for details. It is best to
install these in locations that are not served to users by your web server.

Next, in some folder accessible to your web server, run

git clone --recursive https://github.com/daveagp/websheets

You should be able to see the frontend, and an exercise, at 
 http://your.website/url/to/websheets/index.php
although it will warn you of configuration problems.

Next, copy ws-config.example.json to ws-config.json. 
Reloading that page, it won't warn you, but submitting will
cause errors.

Set up the first 2 otions in ws-config.json. Now you can submit code!

ADDITIONAL SETUP

There are some optional things you can do once the basics are working:

0. To download updates, you need two commands to get the subrepos:
   git pull; git submodule update

1. Setup the db. This is necessary if you want to log past submissions or
   use logins (see below). Set the appropriate options in ws-config.json
   and create a table like "DB TECHNICAL DETAILS" below.

2. Setup or change login mechanisms if you want the websheets site to
   remember each user's latest submission and what they've solved. 
   Pre-requisite: you've created and setup a DB (step 1.)
   If you want to use facebook and/or google, get API keys for them 
   and change the listed options in ws-config.json. Delete the options
   you don't want to use. 

   For authentication we use "hybridauth" which we use as a unified wrapper 
   for user email authentication (they are remembered by email address). 
   With some work you can set up a custom authentication for your school
   if they have a PHP authentication system; follow the Princeton example
   in include.php. You should also be able to use other hybridauth providers
   with a little work.

   You need a google "Client ID for web applications" and "Client secret"
   or a facebook "App ID" and "App Secret" See the hybridauth documentation
   for more details.

3. Create more problems! The bad news is that the documentation for this
   does not yet exist and some spacing issues are not yet worked out. But for
   the non-faint of heart, follow the examples in the "exercises" directory. 
   They are key-value string pairs, written as Python modules because it 
   makes less escaping necessary and because we use Python as a system
   to glue everything together.

THANKS

Thanks to the COS 126 staff at Princeton for offering feedback when using
this tool from Fall 2013 to Spring 2014: 
Donna Gabai, Maia Ginsburg, Bob Sedgewick and Doug Clark.

DB TECHNICAL DETAILS

Here's the table format used currently for saving past submissions:

CREATE TABLE IF NOT EXISTS `ws_history` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `user` varchar(100) COLLATE utf8_unicode_ci NOT NULL,
  `problem` varchar(100) COLLATE utf8_unicode_ci NOT NULL,
  `submission` varchar(5000) COLLATE utf8_unicode_ci NOT NULL,
  `result` mediumtext COLLATE utf8_unicode_ci NOT NULL,
  `time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `passed` tinyint(1) NOT NULL DEFAULT '0',
  `meta` text COLLATE utf8_unicode_ci NOT NULL,
  PRIMARY KEY (`id`),
  KEY `user` (`user`,`problem`,`passed`)
) ENGINE=InnoDB  DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci AUTO_INCREMENT=1;

WARNNING: If you use a database, you'll be putting a DB password in ws-config.json.
Please check that
 http://your.website/url/to/websheets/ws-config.json
is inaccessible; .htaccess tries to do this, but you should confirm it works.

FILES LISTING

ws-config.example.json - copy this to ws-config.json and fill it in
websheet.{css,js} - create/render the partially read-only codemirror area
index.{php,js} - browser for multiple websheets
load.{php,py} - (for ajax) load a problem to show
submit.{php,py} - (for ajax) submit an attempt
include.php - authentication used by all php files
Websheet.py - Python model of a Websheet, command-line tools to use with them
config.py - Python to interact with safeexec and database
GenericTester.java - grader template runs & compares student/reference code