Polls definition code

Imagine one is having the following two polls defined at arbitrary wiki page. Copy / paste the following wiki code into arbitrary main namespace page of your wiki after installation of Extension:QPoll :

<qpoll id="personal_data" interpretation="check_personal_data" layout="tabular">
{Personal information (mandatory fields are marked with *)
|type="text" emptytext="yes" name="person"}
:|name="age" emptytext="no"|Age* <<::width=2>>
:|name="sex" emptytext="no"|Sex* <<male|female>>
:|name="ethnic_origin" emptytext="no" catreq=1|Ethnic origin<sup>*</sup> <<Russian|Tatar|Ukrainian|Bashkir>> or (''arbitrary'') : <<>>
:|birthplace|Birth place <<>>
:|livingplace|Living place <<>>
:|education|Education <<>>
:|qualification|Qualification <<>>
:|workplace|Workplace <<>>
:|occupance|Occupance <<>>
</qpoll>

----
Check your knowledge of English language.
<qpoll id="english_language_test" interpretation="check_english_language_test" max_attempts="10"  dependance="#personal_data">
{Please conjugate verb "accept".
|type="text" emptytext="no" name="verb_test"}
:|name="infinitive"|Infinitive <<|to accept|accepted|accepting>>
:|name="participle"|Participle <<|to accept|accepted|accepting>>
:|name="gerund"|Gerund  <<|to accept|accepted|accepting>>
{Complete the sentences.
|type="text" emptytext="no" name="sentences"}
:|name="short_text"|A duck is a type of <<|fish|mammal|bird>>.<br />Hi! My <<|name|country|city>> is Andrew. How are you?<br />Today is Sunday. Tomorrow is <<|Friday|Saturday|Monday>>.
</qpoll>

A successful submission of both polls will result in output similar to provided at the screenshot.

• First poll has id personal_data. It's attached (bound) to interpretation script page Interpretation:Check_personal_data. The poll has one question with name person. That question has proposals with the following names defined: age, sex, ethnic_origin, birthplace, livingplace, education, qualification, workplace, occupance.

• Second poll has id english_language_test. It's attached (bound) to interpretation script page Interpretation:Check_english_language_test. The poll has two question with the following names: verb_test, sentences. The question with name verb_test has proposals with the following names defined: infinitive, participle, gerund. The question with name sentences has proposal with the name short_text.
• Also note that second poll has dependance="#personal_data" attribute, which means that it will be available for voting only after successful submission of first poll.

• Let's explain declaration of proposal with name ethnic_origin:

:|name="ethnic_origin" emptytext="no" catreq=1|Ethnic origin^* <<Russian|Tatar|Ukrainian|Bashkir>> or (''arbitrary'') : <<>>

