Dockerfile and documentation update

squash

Dockerfile

@@ -55,7 +55,7 @@ RUN cp render_app.conf.dist render_app.conf
 
 RUN cp conf/pg_config.yml lib/PG/conf/pg_config.yml
 
-RUN npm install
+RUN cd public/ && npm install && cd ..
 
 RUN cd lib/PG/htdocs && npm install && cd ../../..
 

README.md

@@ -51,7 +51,9 @@ If using a local install instead of docker:
 * copy `render_app.conf.dist` to `render_app.conf` and make any desired modifications
 * copy `conf/pg_config.yml` to `lib/PG/pg_config.yml` and make any desired modifications
 * install third party JavaScript dependencies
+  * `cd private/`
   * `npm install`
+  * `cd ..`
 * install PG JavaScript dependencies
   * `cd lib/PG/htdocs`
   * `npm install`
@@ -70,59 +72,115 @@ If using a local install instead of docker:
 
 ![image](https://user-images.githubusercontent.com/3385756/129100124-72270558-376d-4265-afe2-73b5c9a829af.png)
 
+## Server Configuration
+
+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.
+
+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. 
+
 ## Renderer API
 
-Can be interfaced through `/render-api`
-
-## Parameters
-
-| 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. |
-| 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`. |
-| 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. |
-| problemSeed | number | NA | true | The seed to determine the randomization of a problem | |
-| psvn | number | 123 | false | used for consistent randomization between problems | |
-| formURL | string | /render-api | false | the URL for form submission | |
-| baseURL | string | / | false | the URL for relative paths | |
-| format | string | '' | false | Determine how the response is formatted ('html' or 'json') ||
-| outputFormat | string (enum) | static | false | Determines how the problem should render, see below descriptions below | |
-| language | string | en | false | Language to render the problem in (if supported) | |
-| showHints | number (boolean) | 1 | false | Whether or not to show hints | |
-| showSolutions | number (boolean) | 0 | false | Whether or not to show the solutions | |
-| permissionLevel | number | 0 | false | Deprecated.  See below. |
-| 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 |
-| problemNumber | number | 1 | false | We don't use this | |
-| numCorrect | number | 0 | false | The number of correct attempts on a problem | |
-| numIncorrect | number | 1000 | false | The number of incorrect attempts on this problem | |
-| 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 | |
-| answersSubmitted | number (boolean) | ? | false? | Determines whether to process form-data associated to the available input fields | |
-| showSummary | number (boolean) | ? | false? | Determines whether or not to show the summary result of processing the form-data associated with `answersSubmitted` above ||
-| showComments | number (boolean) | 0 | false | Renders author comment field at the end of the problem ||
-| includeTags | number (boolean) | 0 | false | Includes problem tags in the returned JSON | Only relevant when requesting `format: 'json'` |
-
-## Output Format
-
-| Key | Description |
-| ----- | ----- |
-| static | zero buttons, locked form fields (read-only) |
-| nosubmit | zero buttons, editable (for exams, save problem state and submit all together) |
-| single | one submit button (intended for graded content) |
-| classic | preview + submit buttons |
-| simple | preview + submit + show answers buttons |
-| practice | check answers + show answers buttons |
-
-## Permission level
-
-| Key | Value |
-| --- | ----- |
-| student | 0 |
-| prof | 10 |
-| admin | 20 |
-
-## Permission logic summary
-
-* `permissionLevel` is ignored if `isInstructor` is directly set.
-* If `permissionLevel >= 10`, then `isInstructor` will be set to true.
-* If `permissionLevel < 10`, then `isInstructor` will be set to false.
-* `permissionLevel` is not used to determine if hints or solutions are shown.
+Can be accessed by POST to `{SITE_HOST}{baseURL}{formURL}`. 
+
+By default, `localhost:3000/render-api`.
+
+### **REQUIRED PARAMETERS**
+
+The bare minimum of parameters that must be included are:
+* the code for the problem, so, **ONE** of the following (in order of precedence):
+  * `problemSource` (raw pg source code, _can_ be base64 encoded)
+  * `sourceFilePath` (relative to OPL `Library/`, `Contrib/`; or in `private/`)
+  * `problemSourceURL` (fetch the pg source from remote server)
+* a "seed" value for consistent randomization
+  * `problemSeed` (integer)
+
+| Key | Type | Description | Notes |
+| --- | ---- | ----------- | ----- |
+| problemSource | string (possibly base64 encoded) | The source code of a problem to be rendered | Takes precedence over `sourceFilePath`. |
+| 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. |
+| 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. |
+| problemSeed | number | The seed that determines the randomization of a problem | |
+
+**ALL** other request parameters are optional.
+
+### Infrastructure Parameters
+
+The defaults for these parameters are set in `render_app.conf`, but these can be overridden on a per-request basis.
+
+| Key | Type | Default Value | Description | Notes |
+| --- | ---- | ------------- | ----------- | ----- |
+| baseURL | string | '/' (as set in `render_app.conf`) | the URL for relative paths | |
+| formURL | string | '/render-api' (as set in `render_app.conf`) | the URL for form submission | |
+
+### Display Parameters
+
+#### Formatting
+
+Parameters that control the structure and templating of the response.
+
+| 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 |
+| _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 |
+| outputFormat | string | 'default' | Determines how the problem should be formatted | 'default', 'static', 'PTX', 'raw', or  |
+| displayMode | string | 'MathJax' | How to prepare math content for display | 'MathJax' or 'ptx' |
+
+#### User Interactions
+
+Control how the user is allowed to interact with the rendered problem.
+
+Requesting `outputFormat: 'static'` will prevent any buttons from being included in the rendered output, regardless of the following options.
+
+| Key | Type | Default Value | Description | Notes |
+| --- | ---- | ------------- | ----------- | ----- |
+| hidePreviewButton | number (boolean) | false | "Preview My Answers" is enabled by default | |
+| hideCheckAnswersButton | number (boolean) | false | "Submit Answers" is enabled by default | |
+| showCorrectAnswersButton | number (boolean) | `isInstructor` | "Show Correct Answers" is disabled by default, enabled if `isInstructor` is true (see below) | |
+
+#### Content
+
+Control what is shown to the user: hints, solutions, attempt results, scores, etc.
+
+| Key | Type | Default Value | Description | Notes |
+| --- | ---- | ------------- | ----------- | ----- |
+| permissionLevel | number | 0 | **DEPRECATED.** Use `isInstructor` instead. |
+| 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 |
+| showHints | number (boolean) | 1 | Whether or not to show hints | |
+| showSolutions | number (boolean) | `isInstructor` | Whether or not to show the solutions | |
+| 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 |
+| 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) |
+| showComments | number (boolean) | 0 | Renders author comment field at the end of the problem | |
+| showFooter | number (boolean) | 0 | Show version information and WeBWorK copyright footer | |
+| includeTags | number (boolean) | 0 | Includes problem tags in the returned JSON | Only relevant when requesting `_format: 'json'` |
+
+## Using JWTs
+
+There are three JWT structures that the Renderer uses, each containing its predecessor:
+* problemJWT
+* sessionJWT
+* answerJWT
+
+### ProblemJWT
+
+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. 
+
+### SessionJWT
+
+This JWT encapsulates a user's attempt on a problem, including:
+* the text and LaTeX versions of each answer entry
+* count of incorrect attempts (stopping after a correct attempt, or after `showCorrectAnswers` is used)
+* the problemJWT
+
+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). 
+
+### AnswerJWT
+
+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'`)
+
+For security purposes, this parameter is only accepted when included as part of a JWT.
+
+This JWT encapsulates the status of the user's interaction with the problem.
+* score
+* sessionJWT
+
+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. 

