You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Modification of `baseURL` may be necessary to separate multiple services running on `SITE_HOST`, and will be used to extend `SITE_HOST`. The result of this extension will serve as the root URL for accessing the renderer (and any supplementary assets it may need to provide in support of a rendered problem). If `baseURL` is an absolute URL, it will be used verbatim -- userful if the renderer is running behind a load balancer.
78
+
79
+
By default, `formURL` will further extend `baseURL`, and serve as the form-data target for user interactions with problems rendered by this service. If `formURL` is an absolute URL, it will be used verbatim -- useful if your implementation intends to sit in between the user and the renderer.
80
+
73
81
## Renderer API
74
82
75
-
Can be interfaced through `/render-api`
76
-
77
-
## Parameters
78
-
79
-
| Key | Type | Default Value | Required | Description | Notes |
| problemSourceURL | string | null | true if `sourceFilePath` and `problemSource` are null | The URL from which to fetch the problem source code | Takes precedence over `problemSource` and `sourceFilePath`. A request to this URL is expected to return valid pg source code in base64 encoding. |
82
-
| problemSource | string (base64 encoded) | null | true if `problemSourceURL` and `sourceFilePath` are null | The source code of a problem to be rendered | Takes precedence over `sourceFilePath`. |
83
-
| sourceFilePath | string | null | true if `problemSource` and `problemSourceURL` are null | The path to the file that contains the problem source code | Can begin with Library/ or Contrib/, in which case the renderer will automatically adjust the path relative to the webwork-open-problem-library root. Path may also begin with `private/` for local, non-OPL content. |
84
-
| problemSeed | number | NA | true | The seed to determine the randomization of a problem ||
85
-
| psvn | number | 123 | false | used for consistent randomization between problems ||
86
-
| formURL | string | /render-api | false | the URL for form submission ||
87
-
| baseURL | string | / | false | the URL for relative paths ||
88
-
| format | string | '' | false | Determine how the response is formatted ('html' or 'json') ||
89
-
| outputFormat | string (enum) | static | false | Determines how the problem should render, see below descriptions below ||
90
-
| language | string | en | false | Language to render the problem in (if supported) ||
91
-
| showHints | number (boolean) | 1 | false | Whether or not to show hints ||
92
-
| showSolutions | number (boolean) | 0 | false | Whether or not to show the solutions ||
93
-
| permissionLevel | number | 0 | false | Deprecated. See below. |
94
-
| isInstructor | number (boolean) | 0 | false | Is the user viewing the problem an instructor or not. | Used by PG to determine if scaffolds can be allowed to be open among other things |
95
-
| problemNumber | number | 1 | false | We don't use this ||
96
-
| numCorrect | number | 0 | false | The number of correct attempts on a problem ||
97
-
| numIncorrect | number | 1000 | false | The number of incorrect attempts on this problem ||
98
-
| processAnswers | number (boolean) | 1 | false | Determines whether or not answer json is populated, and whether or not problem_result and problem_state are non-empty ||
99
-
| answersSubmitted | number (boolean) | ? | false? | Determines whether to process form-data associated to the available input fields ||
100
-
| showSummary | number (boolean) | ? | false? | Determines whether or not to show the summary result of processing the form-data associated with `answersSubmitted` above ||
101
-
| showComments | number (boolean) | 0 | false | Renders author comment field at the end of the problem ||
102
-
| includeTags | number (boolean) | 0 | false | Includes problem tags in the returned JSON | Only relevant when requesting `format: 'json'`|
103
-
104
-
## Output Format
105
-
106
-
| Key | Description |
107
-
| ----- | ----- |
108
-
| static | zero buttons, locked form fields (read-only) |
109
-
| nosubmit | zero buttons, editable (for exams, save problem state and submit all together) |
110
-
| single | one submit button (intended for graded content) |
| practice | check answers + show answers buttons |
114
-
115
-
## Permission level
116
-
117
-
| Key | Value |
118
-
| --- | ----- |
119
-
| student | 0 |
120
-
| prof | 10 |
121
-
| admin | 20 |
122
-
123
-
## Permission logic summary
124
-
125
-
*`permissionLevel` is ignored if `isInstructor` is directly set.
126
-
* If `permissionLevel >= 10`, then `isInstructor` will be set to true.
127
-
* If `permissionLevel < 10`, then `isInstructor` will be set to false.
128
-
*`permissionLevel` is not used to determine if hints or solutions are shown.
83
+
Can be accessed by POST to `{SITE_HOST}{baseURL}{formURL}`.
84
+
85
+
By default, `localhost:3000/render-api`.
86
+
87
+
### **REQUIRED PARAMETERS**
88
+
89
+
The bare minimum of parameters that must be included are:
90
+
* the code for the problem, so, **ONE** of the following (in order of precedence):
91
+
*`problemSource` (raw pg source code, _can_ be base64 encoded)
92
+
*`sourceFilePath` (relative to OPL `Library/`, `Contrib/`; or in `private/`)
93
+
*`problemSourceURL` (fetch the pg source from remote server)
94
+
* a "seed" value for consistent randomization
95
+
*`problemSeed` (integer)
96
+
97
+
| Key | Type | Description | Notes |
98
+
| --- | ---- | ----------- | ----- |
99
+
| problemSource | string (possibly base64 encoded) | The source code of a problem to be rendered | Takes precedence over `sourceFilePath`. |
100
+
| sourceFilePath | string | The path to the file that contains the problem source code | Renderer will automatically adjust `Library/` and `Contrib/` relative to the webwork-open-problem-library root. Path may also begin with `private/` for local, non-OPL content. |
101
+
| problemSourceURL | string | The URL from which to fetch the problem source code | Takes precedence over `problemSource` and `sourceFilePath`. A request to this URL is expected to return valid pg source code in base64 encoding. |
102
+
| problemSeed | number | The seed that determines the randomization of a problem ||
103
+
104
+
**ALL** other request parameters are optional.
105
+
106
+
### Infrastructure Parameters
107
+
108
+
The defaults for these parameters are set in `render_app.conf`, but these can be overridden on a per-request basis.
109
+
110
+
| Key | Type | Default Value | Description | Notes |
| language | string | en | Language to render the problem in (if supported) | affects the translation of template strings, _not_ actual problem content |
124
+
|_format | string | 'html' | Determine how the response is _structured_ ('html' or 'json') | usually 'html' if the user is directly interacting with the renderer, 'json' if your CMS sits between user and renderer |
125
+
| outputFormat | string | 'default' | Determines how the problem should be formatted | 'default', 'static', 'PTX', 'raw', or |
126
+
| displayMode | string | 'MathJax' | How to prepare math content for display | 'MathJax' or 'ptx' |
127
+
128
+
#### User Interactions
129
+
130
+
Control how the user is allowed to interact with the rendered problem.
131
+
132
+
Requesting `outputFormat: 'static'` will prevent any buttons from being included in the rendered output, regardless of the following options.
133
+
134
+
| Key | Type | Default Value | Description | Notes |
| hidePreviewButton | number (boolean) | false | "Preview My Answers" is enabled by default ||
137
+
| hideCheckAnswersButton | number (boolean) | false | "Submit Answers" is enabled by default ||
138
+
| showCorrectAnswersButton | number (boolean) |`isInstructor`| "Show Correct Answers" is disabled by default, enabled if `isInstructor` is true (see below) ||
139
+
140
+
#### Content
141
+
142
+
Control what is shown to the user: hints, solutions, attempt results, scores, etc.
143
+
144
+
| Key | Type | Default Value | Description | Notes |
| permissionLevel | number | 0 |**DEPRECATED.** Use `isInstructor` instead. |
147
+
| isInstructor | number (boolean) | 0 | Is the user viewing the problem an instructor or not. | Used by PG to determine if scaffolds can be allowed to be open among other things |
148
+
| showHints | number (boolean) | 1 | Whether or not to show hints ||
149
+
| showSolutions | number (boolean) |`isInstructor`| Whether or not to show the solutions ||
150
+
| hideAttemptsTable | number (boolean) | 0 | Hide the table of answer previews/results/messages | If you have a replacement for flagging the submitted entries as correct/incorrect |
151
+
| showSummary | number (boolean) | 1 | Determines whether or not to show a summary of the attempt underneath the table | Only relevant if the Attempts Table is shown `hideAttemptsTable: false` (default) |
152
+
| showComments | number (boolean) | 0 | Renders author comment field at the end of the problem ||
153
+
| showFooter | number (boolean) | 0 | Show version information and WeBWorK copyright footer ||
154
+
| includeTags | number (boolean) | 0 | Includes problem tags in the returned JSON | Only relevant when requesting `_format: 'json'`|
155
+
156
+
## Using JWTs
157
+
158
+
There are three JWT structures that the Renderer uses, each containing its predecessor:
159
+
* problemJWT
160
+
* sessionJWT
161
+
* answerJWT
162
+
163
+
### ProblemJWT
164
+
165
+
This JWT encapsulates the request parameters described above, under the API heading. Any value set in the JWT cannot be overridden by form-data. For example, if the problemJWT includes `isInstructor: 0`, then any subsequent interaction with the problem rendered by this JWT cannot override this setting by including `isInstructor: 1` in the form-data.
166
+
167
+
### SessionJWT
168
+
169
+
This JWT encapsulates a user's attempt on a problem, including:
170
+
* the text and LaTeX versions of each answer entry
171
+
* count of incorrect attempts (stopping after a correct attempt, or after `showCorrectAnswers` is used)
172
+
* the problemJWT
173
+
174
+
If stored (see next), this JWT can be submitted as the sole request parameter, and the response will effectively restore the users current state of interaction with the problem (as of their last submission).
175
+
176
+
### AnswerJWT
177
+
178
+
If the initial problemJWT contains a value for `JWTanswerURL`, this JWT will be generated and sent to the specified URL. The answerJWT is the only content provided to the URL. The renderer is intended to to be user-agnostic. It is recommended that the JWTanswerURL specify the unique identifier for the user/problem combination. (e.g. `JWTanswerURL: 'https://db.yoursite.org/grades-api/:user_problem_id'`)
179
+
180
+
For security purposes, this parameter is only accepted when included as part of a JWT.
181
+
182
+
This JWT encapsulates the status of the user's interaction with the problem.
183
+
* score
184
+
* sessionJWT
185
+
186
+
The goal here is to update the `JWTanswerURL` with the score and "state" for the user. If you have uses for additional information, please feel free to suggest as a GitHub Issue.
0 commit comments