View of /trunk/webwork-modperl/lib/WeBWorK/PG.pm

    1 ################################################################################
    2 # WeBWorK mod_perl (c) 2000-2002 WeBWorK Project
    3 # $Id$
    4 ################################################################################
    5 
    6 package WeBWorK::PG;
    7 
    8 =head1 NAME
    9 
   10 WeBWorK::PG - Invoke one of several PG rendering methods using an easy-to-use
   11 API.
   12 
   13 =cut
   14 
   15 use strict;
   16 use warnings;
   17 use WeBWorK::Utils qw(runtime_use);
   18 
   19 sub new {
   20   shift; # throw away invocant -- we don't need it
   21   my ($ce, $user, $key, $set, $problem, $psvn, $formFields,
   22     $translationOptions) = @_;
   23 
   24   my $renderer = $ce->{pg}->{renderer};
   25 
   26   runtime_use $renderer;
   27 
   28   return $renderer->new(@_);
   29 }
   30 
   31 1;
   32 
   33 __END__
   34 
   35 =head1 SYNOPSIS
   36 
   37  $pg = WeBWorK::PG->new(
   38    $ce,         # a WeBWorK::CourseEnvironment object
   39    $user,       # a WeBWorK::DB::Record::User object
   40    $sessionKey,
   41    $set,        # a WeBWorK::DB::Record::UserSet object
   42    $problem,    # a WeBWorK::DB::Record::UserProblem object
   43    $psvn,
   44    $formFields  # in &WeBWorK::Form::Vars format
   45    { # translation options
   46      displayMode     => "images", # (plainText|formattedText|images)
   47      showHints       => 1,        # (0|1)
   48      showSolutions   => 0,        # (0|1)
   49      refreshMath2img => 0,        # (0|1)
   50      processAnswers  => 1,        # (0|1)
   51    },
   52  );
   53 
   54  $translator = $pg->{translator}; # WeBWorK::PG::Translator
   55  $body       = $pg->{body_text};  # text string
   56  $header     = $pg->{head_text};  # text string
   57  $answerHash = $pg->{answers};    # WeBWorK::PG::AnswerHash
   58  $result     = $pg->{result};     # hash reference
   59  $state      = $pg->{state};      # hash reference
   60  $errors     = $pg->{errors};     # text string
   61  $warnings   = $pg->{warnings};   # text string
   62  $flags      = $pg->{flags};      # hash reference
   63 
   64 =head1 DESCRIPTION
   65 
   66 WeBWorK::PG is a factory for modules which use the WeBWorK::PG API. Notable
   67 modules which use this API (and exist) are WeBWorK::PG::Local and
   68 WeBWorK::PG::Remote. The course environment key $pg{renderer} is consulted to
   69 determine which render to use.
   70 
   71 =head1 THE WEBWORK::PG API
   72 
   73 Modules which support this API must implement the following method:
   74 
   75 =over
   76 
   77 =item new (ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS)
   78 
   79 The C<new> method creates a translator, initializes it using the parameters
   80 specified, translates a PG file, and processes answers. It returns a reference
   81 to a blessed hash containing the results of the translation process.
   82 
   83 =back
   84 
   85 =head2 Parameters
   86 
   87 =over
   88 
   89 =item ENVIRONMENT
   90 
   91 a WeBWorK::CourseEnvironment object
   92 
   93 =item USER
   94 
   95 a WeBWorK::User object
   96 
   97 =item KEY
   98 
   99 the session key of the current session
  100 
  101 =item SET
  102 
  103 a WeBWorK::Set object
  104 
  105 =item PROBLEM
  106 
  107 a WeBWorK::DB::Record::UserProblem object. The contents of the source_file
  108 field can specify a PG file either by absolute path or path relative to the
  109 "templates" directory. I<The caller should remove taint from this value before
  110 passing!>
  111 
  112 =item PSVN
  113 
  114 the problem set version number
  115 
  116 =item FIELDS
  117 
  118 a reference to a hash (as returned by &WeBWorK::Form::Vars) containing form
  119 fields submitted by a problem processor. The translator will look for fields
  120 like "AnSwEr[0-9]" containing submitted student answers.
  121 
  122 =item OPTIONS
  123 
  124 a reference to a hash containing the following data:
  125 
  126 =over
  127 
  128 =item displayMode
  129 
  130 one of "plainText", "formattedText", or "images"
  131 
  132 =item showHints
  133 
  134 boolean, render hints
  135 
  136 =item showSolutions
  137 
  138 boolean, render solutions
  139 
  140 =item refreshMath2img
  141 
  142 boolean, force images created by math2img (in "images" mode) to be recreated,
  143 even if the PG source has not been updated. FIXME: remove this option.
  144 
  145 =item processAnswers
  146 
  147 boolean, call answer evaluators and graders
  148 
  149 =back
  150 
  151 =back
  152 
  153 =head2 RETURN VALUE
  154 
  155 The C<new> method returns a blessed hash reference containing the following
  156 fields. More information can be found in the documentation for
  157 WeBWorK::PG::Translator.
  158 
  159 =over
  160 
  161 =item translator
  162 
  163 The WeBWorK::PG::Translator object used to render the problem.
  164 
  165 =item head_text
  166 
  167 HTML code for the E<lt>headE<gt> block of an resulting web page. Used for
  168 JavaScript features.
  169 
  170 =item body_text
  171 
  172 HTML code for the E<lt>bodyE<gt> block of an resulting web page.
  173 
  174 =item answers
  175 
  176 An C<AnswerHash> object containing submitted answers, and results of answer
  177 evaluation.
  178 
  179 =item result
  180 
  181 A hash containing the results of grading the problem.
  182 
  183 =item state
  184 
  185 A hash containing the new problem state.
  186 
  187 =item errors
  188 
  189 A string containing any errors encountered while rendering the problem.
  190 
  191 =item warnings
  192 
  193 A string containing any warnings encountered while rendering the problem.
  194 
  195 =item flags
  196 
  197 A hash containing PG_flags (see the Translator docs).
  198 
  199 =back
  200 
  201 =head1 AUTHOR
  202 
  203 Written by Sam Hathaway, sh002i (at) math.rochester.edu.
  204 
  205 =cut