conf/pg_config.yml

@@ -40,6 +40,7 @@ directories:
   #  (in this order) by loadMacros when it looks for a .pl macro file.
   macrosPath:
     - .
+    - $render_root/private/macros
     - $pg_root/macros
     - $pg_root/macros/answers
     - $pg_root/macros/capa
@@ -182,9 +183,6 @@ options:
   # This is the operations file to use for mathview, each contains a different locale.
   mathViewLocale: mv_locale_us.js
 
-  # Set to 1 to show the WirisEditor preview system.
-  useWirisEditor: 0
-
   # Catch translation warnings internally.
   catchWarnings: 1
 

lib/WeBWorK/FormatRenderedProblem.pm

@@ -49,8 +49,8 @@ sub formatRenderedProblem {
 		$renderErrorOccurred                = 1;
 	}
 
-	my $SITE_URL        = $ENV{baseURL};
-	my $FORM_ACTION_URL = $ENV{formURL}; 
+	my $SITE_URL        = $inputs_ref->{baseURL};
+	my $FORM_ACTION_URL = $inputs_ref->{formURL}; 
 
 	my $displayMode = $inputs_ref->{displayMode} // 'MathJax';
 
@@ -106,8 +106,7 @@ sub formatRenderedProblem {
 	# Get the requested format. (outputFormat or outputformat)
 	# override to static mode if showCorrectAnswers has been set
 	my $formatName = $inputs_ref->{showCorrectAnswers} && !$inputs_ref->{isInstructor}
-		? 'static'
-		: $inputs_ref->{outputFormat} // $inputs_ref->{outputformat} // 'default';
+		? 'static' : $inputs_ref->{outputFormat};
 
 	# Add JS files requested by problems via ADD_JS_FILE() in the PG file.
 	my @extra_js_files;
@@ -248,8 +247,8 @@ sub formatRenderedProblem {
 		answerTemplate           => $answerTemplate,
 		showScoreSummary         => $submitMode && !$renderErrorOccurred && !$previewMode && $problemResult,
 		answerhashXML            => $answerhashXML,
-		showPreviewButton        => $inputs_ref->{showPreviewButton}        // '',
-		showCheckAnswersButton   => $inputs_ref->{showCheckAnswersButton}   // '',
+		showPreviewButton        => $inputs_ref->{hidePreviewButton}        ? '' : 0,
+		showCheckAnswersButton   => $inputs_ref->{hideCheckAnswersButton}   ? '' : 0,
 		showCorrectAnswersButton => $inputs_ref->{showCorrectAnswersButton} // $inputs_ref->{isInstructor} ? '' : '0',
 		showFooter               => $inputs_ref->{showFooter}               // '0',
 		pretty_print             => \&pretty_print,

lib/WeBWorK/RenderProblem.pm

@@ -80,7 +80,7 @@ sub process_pg_file {
 
     # just make sure we have the fundamentals covered...
     $inputs_ref->{displayMode}    ||= 'MathJax';
-    $inputs_ref->{outputFormat}   ||= 'static';
+    $inputs_ref->{outputFormat}   ||= $inputs_ref->{outputformat} || 'default';
     $inputs_ref->{language}       ||= 'en';
     $inputs_ref->{isInstructor}   //= ($inputs_ref->{permissionLevel} // 0) >= 10;
     # HACK: required for problemRandomize.pl
@@ -235,7 +235,7 @@ sub standaloneRenderer {
 		problemSeed          => $inputs_ref->{problemSeed},
 		processAnswers       => $processAnswers,
 		showHints            => $inputs_ref->{showHints},              # default is to showHint (set in PG.pm)
-		showSolutions        => $inputs_ref->{showSolutions},
+		showSolutions        => $inputs_ref->{showSolutions} // $inputs_ref->{isInstructor} ? 1 : 0,
 		problemNumber        => $inputs_ref->{problemNumber},          # ever even relevant?
 		num_of_correct_ans   => $inputs_ref->{numCorrect} || 0,
 		num_of_incorrect_ans => $inputs_ref->{numIncorrect} || 0,
@@ -356,7 +356,7 @@ sub generateJWTs {
       iss        => $ENV{SITE_HOST},
       aud        => $inputs_ref->{JWTanswerURL},
       score      => $scoreHash,
-      problemJWT => $inputs_ref->{problemJWT},
+    #   problemJWT => $inputs_ref->{problemJWT},
       sessionJWT => $sessionJWT,
       platform   => 'standaloneRenderer'
     };