$inactiveTopic$ PG.pm

topic started 8/16/2002; 5:23:14 PM
last post 8/16/2002; 5:23:14 PM

$user$ Michael Gage - PG.pm $blueArrow$
8/16/2002; 5:23:14 PM (reads: 2827, responses: 0)

NAME

WeBWorK::PG - Invoke one of several PG rendering methods using an easy-to-use API.

SYNOPSIS

 $pg = WeBWorK::PG->new(
        $ce,        # a WeBWorK::CourseEnvironment object
        $user,  # a WeBWorK::DB::Record::User object
        $sessionKey,
        $set,   # a WeBWorK::DB::Record::UserSet object
        $problem,   # a WeBWorK::DB::Record::UserProblem object
        $psvn,
        $formFields # in &WeBWorK::Form::Vars format
        { # translation options
            displayMode => "images", # (plainText|formattedText|images)
            showHints   => 1,   # (0|1)
            showSolutions   => 0,   # (0|1)
            refreshMath2img => 0,   # (0|1)
            processAnswers  => 1,   # (0|1)
        },
 );

 $translator = $pg->{translator}; # WeBWorK::PG::Translator
 $body  = $pg->{body_text}; # text string
 $header    = $pg->{head_text}; # text string
 $answerHash = $pg->{answers};  # WeBWorK::PG::AnswerHash
 $result    = $pg->{result};    # hash reference
 $state = $pg->{state}; # hash reference
 $errors    = $pg->{errors};    # text string
 $warnings  = $pg->{warnings};  # text string
 $flags = $pg->{flags}; # hash reference

DESCRIPTION

WeBWorK::PG is a factory for modules which use the WeBWorK::PG API. Notable modules which use this API (and exist) are WeBWorK::PG::Local and WeBWorK::PG::Remote. The course environment key $pg{renderer} is consulted to determine which render to use.

THE WEBWORK::PG API

Modules which support this API must implement the following method:

new ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS: The new method creates a translator, initializes it using the parameters specified, translates a PG file, and processes answers. It returns a reference to a blessed hash containing the results of the translation process.

Parameters

ENVIRONMENT: a WeBWorK::CourseEnvironment object
USER: a WeBWorK::User object
KEY: the session key of the current session
SET: a WeBWorK::Set object
PROBLEM: a WeBWorK::DB::Record::UserProblem object. The contents of the source_file field can specify a PG file either by absolute path or path relative to the "templates" directory. The caller should remove taint from this value before passing!
PSVN: the problem set version number
FIELDS: a reference to a hash (as returned by &WeBWorK::Form::Vars) containing form fields submitted by a problem processor. The translator will look for fields like "AnSwEr[0-9]" containing submitted student answers.
OPTIONS: a reference to a hash containing the following data:

displayMode: one of "plainText", "formattedText", or "images"
showHints: boolean, render hints
showSolutions: boolean, render solutions
refreshMath2img: boolean, force images created by math2img (in "images" mode) to be recreated, even if the PG source has not been updated. FIXME: remove this option.
processAnswers: boolean, call answer evaluators and graders

RETURN VALUE

The new method returns a blessed hash reference containing the following fields. More information can be found in the documentation for WeBWorK::PG::Translator.

translator: The WeBWorK::PG::Translator object used to render the problem.
head_text: HTML code for the <head> block of an resulting web page. Used for JavaScript features.
body_text: HTML code for the <body> block of an resulting web page.
answers: An AnswerHash object containing submitted answers, and results of answer evaluation.
result: A hash containing the results of grading the problem.
state: A hash containing the new problem state.
errors: A string containing any errors encountered while rendering the problem.
warnings: A string containing any warnings encountered while rendering the problem.
flags: A hash containing PG_flags (see the Translator docs).