Each WeBWorK problem is defined in a text file written in an extension of the Perl scripting language. These files are called PG (Problem Generation) files, and are stored on the WeBWorK server. (PG files can also contain other scripting or markup languages that help to define the problem, such LaTex or PGML.)
This article will cover:
- Creating a new Problem using a standard PG template.
- Using the Editor to modify and save the Problem's source code.
- Saving and Locating your local Problem in the Library Browser.
(Note: Advanced Problem Editing will be covered in a future article.)
Creating a new Problem from a Template
We will add a blank problem to a homework set to create a standard code template that you can customize.
This video shows the steps to create a new Problem using a standard template:
First, we must create a new Problem by adding a new, empty problem template. Then, we'll edit it using the built-in text editor.
This assumes that you have an existing Homework Set in which to add a new problem.
If you need to create a new Homework Set, use the instructions in this article, before continuing: KB1257 - WeBWorK: Creating a new Homework Set
-
Go to your WeBWorK course homepage and click "Hmwrk Sets Editor" in the menu.
-
Click the number under the "Edit Problems" column next to the set. (This will put you on the set's "Details" page.)
-
Scroll down to the very bottom of the "Details" page and check the "Add" checkbox, and enter the number of "blank problem templates" that you want to add.
(A blank problem template is a text file set up for you to more easily create a new problem.)
-
Click Save Changes.
-
Scroll all the way down through the "Problems" section again, and you will now see your new blank problem(s) added as the last item(s) in the list.
Click the pencil icon to edit a new problem. (You will then see your problem loaded into the online text editor.)
Good Structure for Problem Files
When writing a custom problem, you must follow the standard structure of WeBWorK problems in the template:
There are five sections in a typical WeBWorK Problem file:
-
Tagging and description section: Describes the problem.
-
Initialization section: Loads required macros for the problem.
-
Problem set-up section: Sets variables specific to the problem.
-
Text section: Gives the text that is shown to the student.
-
Answer and solution section: Specifies how answer(s) to the problem are marked for correctness, and gives a solution that may be shown to the student after the problem set is complete.
The Problem Editor
This section covers the most essential functions of the WeBWorK text editor, so you can do simple text tweaks (like changing the word "inches" to "centimetres").
Editor Toolbar Buttons
The toolbar at the top of the text editor leads to helpful documentation and tools for WeBWorK authors:
- Problem Techniques: A vast directory of techniques you can use to construct problems in WeBWorK.
- Math Objects: Wiki page to learn about using MathObjects in your problems.
- POD: External documentation for PF modules and macro files (Rochester.edu).
- PGLab: External site to test snippets of Problem Generation code in an interactive editor (Rochester.edu).
- PGML: Note - This button leads to a missing external web page and causes an error. (eLSupport will try to address it.)
- Author Info: A directory of topics to help WeBWorK Problem Authors (that's you).
- Report Bugs in this Problem: Log into the WeBWorK Bugzilla reporting system to report an issue with a problem.
More detail about the fields in the editor page can be found by clicking the (?) icon in the left-hand navigation menu.
Doing Basic Text Edits on a Problem
In the "Text" section of the Problem source, look for these lines:
BEGIN_TEXT
and
END_TEXT
Between those instructions, you will see the problem's text content that will be printed to the screen.
Read the source code carefully, so you have a good sense of how it works.
The code uses colour-coding (aka syntax highlighting) to help show its structure and to differentiate things like variables and functions from plain text, etc.
- Comments may be coloured in tan. (These start with # or ## or ### and are only instructive or descriptive in nature.)
- Any regular text that you can safely edit will be coloured in black.
- Perl instructions may be coloured brown or blue. (Don't touch them unless you know what you're doing.)
- Don't edit or remove the lines that say BEGIN_TEXT or END_TEXT - those are part of the problem's internal structure.
For example, below, the text "Enter a value for " is safely editable. On the same line, the text immediately after that will emit the value for the variable "pi" (which would have been defined near the beginning of the PG file, in the Problem Setup section - not shown here).
BEGIN_TEXT
Enter a value for \(\pi\)
\{$pi->ans_rule\}
END_TEXT
Saving your Problem File
When you've completed your edits, the edited problem file must be saved locally as your own copy.
-
Below the text editor, click the New Version tab.
-
You should rename the file:
If the file was named
setSample_Simple_Homework_Set/blankProblem.pg
you could rename it to
setSample_Simple_Homework_Set/my-new-blankProblem.pg
(No spaces in filenames or folders please!)
-
Click Take Action to save this problem file.
You can edit your custom questions at any time, using the "Edit" icon inside your Homework Set's "Set Details" page.
Finding and Using Your Local Problems
You can find your locally-saved problems using the Library Browser (similar to public problems). Select "Local Problems" and then scroll down through the list of Local Problems, until you find yours (usually listed at the bottom).
Going Further with Writing Problems
Editing WeBWorK problems is too vast a topic to cover in this one article. There are many methods, libraries and techniques available to you, depending on your needs. The Mathematical Association of America (MMA) has a great series of tutorial articles for WeBWorK Authors: https://webwork.maa.org/wiki/Authors
Related Resources: