// v1.3 - Dec 7, 2015
// for change history see release notes below
// ©2015 SmugWimp Software

Welcome to Smugs Exam Builder for iOS and Android.

The easy way to create quality exams from quiz sources.

Can use questions for either the standard BT Quiz, or Nad's excellent Advanced Quiz.

What this plugin does in one sentence:

"Prepares and executes a custom Quiz using different question sources."

What this plugin does not do in one sentence:

"This is not a quiz plugin nor does it replace the requirement to have a quiz plugin for use."

+++++++++++++++++++++++++++++++++++++++++++++++++++++
Here is the scenario:

You have a subject, with 10 different topics.
You have a quiz for each topic, with 10 different questions.
You want to create an exam with questions from each topic.

Exam builder will allow you to create exams 'on the fly' using questions
from each 'question pool' (quiz childItems). You can select from 1-N questions to be selected randomly.
If in a multi-user environment, each ‘exam’ would be different for each user, alleviating coercion.
+++++++++++++++++++++++++++++++++++++++++++++++++++++

In 'real life' I designed this for a possible 'FCC License' app I'm thinking about. The
FCC exam depends on the license you desire, and the 'question pool' is from 700 questions
to several thousand questions resulting in a 35, 70, and 100 question exam depending on
the license goal. The tests are computer generated from the pools and completely random.

The Regular quiz is nice, and Nad's advanced quiz is the bomb. But I
needed a way to nab random questions from each 'topic pool' of questions, just like the
actual exam, and then use that 'exam pool' in a quiz.

All we're essentially doing here is grabbing random questions from your quiz childItem file
and creating one big 'loadScreenObject' to define a new quiz config from the dynamically generated
exam pool.

I've done this with a few thousand questions, and so far haven't run into any memory issues.
but keep in mind the varied devices that people use might not be as good as yours, so keep
it as simple as possible.

Allows for the same configuration as your 'source' quiz properties. But...

If you choose Nad's advanced quiz, *ALL* files must be in Nad's format. Same goes for the
regular quiz. File formats must be one *or* the other (not both types!), and all of them
in the same format. Got it? ;)

A "Quiz File List" can be either control panel Child Items, or a dataURL. A dataURL will
take priority over control panel child items.

Question Pools for the Exam can be obtained in any of 3 ways;

1) Control Panel childItems from another quiz within the app
2) a dataURL to a childItem quiz text file
3) a bundled childItem file.

NO filename can be the same. We save those to cache.

Bad:

{
"itemId": "XXXXXXXXXXXXX",
"itemType": "SW_examSourceItem",
"friendlyName": "Resistance",
"examSourceFile": "http://www.myserver.com/quiz1/questions.txt" <-- same filename
},
{
"itemId": "XXXXXXXXXXXXX",
"itemType": "SW_examSourceItem",
"friendlyName": "Resistance",
"examSourceFile": "http://www.myserver.com/quiz2/questions.txt" <-- same filename
}

Good:

{
"itemId": "XXXXXXXXXXXXX",
"itemType": "SW_examSourceItem",
"friendlyName": "Resistance",
"examSourceFile": "http://www.myserver.com/quiz1/questions1.txt" <-- diff filename
},
{
"itemId": "XXXXXXXXXXXXX",
"itemType": "SW_examSourceItem",
"friendlyName": "Resistance",
"examSourceFile": "http://www.myserver.com/quiz2/questions2.txt" <-- diff filename
}

We require unique filenames for each quiz source, as those are the filenames we write to
cache. If you use the same filename, the second file will overwrite the first, and you
will have two identical sources in the same exam, resulting in more questions from one
topic (possibly resulting in duplicates, too) as well as an incomplete exam. Bad Juju.

If you ask for more questions than exists in your source file, the additional questions
will be ignored, not duplicated. So, if you ask for 6 random questions from 4 files, and
your third file only has 4 questions, your ‘exam’ will have 22 questions, not 24.

6 + 6 + 4 + 6 = 22. We do not allow duplicates. You’ll have to pry the keyboard from my cold hands.

You can choose a ‘global’ number of random questions for all ‘question pools’ — or you can specify per pool.
This will allow you to add an additional question to a pool if you need to ‘even’ the total number somehow.

For instance, you have 4 test pools, and want a 10 question exam:

Quiz Pool 1 - 2 random questions pulled
Quiz Pool 2 - 2 random questions pulled
Quiz Pool 3 - 3 random questions pulled
Quiz Pool 4 - 3 random questions pulled

For 10 questions total.

In fact, 'creative weighting' can provide emphasis on 'primary' question pools, while allowing
for a 'lighter weight' on elementary or lower priority question pools. Such as this example:

Quiz Pool 1 - 1 random questions pulled
Quiz Pool 2 - 2 random questions pulled
Quiz Pool 3 - 3 random questions pulled
Quiz Pool 4 - 4 random questions pulled

This still provides for a 10 question exam, but more questions are pulled from 'more important'
topics.

There is an explanation of use in a PDF located here:

https://www.marianasgps.com/public/exambuilder_v1.pdf

+++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++
Release History:

v1.0 - November 21, 2015
------------------------
1) Initial Release for iOS and Android

v1.1 - November 27, 2015
------------------------
1) Fixed issue regarding number of questions
2) added ‘Nike’ mode (no buttons; Just do it)

v1.2 - November 29, 2015
------------------------
1) Improved Control Panel Esthetics
2) More graceful return to prev screen (iOS)

v1.3 - December 7, 2015
------------------------
1) Forgot to include a control panel section. oops.

+++++++++++++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++++++++++++++++++++++++++++++++++++

iOS Project
------------------------
SW_examBuilder.h
SW_examBuilder.m

Android Project
------------------------
SW_examBuilder.java
SW_examBuilder.xml

JSON Data
------------------------

Json data varies depending on your configuration. It 'mimics' the behavior of both the Nad Advanced Quiz, and the BT Screen Quiz.

Json data will reflect the type of Quiz that is selected. Please see the read me of the specific plugin for Json Configuration Examples.

Child Item files should follow this example:

{
"childItems": [
{
"itemId": "00AD7651866FCB77601980B",
"itemType": "SW_examSourceItem",
"friendlyName": "MotownArtists",
"examSourceFile": "gordy.txt",
"lQCount": "3"
},
{
"itemId": "7FD4E39FC127DF49F4E1E49",
"itemType": "SW_examSourceItem",
"friendlyName": "60sEraRockandRoll",
"examSourceFile": "https: //myserver.com/quiz/rr.txt",
"lQCount": "3"
},
{
"itemId": "316DCFD642AC9B433D95277",
"itemType": "SW_examSourceItem",
"friendlyName": "CountryMusicHallofFame",
"examSourceFile": "AdvQuiz",
"screenItemId": "7F6B20EB062A2554D2F4DB3",
"lQCount": "4"
}
]
}