# node-quizzer

## Demo

[An example running node-quizzer](https://github.com/raduGaspar/node-quizzer-example)

## Documentation

- To add questions open the quizzes.json file in `node-quizzer\data`
- There are 4 question types marked from 0 to 4
  - `{"type": 0}` indicates single answer questions, this will generate radio buttons in the UI
  - `{"type": 1}` multiple answer questions, checkboxes are generated in the UI
  - `{"type": 2}` free text, this will be validated by RegExp; a text input is generated in the UI
  - `{"type": 3}` free text, requires human validation; a textarea is generated in the UI
- Fields a question might have:

  ```js
  {
    "qid": 0,       // number: indicates the question ID, must be unique per category
    "graded": true, // boolean: marks if the question is graded or not upon evaluation
    "type": 1,      // number: one of the 4 types described above
    "title": null,  // string: the title of the question
    "desc": null,   // string: a small description if needed
    "code": null,   // string: a piece of code if needed
    "lang": null,   // string: the piece of code type (js, css, perl, etc.)
    "opts": [],     // array: holds all possible responses for this question
    "correct": [],  // array: holds all indexes of the correct answers for this question
    "rule": "",     // string: a RegExp to use as validation for type 2 questions
    "ruleOpts": ""  // string: RegExp options for better validation; default: "gi"
  }
  ```

- Don't use all of the fields for every question type:
  - `{"type": 0}` doesn't need the `rule, ruleOpts` fields
  - `{"type": 1}` doesn't need the `rule, ruleOpts` fields
  - `{"type": 2}` doesn't need the `correct, opts` fields
  - `{"type": 3}` doesn't need the `correct, opts, rule, ruleOpts` fields
- All the test evaluations will be saved on the server in a `results` folder
  - all tests will have the following name format:

    `{review|final}-{token_id}-{full-username}`

  - quiz names that start with `review` contain at least one `{"type": 3}` question

## Breakdown of methods in `node-quizzer`

```js
// load the node-quizzer module
var quizzer = require('node-quizzer');

/*
 * generate - method used for generating quizzes
 * tokenize - method used for generating a quiz token
 * usage: quizzer.generate(opts);
 * usage: quizzer.tokenize(opts);
 *
 * @param {object} opts  And object containing user and quiz details: uname,
 *                       email, name, count, time, perc (defined below)
 *   @param {string} uname The full username of the quiz taker
 *   @param {string} email The email of the quiz taker
 *   @param {string} name  The name of the quiz, defined as a key in quizzes.json
 *   @param {number} count The number of questions in the quiz;    default: 20
 *   @param {number} time  The number of minutes before quiz ends; default: 30
 *   @param {number} perc  The minimum required pass percentage;   default: 50
 *
 * @return {string} HTML markup containing questions and countdown timer
 *                  URL to quiz (in case tokinize was used instead)
 */
var set = quizzer.generate({
  uname: 'John Doe',
  email: 'john.doe@missing.com',
  name: 'nodejs',
  count: 10
});
console.log(set);

/*
 * fromToken - method user for generating a quiz templated based on a token
 * usage: quizzer.fromToken(token_uid);
 *
 * @param {string} token_uid The token that was generate with quizzer.tokenize
 *
 * @return {string} HTML markup containing questions and countdown timer
 */
var quiz = quizzer.fromToken("1a2b3c4d5e"); // warning: use an actual token
console.log(quiz);

/*
 * getCategories - gets a list of categories (only those that have questions)
 * usage: quizzer.getCategories()
 *
 * @return {array} Array of categories as strings
 */
var categories = quizzer.getCategories();
console.log(categories);

/*
 * evaluate - evaluates the quiz based on the provided form data
 * usage: quizzer.evaluate(form)
 *
 * @return {object} Contains details about the result of the quiz
 */
```

## Future tasks

- [ ] create a manager for better categories, quiz, question and answer handling
- [ ] support templating/custom CSS