Diff of /trunk/webwork2/lib/WeBWorK/PG.pm

Revision 439		Revision 440
		1	################################################################################
		2	# WeBWorK mod_perl (c) 1995-2002 WeBWorK Team, Univeristy of Rochester
		3	# $Id$
		4	################################################################################
		5
1	package WeBWorK::PG;	6	package WeBWorK::PG;
2
3	# hide PG::* from the not-yet-insane.
4	# "PG Render" or something
5		7
6	use strict;	8	use strict;
7	use warnings;	9	use warnings;
8	use WeBWorK::Utils qw(readFile formatDateTime);	10	use WeBWorK::Utils qw(readFile formatDateTime);
9	use WeBWorK::DB::Classlist;	11	use WeBWorK::DB::Classlist;
…		…
128	if $grader eq "avg_problem_grader";	130	if $grader eq "avg_problem_grader";
129	die "Problem grader $grader is not a CODE reference."	131	die "Problem grader $grader is not a CODE reference."
130	unless ref $grader eq "CODE";	132	unless ref $grader eq "CODE";
131	$translator->rf_problem_grader($grader);	133	$translator->rf_problem_grader($grader);
132		134
133	# grading the problem	135	# grade the problem
134	warn "PG: grade the problem\n";	136	warn "PG: grading the problem\n";
135	my ($result, $state) = $translator->grade_problem(	137	my ($result, $state) = $translator->grade_problem(
136	answers_submitted => $translationOptions->{processAnswers},	138	answers_submitted => $translationOptions->{processAnswers},
137	ANSWER_ENTRY_ORDER => \@answerOrder,	139	ANSWER_ENTRY_ORDER => \@answerOrder,
138	);	140	);
139		141
…		…
286	$errorno = 0;	288	$errorno = 0;
287	return($answer, $errorno);	289	return($answer, $errorno);
288	}	290	}
289		291
290	1;	292	1;
		293
		294	__END__
		295
		296	=head1 NAME
		297
		298	WeBWorK::PG - Wrap the action of the PG Translator in an easy-to-use API
		299
		300	=head1 SYNOPSIS
		301
		302	$pg = WeBWorK::PG->new(
		303	$courseEnv, # a WeBWorK::CourseEnvironment object
		304	$userName,
		305	$sessionKey,
		306	$setName,
		307	$problemNumber,
		308	{ # translation options
		309	displayMode => "images", # (plainText\|formattedText\|images)
		310	showHints => 1, # (0\|1)
		311	showSolutions => 0, # (0\|1)
		312	refreshMath2img => 0, # (0\|1)
		313	processAnswers => 1, # (0\|1)
		314	},
		315	$formFields # in WeBWorK::Form::Vars format
		316	);
		317
		318	$translator = $pg->{translator}; # WeBWorK::PG::Translator
		319	$body = $pg->{body_text}; # text string
		320	$header = $pg->{head_text}; # text string
		321	$answerHash = $pg->{answers}; # WeBWorK::PG::AnswerHash
		322	$result = $pg->{result}; # hash reference
		323	$state = $pg->{state}; # hash reference
		324	$errors = $pg->{errors}; # text string
		325	$warnings = $pg->{warnings}; # text string
		326	$flags = $pg->{flags}; # hash reference
		327
		328	=head1 DESCRIPTION
		329
		330	WeBWorK::PG encapsulates the PG translation process, making multiple calls to
		331	WeBWorK::PG::Translator. Much of the flexibility of the Translator is hidden,
		332	instead making choices that are appropriate for the webwork-modperl system.
		333
		334	=head1 CONSTRUCTION
		335
		336	=over
		337
		338	=item new (ENVIRONMENT, USER, KEY, SET, PROBLEM, OPTIONS, FIELDS)
		339
		340	The C<new> method creates a translator, initializes it using the parameters
		341	specified, translates a PG file, and processes answers. It returns a reference
		342	to a blessed hash containing the results of the translation process.
		343
		344	=back
		345
		346	=head2 Parameters
		347
		348	=over
		349
		350	=item ENVIRONMENT
		351
		352	a WeBWorK::CourseEnvironment object
		353
		354	=item USER
		355
		356	the name of the user for whom to render
		357
		358	=item KEY
		359
		360	the session key of the current session
		361
		362	=item SET
		363
		364	the name of the problem set from which to get the problem
		365
		366	=item PROBLEM
		367
		368	the number of the problem to render
		369
		370	=item OPTIONS
		371
		372	a reference to a hash containing the following data:
		373
		374	=over
		375
		376	=item displayMode
		377
		378	one of "plainText", "formattedText", or "images"
		379
		380	=item showHints
		381
		382	boolean, render hints
		383
		384	=item showSolutions
		385
		386	boolean, render solutions
		387
		388	=item refreshMath2img
		389
		390	boolean, force images created by math2img (in "images" mode) to be recreated,
		391	even if the PG source has not been updated.
		392
		393	=item processAnswers
		394
		395	boolean, call answer evaluators and graders
		396
		397	=back
		398
		399	=item FIELDS
		400
		401	a reference to a hash (as returned by &WeBWorK::Form::Vars) containing form
		402	fields submitted by a problem processor. The translator will look for fields
		403	like "AnSwEr[0-9]" containing submitted student answers.
		404
		405	=back
		406
		407	=head2 RETURN VALUE
		408
		409	The C<new> method returns a blessed hash reference containing the following
		410	fields. More information can be found in the documentation for
		411	WeBWorK::PG::Translator.
		412
		413	=over
		414
		415	=item translator
		416
		417	The WeBWorK::PG::Translator object used to render the problem.
		418
		419	=item head_text
		420
		421	HTML code for the E<lt>headE<gt> block of an resulting web page. Used for
		422	JavaScript features.
		423
		424	=item body_text
		425
		426	HTML code for the E<lt>bodyE<gt> block of an resulting web page.
		427
		428	=item answers
		429
		430	An C<AnswerHash> object containing submitted answers, and results of answer
		431	evaluation.
		432
		433	=item result
		434
		435	A hash containing the results of grading the problem.
		436
		437	=item state
		438
		439	A hash containing the new problem state.
		440
		441	=item errors
		442
		443	A string containing any errors encountered while rendering the problem.
		444
		445	=item warnings
		446
		447	A string containing any warnings encountered while rendering the problem.
		448
		449	=item flags
		450
		451	A hash containing PG_flags (see the Translator docs).
		452
		453	=back
		454
		455	=head1 OPERATION
		456
		457	WeBWorK::PG goes through the following operations when constructed:
		458
		459	=over
		460
		461	=item Get database information
		462
		463	Retrieve information about the current user, set, and problem from the
		464	database.
		465
		466	=item Create a translator
		467
		468	Instantiate a WeBWorK::PG::Translator object.
		469
		470	=item Set the directory hash
		471
		472	Set the translator's directory hash (courseScripts, macros, templates, and temp
		473	directories) from the course environment.
		474
		475	=item Evaluate PG modules
		476
		477	Using the module list from the course environment (pg->modules), perform a
		478	"use"-like operation to evaluate modules at runtime.
		479
		480	=item Set the problem environment
		481
		482	Use data from the user, set, and problem, as well as the course environemnt and
		483	translation options, to set the problem environment.
		484
		485	=item Initialize the translator
		486
		487	Call &WeBWorK::PG::Translator::initialize. What more do you want?
		488
		489	=item Load PG.pl and dangerousMacros.pl
		490
		491	These macros must be loaded without opcode masking, so they are loaded here.
		492
		493	=item Set the opcode mask
		494
		495	Set the opcode mask to the default specified by WeBWorK::PG::Translator.
		496
		497	=item Load the problem source
		498
		499	Give the problem source to the translator.
		500
		501	=item Install a safety filter
		502
		503	The safety filter is used to preprocess student input before evaluation. The
		504	default safety filter, &WeBWorK::PG::safetyFilter, is used.
		505
		506	=item Translate the problem source
		507
		508	Call &WeBWorK::PG::Translator::translate to render the problem source into the
		509	format given by the display mode.
		510
		511	=item Process student answers
		512
		513	Use form field inputs to evaluate student answers.
		514
		515	=item Load the problem state
		516
		517	Use values from the database to initialize the problem state, so that the
		518	grader will have a point of reference.
		519
		520	=item Determine an entry order
		521
		522	Use the ANSWER_ENTRY_ORDER flag to determine the order of answers in the
		523	problem. This is important for problems with dependancies among parts.
		524
		525	=item Install a grader
		526
		527	Use the PROBLEM_GRADER_TO_USE flag, or a default from the course environment,
		528	to install a grader.
		529
		530	=item Grade the problem
		531
		532	Use the selected grader to grade the problem.
		533
		534	=back
		535
		536	=head1 AUTHOR
		537
		538	Written by Sam Hathaway, sh002i (at) math.rochester.edu.
		539
		540	=cut

 Legend:



Removed from v.439
 


changed lines


 
Added in v.440
 Legend:



Removed from v.439
 


changed lines


 
Added in v.440
-Removed from v.439
+Added in v.440

aubreyja at gmail dot com	ViewVC Help
Powered by ViewVC 1.0.9