Skip to content

Latest commit

 

History

History
182 lines (141 loc) · 20.1 KB

devElements.md

File metadata and controls

182 lines (141 loc) · 20.1 KB

Element developer guide

See elements/ for example elements.

Element code uses the libraries in the python/ module.

Anatomy of an element

The system-wide elements available in the current build of the PrairieLearn server live in [PrairieLearn directory]/elements inside a folder corresponding to the element name. You can also have course-specific elements in a directory inside the root of your course repository, such as [course directory]/elements. See exampleCourse/elements for a real example of this.

By convention, all element files are named the same as the element they belong to. That directory should contain an info.json file that contains metadata about the element, including which file is the element controller and any dependencies of the element. See the section on dependencies for more information

Each element should have a .py controller that contains the functions listed in the next section. This controller is responsible for rendering the element, parsing the student's submission, and optionally grading the submission.

As a simple example, element pl-my-element would have the following file structure:

pl-my-element
+-- info.json
|-- pl-my-element.py
|-- pl-my-element.mustache
|-- pl-my-element.js
`-- pl-my-element.css

And an info.json with the following contents:

{
  "controller": "pl-my-element.py",
  "dependencies": {
    "elementScripts": ["pl-my-element.js"],
    "elementStyles": ["pl-my-element.css"]
  }
}

Element functions

All element functions are of the following form:

def fcn(element_html, data):

Note that not all functions have the same return type. The arguments are:

Argument Type Description
element_html string The template HTML for the element.
data dict Mutable data for the question, which can be modified and returned.

The data dictionary has the following possible keys (not all keys will be present in all element functions):

Key Type Description
data["correct_answers"] dict The true answer (if any) for the variant.
data["editable"] boolean Whether the question is currently in an editable state.
data["extensions"] dict A list of extensions that are available to be loaded by this element. For more information see the element extensions page.
data["feedback"] dict Any feedback to the student on their submitted answer.
data["format_errors"] dict Any errors encountered while parsing the student input.
data["manual_grading"] boolean Whether the question is being rendered in the manual grading view.
data["num_valid_submissions"] int The number of valid (not containing format errors) submissions by the student for the current variant.
data["options"] dict Any options associated with the question.
data["panel"] string Which panel is being rendered (question, submission, or answer).
data["params"] dict Parameters that describe the question variant.
data["partial_scores"] dict Partial scores for individual variables in the question.
data["raw_submitted_answers"] dict The answer submitted by the student before parsing.
data["score"] float The total final score for the question.
data["submitted_answers"] dict The answer submitted by the student (after parsing).
data["variant_seed"] integer The random seed for this question variant.

So that multiple elements can exist together in one question, the convention is that each element instance is associated with one or more variables. These variables are keys in the dictionaries for the data elements. For example, if there are variables x and y then we might have:

data["correct_answers"]["x"] = 4
data["correct_answers"]["y"] = 7
data["submitted_answers"]["x"] = 4
data["submitted_answers"]["y"] = 12

This structure, where dictionaries have variables as keys, is used for all dictionaries in data.

The element functions are:

Function Return object Modifiable data keys Unmodifiable data keys Description
generate() None correct_answers, params extensions, options, variant_seed Generate the parameter and true answers for a new random question variant. Set data["params"][name] and data["correct_answers"][name] for any variables as needed. Return the modified data dictionary.
prepare() None correct_answers, params extensions, options, variant_seed Final question preparation after element code has run. Can modify data as necessary. Return the modified data dictionary.
render() str (html) correct_answers, editable, extensions, feedback, format_errors, manual_grading, num_valid_submissions, options, panel, params, partial_scores, raw_submitted_answers, score, submitted_answers, variant_seed, Render the HTML for one panel and return it as a string.
parse() None correct_answers, feedback, format_errors, submitted_answers extensions, options, params, raw_submitted_answers, variant_seed Parse the data["submitted_answers"][var] data entered by the student, modifying this variable. Return the modified data dictionary.
grade() None correct_answers, feedback, format_errors, params, partial_scores, score, submitted_answers extensions, options, raw_submitted_answers, variant_seed Grade data["submitted_answers"][var] to determine a score. Store the score and any feedback in data["partial_scores"][var]["score"] and data["partial_scores"][var]["feedback"] respectively. Return the modified data dictionary. Note: Avoid modifying the data["feedback"] dictionary, as this is meant to be used by custom questions.
test() None format_errors, partial_scores, raw_submitted_answers, score extensions, gradable, test_type Creates a test submission for this element, used when running tests from the "Settings" panel. Should set a value in data["raw_submitted_answers"][var] and expected score in data["partial_scores"][var] (or data["format_errors"][var] if invalid). The type of input to test is given in data["test_type"], and can be one of correct, incorrect, or invalid.

The above function descriptions describe the typical variables that will be read and modified by each function. However, any function that returns data (i.e., not parse()) is allowed to change any of the modifiable values in data (see above table) and these changes will be persisted to the database. No function is allowed to add or delete keys in data.

Element dependencies

It's likely that your element will depend on certain client-side assets, such as scripts or stylesheets. To keep clean separation of HTML, CSS, and JS, you can place those dependencies in other files. If you depend on libraries like lodash or d3, you can also link to node modules containing these libraries. PrairieLearn will compile a list of all dependencies needed by all elements on a page, deduplicate the dependencies, and ensure they are loaded on the page.

Dependencies are listed in your element's info.json. You can configure them for your element as follows:

{
  "controller": "pl-my-element.py",
  "dependencies": {
    "nodeModulesScripts": ["three/build/three.min.js"],
    "elementScripts": ["pl-my-element.js"],
    "elementStyles": ["pl-my-element.css"],
    "clientFilesCourseStyles": ["courseStylesheet1.css", "courseStylesheet2.css"]
  }
}

The different types of dependency properties currently available are summarized in this table:

Property Description
nodeModulesStyles The styles required by this element, relative to [PrairieLearn directory]/node_modules.
nodeModulesScripts The scripts required by this element, relative to [PrairieLearn directory]/node_modules.
elementStyles The styles required by this element relative to the element's directory, which is either [PrairieLearn directory]/elements/this-element-name or [course directory]/elements/this-element-name.
elementScripts The scripts required by this element relative to the element's directory, which is either [PrairieLearn directory]/elements/this-element-name or [course directory]/elements/this-element-name.
clientFilesCourseStyles The styles required by this element relative to [course directory]/clientFilesCourse. (Note: This property is only available for elements hosted in a specific course's directory, not system-wide PrairieLearn elements.)
clientFilesCourseScripts The scripts required by this element relative to [course directory]/clientFilesCourse. (Note: This property is only available for elements hosted in a specific course's directory, not system-wide PrairieLearn elements.)

The coreScripts and coreStyles properties are used in legacy elements and questions, but are deprecated and should not be used in new objects. It lists scripts and styles required by this element, relative to [PrairieLearn directory]/public/javascripts and [PrairieLearn directory]/public/stylesheets, respectively. Scripts in [PrairieLearn directory]/public/javascripts are mainly used for compatibility with legacy elements and questions, while styles in [PrairieLearn directory]/public/stylesheets are reserved for styles used by specific pages rather than individual elements.

While the use of node module dependencies in course elements is supported, it is recommended that caution be used when doing so. In particular, note that node modules may be updated without warning, which in some cases may break your element. If your code relies on a particular version of a node module, it is recommended that you copy the module into your element directory or courseFilesCourse and link to that module from there instead.

In addition to static dependencies, elements can also declare dynamic dependencies, corresponding to scripts that are loaded only if they are deemed necessary. For example, if an element may use the d3 library, but only in certain cases, it can declare a dependency on d3:

{
  "controller": "pl-my-element.py",
  "dependencies": {
    "elementScripts": ["pl-my-element.js"]
  },
  "dynamicDependencies": {
    "nodeModulesScripts": { "d3": "d3/dist/d3.min.js" }
  }
}

Then, the element's own script (e.g., pl-my-element.js) can dynamically import the d3 library only when considered necessary:

if (options.use_d3) {
  import('d3').then((module) => {
    // use d3 here
  });
}

Dynamic dependencies are implemented using import maps, which allow the import call in the element script to refer to the module by the name defined in the info.json file instead of the full URL. Dynamic dependencies may point to:

Property Description
nodeModulesScripts The scripts required by this element, relative to [PrairieLearn directory]/node_modules.
elementScripts The scripts required by this element relative to the element's directory, which is either [PrairieLearn directory]/elements/this-element-name or [course directory]/elements/this-element-name.
clientFilesCourseScripts The scripts required by this element relative to [course directory]/clientFilesCourse. (Note: This property is only available for elements hosted in a specific course's directory, not system-wide PrairieLearn elements.)

Note that the key used in the dynamic dependencies will be shared among all elements available in a question. For example, if two elements in a question both declare a dynamic dependency on d3, then the d3 library will only be loaded once, even if both elements use it. For this reason, it is important that the following convention is used when defining keys for dynamic dependencies:

  • For node modules: use the name of the module, as defined in the package.json file. This will allow multiple elements that use the same module to share the same dependency without loading the module twice.
  • For element scripts: use the name of the element, followed by a slash, followed by the name of the script. For example, if the element is named pl-my-element and the script is named my-element.js, then the key should be pl-my-element/my-element.js.
  • For clientFilesCourse scripts: use any course-specific convention that does not clash with the naming above.

You can also find the types of dependencies defined in these schema files: