This document provides a quick guide to the BetterQuiz codebase.
Installing a BetterQuiz server is relatively simple.
Assuming the betterquiz repo is checked out to /opt/betterquiz, you can install a basic Apache server with required libraries using the src/tools/install.sh script. You can also do this all yourself- the script is very self-evident.
Create an empty database and configure a user with password and all privileges.
Copy public/lib/settings.template.php to public/lib/settings.local.php and edit this file to contain your database details and your Panacea SMS API account details.
Migrate the database. This is done by executing every script of the form src/sql/betterquizN.sql against the database in ascending numerical order 0, 1, 2 ...
You're ready to go!
From the Admin system, upload your quiz. Then find the ID for the quiz: you can use Quiz->Find and locate the quiz you've uploaded.
Direct the user to:
http://your.betterquiz.com/?qz={ID}&r={REDIRECT}
Set the qz parameter to the ID of your quiz, and the r parameter to the URL to which you want the user returned when the quiz is completed.
How to get reports:
There are two important root directories in the codebase: public and src. The public directory contains the base directory to be served as the BetterQuiz website. The src directory contains code that is compiled or transformed in some fashion, and typically inserted into the public directory in compiled form.
The code for the BetterQuiz admin site. The public/admin/lib contains some general library files used on the admin site.
Generated webcomponents, from the code in src/bq-components.
CSS code generated from SASS in src/scss
Javascript code generated from Coffeescript in src/coffee.
General libraries for inclusion on betterquiz pages. The settings.local.php in this directory in particular contains site-specific settings for the database and for PanaceaSMS API usage.
This directory contains most of the BetterQuiz specific code. It can be divided into three broad groups:
func.bqf_unescape_string.php that provide some utility to the tokenization and parsing processes.class.Errors.php, class.Flash.php, class.ReturnSite.php and class.SessionStore.phpThe source code for the web components that are used on the admin site. These are all experimental, and will probably give trouble as the webcomponents standard evolves (!) - but fine for now.
Coffeescript sources. These are compiled through the gulpfile contained in /, and become compiled javascript in src/js.
SASS stylesheets that are compiled by running compass watch in the root directory. They become compiled CSS in public/css
SQL migrations scripts. These are each of the form betterquizN.sql and betterquiz-N.sql . Execute the positive forms (betterquizN.sql) in numerical sequence from 0 to migrate to a database version, and the negative forms (betterquiz-N.sql) in reverse numerical sequence to rollback a migration.
The src/tools directory contains a few basic tools for betterquiz operation.
A very basic bash script to install betterquiz (which is assumed to be in /opt/betterquiz) on a fresh Ubuntu server. It does not migrate the database, nor setup database connection options. See Installation above for detailed installation instructions.
A Perl script for converting BetterCare Quizzes in MarkDown format to BQF format. This is a command line tool, and is designed to be used with Unix pipes. It reads the MarkDown from stdin and writes it to stdout.
The Tokenization and Parsing of the BQF is managed using ideas expressed in this talk by Rob Pike: https://www.youtube.com/watch?v=HxaD_trXwRE
The mile high view is that a StringStream derived class provides methods for reading through the input string at a character level.
One of the State derived classes controls the reading of the StringStream, breaking the stream into Tokens and emitting Tokens as appropriate. A state-machine controls the state of the tokenization. The Parser related classes receive the Tokens, and populate a BQQuiz based on the received Tokens. Again, a state-machine controls the parsing state.
The following build tools are used at various points in the betterquiz build process. Note, though, that all compiled assets are stored in the repo, so none of these build tools are required on production boxes.