• This proposal defines two categories: first one is select with four pre-defined text options: <<Russian|Tatar|Ukrainian|Bashkir>>. Second category is ordinary text field: <<>>. It would be very hard to list all possible ethnic origins of the world, so we place the pre-defined list of most common ethnic origins into first field (select) while allowing to supply arbitrary ethnic_origin proposal value via second text field. We disable the submission of empty text input (which would be meaningless) via emptytext="no" proposal attribute. We allow to fill only one, not all (not both) of category fields via catreq=1 attribute, because we assume that there is no multiple ethnic origins at once (which actually might be false, but that's just an example). Note that both fields still could be submitted by user (which is not mandatory yet possible), thus we'll address such case in the interpretation script below.
• We use tabular layout of first poll to align form fields into the grid. Try removing that attribute from first poll header. You'll see that fields will float in the proposal text unaligned.
• Second poll is language test so it's categories (fields) intentionally are made unaligned, which is more common to "natural" text.

Definition of interpretation scripts

Note that both polls have interpretation attribute in their headers. Poll with id personal_data is bound to interpretation script which should be located at the page Interpretation:Check_personal_data . You may create such page at your wiki then place the following code into it:

<qpinterpret lang="php">
# we have only one question; this is a shortcut
$q = $answer['person'];
qp_debug('person',$q);

$result = array(
  'options' => array( 'store_erroneous' => false ),
  # possible qpc errors. 'person' is question name (we have only one question)
  'error' => array( 'person' => array() ),
  'structured' => array(
    'age' => $q['age'][0],
    'sex' => $q['sex'][0],
    'birthplace' => $q['birthplace'][0],
    'livingplace' => $q['livingplace'][0],
    'education' => $q['education'][0],
    'qualification' => $q['qualification'][0],
    'workplace' => $q['workplace'][0],
    'occupance' => $q['occupance'][0]
  )
);

# age must be a number from 18 to 100
$min_age = 18;
$max_age = 120;
if ( !ctype_digit( $q['age'][0] ) ||
     $q['age'][0] < $min_age || $q['age'][0] > $max_age ) {
  $result['error']['person']['age'] = 'Age must be a integer number from ' . $min_age . ' to ' . $max_age;
}

# We assume that one person may have only one ethnic_origin (that's just an example of category restriction).
if ( count( $q['ethnic_origin'] ) > 1 ) {
  $result['error']['person']['ethnic_origin'] = 'There can be only one ethnic origin of person.';
} else {
  $result['structured']['ethnic_origin'] = isset( $q['ethnic_origin'][0] ) ? $q['ethnic_origin'][0] : $q['ethnic_origin'][1];
}

# do not display any result to end user
$result['long'] = 'You are sucessfully registered for our polls.';

return $result;
</qpinterpret>

Poll with id english_language_test is bound to interpretation script which should be located at the page Interpretation:Check_english_language_test . You may create such page at your wiki then place the following code into it:

<qpinterpret lang="php">
qp_debug('answer',$answer);

$personal_data = qp_getStructuredInterpretation( 'QPoll01#personal_data' );
qp_debug('personal_data',$personal_data);

$result = array(
  'options' => array( 'store_erroneous' => true ),
  # Possible qpc errors.
  # 'verb_test' and 'sentences' keys are question names.
  'error' => array(
    'verb_test' => array(),
    'sentences' => array(),
  ),
  'structured' => array(
    # Structured data from previosely answered polls can be processed and stored again,
    'approx_age_in_days' => $personal_data['age'] * 365,
    'err_num' => 0,
  )
);

if ( $answer['verb_test']['infinitive'][0] !== 'to accept' ) {
  $result['error']['verb_test']['infinitive'] = 'Incorrect infinitive conjugation';
  $result['structured']['err_num']++;
}

if ( $answer['verb_test']['participle'][0] !== 'accepted' ) {
  $result['error']['verb_test']['participle'] = 'Incorrect participle conjugation';
  $result['structured']['err_num']++;
}

if ( $answer['verb_test']['gerund'][0] !== 'accepting' ) {
  $result['error']['verb_test']['gerund'] = 'Incorrect gerund conjugation';
  $result['structured']['err_num']++;
}

if ( $answer['sentences']['short_text'][0] !== 'bird' ) {
  $result['error']['sentences']['short_text'][0] = 'A bird is not a ' . $answer['sentences']['short_text'][0];
  $result['structured']['err_num']++;
}

if ( $answer['sentences']['short_text'][1] !== 'name' ) {
  $result['error']['sentences']['short_text'][1] = 'A person is not a ' . $answer['sentences']['short_text'][1];
  $result['structured']['err_num']++;
}

if ( $answer['sentences']['short_text'][2] !== 'Monday' ) {
  $result['error']['sentences']['short_text'][2] = 'Please study English days of the week.';
  $result['structured']['err_num']++;
}

if ( $result['structured']['err_num'] === 0 ) {
  $result['short'] = 'Well done!';
  $result['long'] = 'Congratulations!';
  if ( intval( $personal_data['age'] ) > 40 ) {
    $result['long'] .= " Especially because it is harder for people past 40 to learn foreign languages.";
  }
} else {
  $result['short'] = 'Not so good.';
  $result['long'] = "You have made " . $result['structured']['err_num'] . " error(s). Try better next time.";
}

qp_debug('result',$result);
return $result;
</qpinterpret>

Notes about general logic of interpretation

Result of successful interpretation of poll with id personal_data with user vote displayed at Special:PollResults page.

• Interpretation script executes only in case question / proposal restrictions are met: such as default or current catreq, max_attempts and emptytext attribute values.
• When interpretation script begins to execute, user-submitted categories are placed into nested array $answers. When question names and proposal names are used (which is recommended), $answers keys will have form of $answer['question_name']['proposal_name'][$cidx], where $cidx is category index (0..n). Remember that each proposal may have one or multiple categories selected via multiple fields (text inputs, checkboxes) or selects with multiple options. Because of that, even proposals with single category defined are returned as $answer['question_name']['proposal_name'][0] for orthogonality of interpretation scripts.
• When no question names / proposal names are used, $answer array will have the form of $answer[$qidx][$pidx][$cidx], where $qidx is (1..n), $pidx is (0..n), $cidx is (0..n).
• Interpretation script is wrapped into function call so the result of interpretation should be provided via PHP return statement at any point of execution. For convinience it's placed into variable $result in the provided samples, which is a nested array with the following keys:

if ( $answer['sentences']['short_text'][0] !== 'bird' ) {
  # Provide exact question / proposal / category ("qpc") error message.
  $result['error']['sentences']['short_text'][0] = 'A bird is not a ' . $answer['sentences']['short_text'][0];
  # Increase error counter.
  $result['structured']['err_num']++;
}

List of built-in functions

require_once( "$IP/extensions/QPoll/QPoll/qp_user.php" );
$wgDebugLogGroups['qpoll'] = 'my_arbitrary_qpoll_debug_file.txt';

$personal_data = qp_getStructuredInterpretation( 'QPoll01#personal_data' );

$result['structured']['approx_age_in_days'] = $personal_data['age'] * 365;