Request that the problem HTML page also include additional CSS files from the webwork2/htdocs/ directory or from an external location.
ADD_CSS_FILE($file, $external);If external is 1, it is assumed the full url is provided. If external is 0 or not given, then file name will be prefixed with the webwork2/htdocs/ directory. For example:
ADD_CSS_FILE("css/rtl.css");
ADD_CSS_FILE("https://external.domain.com/path/to/file.css", 1);Request that the problem HTML page also include additional JS files from the webwork2/htdocs/ directory or from an external location.
ADD_JS_FILE($file, $external);If external is 1, it is assumed the full url is provided. If external is 0 or not given, then file name will be prefixed with the webwork2/htdocs/ directory.
Additional attributes can be passed as a hash reference in the optional third argument. These attributes will be added as attributes to the script tag.
For example:
ADD_JS_FILE("js/Base64/Base64.js");
ADD_JS_FILE("//web.geogebra.org/4.4/web/web.nocache.js", 1);
ADD_JS_FILE("js/GraphTool/graphtool.js", 0, { id => "gt_script", defer => undef });These two subroutines can be used in filters to set default options. They help make filters perform in uniform, predictable ways, and also make it easy to recognize from the code which options a given filter expects.
Use this to assign aliases for the standard options. It must come before set_default_options within the subroutine.
assign_option_aliases(\%options,
'alias1' => 'option5'
'alias2' => 'option7'
);If the subroutine is called with an option " alias1 => 23 " it will behave as if it had been called with the option " option5 => 23 "
set_default_options(\%options,
'_filter_name' => 'filter',
'option5' => .0001,
'option7' => 'ascii',
'allow_unknown_options => 0,
}Note that the first entry is a reference to the options with which the filter was called.
The option5 is set to .0001 unless the option is explicitly set when the subroutine is called.
The '_filter_name' option should always be set, although there is no error if it is missing. It is used mainly for debugging answer evaluators and allows you to keep track of which filter is currently processing the answer.
If 'allow_unknown_options' is set to 0 then if the filter is called with options which do NOT appear in the set_default_options list an error will be signaled and a warning message will be printed out. This provides error checking against misspelling an option and is generally what is desired for most filters.
Occasionally one wants to write a filter which accepts a long list of options, not all of which are known in advance, but only uses a subset of the options provided. In this case, setting 'allow_unkown_options' to 1 prevents the error from being signaled.
includePGproblem($filePath);
Essentially runs the pg problem specified by $filePath, which is
a path relative to the top of the templates directory. The output
of that problem appears in the given problem.PG.pl - Provides core Program Generation Language functionality.
In a PG problem:
DOCUMENT(); # should be the first statment in the problem
loadMacros(.....); # (optional) load other macro files if needed.
HEADER_TEXT(...); # (optional) used only for inserting javaScript into problems.
TEXT( # insert text of problems
"Problem text to be displayed. ",
"Enter 1 in this blank:",
ANS_RULE(1,30) # ANS_RULE() defines an answer blank 30 characters long.
# It is defined in F<PGbasicmacros.pl>
);
ANS(answer_evalutors); # see F<PGanswermacros.pl> for examples of answer evaluatiors.
ENDDOCUMENT() # must be the last statement in the problemThis file provides the fundamental macros that define the PG language. It maintains a problem's text, header text, and answers:
Problem text: The text to appear in the body of the problem. See TEXT() below.
Header text: When a problem is processed in an HTML-based display mode, this variable can contain text that the caller should place in the HEAD of the resulting HTML page. See HEADER_TEXT() below.
Implicitly-labeled answers: Answers that have not been explicitly assigned names, and are associated with their answer blanks by the order in which they appear in the problem. These types of answers are designated using the ANS() macro.
Explicitly-labeled answers: Answers that have been explicitly assigned names with the LABELED_ANS() macro, or a macro that uses it. An explicitly- labeled answer is associated with its answer blank by name.
"Extra" answers: Names of answer blanks that do not have a 1-to-1 correspondance to an answer evaluator. For example, in matrix problems, there will be several input fields that correspond to the same answer evaluator.
This file is automatically loaded into the namespace of every PG problem. The macros within can then be called to define the structure of the problem.
DOCUMENT() should be the first executable statement in any problem. It initializes vriables and defines the problem environment.
ENDDOCUMENT() must be the last executable statement in any problem. It packs up the results of problem processing for delivery back to WeBWorK.
The HEADER_TEXT(), TEXT(), and ANS() macros add to the header text string, body text string, and answer evaluator queue, respectively.
HEADER_TEXT("string1", "string2", "string3");HEADER_TEXT() concatenates its arguments and appends them to the stored header text string. It can be used more than once in a file.
The macro is used for material which is destined to be placed in the HEAD of the page when in HTML mode, such as JavaScript code.
Spaces are placed between the arguments during concatenation, but no spaces are introduced between the existing content of the header text string and the new content being appended.
TEXT("string1", "string2", "string3");TEXT() concatenates its arguments and appends them to the stored problem text string. It is used to define the text which will appear in the body of the problem. It can be used more than once in a file.
This macro has no effect if rendering has been stopped with the STOP_RENDERING() macro.
This macro defines text which will appear in the problem. All text must be passed to this macro, passed to another macro that calls this macro, or included in a BEGIN_TEXT/END_TEXT block, which uses this macro internally. No other statements in a PG file will directly appear in the output. Think of this as the "print" function for the PG language.
Spaces are placed between the arguments during concatenation, but no spaces are introduced between the existing content of the header text string and the new content being appended.
TEXT(ans_rule(), ans_rule(), ans_rule());
ANS($answer_evaluator1, $answer_evaluator2, $answer_evaluator3);Adds the answer evaluators listed to the list of unlabeled answer evaluators. They will be paired with unlabeled answer rules (a.k.a. answer blanks) in the order entered. This is the standard method for entering answers.
In the above example, answer_evaluator1 will be associated with the first answer rule, answer_evaluator2 with the second, and answer_evaluator3 with the third. In practice, the arguments to ANS() will usually be calls to an answer evaluator generator such as the cmp() method of MathObjects or the num_cmp() macro in PGanswermacros.pl.
TEXT(labeled_ans_rule("name1"), labeled_ans_rule("name2"));
LABELED_ANS(name1 => answer_evaluator1, name2 => answer_evaluator2);Adds the answer evaluators listed to the list of labeled answer evaluators. They will be paired with labeled answer rules (a.k.a. answer blanks) in the order entered. This allows pairing of answer evaluators and answer rules that may not have been entered in the same order.
STOP_RENDERING() unless all_answers_are_correct();Temporarily suspends accumulation of problem text and storing of answer blanks and answer evaluators until RESUME_RENDERING() is called.
RESUME_RENDERING();Resumes accumulating problem text and storing answer blanks and answer evaluators. Reverses the effect of STOP_RENDERING().
ENDDOCUMENT();When PG problems are evaluated, the result of evaluating the entire problem is interpreted as the return value of ENDDOCUMENT(). Therefore, ENDDOCUMENT() must be the last executable statement of every problem. It can only appear once. It returns a list consisting of:
A reference to a string containing the rendered text of the problem.
A reference to a string containing text to be placed in the HEAD block when in and HTML-based mode (e.g. for JavaScript).
A reference to the hash mapping answer labels to answer evaluators.
A reference to a hash containing various flags:
showPartialCorrectAnswers: determines whether students are told which of their answers in a problem are wrong.
recordSubmittedAnswers: determines whether students submitted answers are saved.
refreshCachedImages: determines whether the cached image of the problem in typeset mode is always refreshed (i.e. setting this to 1 means cached images are not used).
solutionExits: indicates the existence of a solution.
hintExits: indicates the existence of a hint.
comment: contents of COMMENT commands if any.
PROBLEM_GRADER_TO_USE: a reference to the chosen problem grader. ENDDOCUMENT chooses the problem grader as follows:
If a problem grader has been chosen in the problem by calling install_problem_grader(\&grader), it is used.
Otherwise, if the PROBLEM_GRADER_TO_USE PG environment variable contains a reference to a subroutine, it is used.
Otherwise, if the PROBLEM_GRADER_TO_USE PG environment variable contains the string std_problem_grader or the string avg_problem_grader, &std_problem_grader or &avg_problem_grader are used. These graders are defined in PGanswermacros.pl.
Otherwise, the PROBLEM_GRADER_TO_USE flag will contain an empty value and the PG translator should select &std_problem_grader.
These macros should only be used by other macro files. In practice, they are used exclusively by PGbasicmacros.pl.
DEPRECATED
Increments the internal count of the number of answer blanks that have been defined ($ans_rule_count) and returns the new count. This should only be used when one is about to define a new answer blank, for example with NEW_ANS_NAME().
RECORD_ANS_NAME("label", "VALUE");Records the label for an answer blank. Used internally by PGbasicmacros.pl to record the order of explicitly-labelled answer blanks.
NEW_ANS_NAME();Generates an anonymous answer label from the internal count The label is added to the list of implicity-labeled answers. Used internally by PGbasicmacros.pl to generate labels for unlabeled answer blanks.
ANS_NUM_TO_NAME($num);Generates an answer label from the supplied answer number, but does not add it to the list of inplicitly-labeled answers. Used internally by PGbasicmacros.pl in generating answers blanks that use radio buttons or check boxes. (This type of answer blank uses multiple HTML INPUT elements with the same label, but the label should only be added to the list of implicitly- labeled answers once.)
RECORD_FORM_LABEL("label");Stores the label of a form field in the "extra" answers list. This is used to keep track of answer blanks that are not associated with an answer evaluator.
NEW_ANS_ARRAY_NAME($num, $row, $col);Generates a new answer label for an array (vector) element and adds it to the list of implicitly-labeled answers.
NEW_ANS_ARRAY_NAME_EXTENSION($num, $row, $col);Generate an additional answer label for an existing array (vector) element and add it to the list of "extra" answers.
get_PG_ANSWERS_HASH();
get_PG_ANSWERS_HASH($key);includePGproblem($filePath);
Essentially runs the pg problem specified by $filePath, which is
a path relative to the top of the templates directory. The output
of that problem appears in the given problem.