From 51ae86f77155535cefa7f9a82636b8cef77f9469 Mon Sep 17 00:00:00 2001 From: ed eustace Date: Wed, 3 Apr 2019 12:39:10 +0100 Subject: [PATCH] feat(env): add info about `partialScoring` --- site/docs/developing/environment.md | 59 +++++++++++++++++------------ 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/site/docs/developing/environment.md b/site/docs/developing/environment.md index 49404735..b11930aa 100644 --- a/site/docs/developing/environment.md +++ b/site/docs/developing/environment.md @@ -7,44 +7,56 @@ layout: DefaultLayout The environment `env` Object helps to define the current runtime context for PIEs as they are being viewed by a user. Any time this property is updated the [PIE Player](../pie-player.md) will set it on the Custom Element for a PIE. It also will be passed to to the `model` function implemented by a PIE [controller](controller.md). The result of this will be set as the `model` property in the PIE Custom Element. This allows a developer to update or filter the model as neccesary to have the appropriate data available to render the view in the current context. - ## Environment Properties -```json -{ - "view": "gather" | "view" | "evaluate" | "preview", - "role": "student" | "instructor", - "lang": [BCP 47 language tag], - "options": {...} +```javascript + +type Env = { + view: "gather" | "view" | "evaluate" | "preview", + role?: "student" | "instructor", + lang?: [BCP 47 language tag], + options?: any, + partialScoring: boolean = true } + ``` -### Property: `view` +### view The `view` property indicates which view the PIE should render. The following values may be provided: | value | Description | -|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | gather | The PIE should present a view that allows a response to be captured | | evaluate | The PIE should present the response in a way that provides an evaluation of the response provided by a user | | view | The PIE should present a response with no inflection, and without allowing modification of the response. | | preview | The PIE should present the interaction for a user who is finding questions/interactions to use. For example an instructor previewing questions before including them in a test. | +### role -### Property: `role` - -Indicates the role of the current user viewing the PIE. +Indicates the role of the current user viewing the PIE. Possible values are `instructor` and `student` It is up to the PIE developer to determine what to do with these properties. For example a PIE might present the `evaluate` view differently to a user with role `student` or `instructor`, but may not have any difference in presentation for roles when the view is `gather`. -### Property: `lang` +### lang -For localisation, the `lang` property informs the PIE of the primary language setting for the user. +For localisation, the `lang` property informs the PIE of the primary language setting for the user. The values will be [BCP 47](https://www.w3.org/International/articles/language-tags/) tags like `en_US` +### partialScoring + +Some pies support `partialScoring` - if disabled the score will only ever be 0 when incorrect and 1 when correct. -### Property: `options` +When enabled the pie will score between 0 and 1 if the response is partially correct. + +`partialScoring` is enabled by default. It can be disabled by setting `partialScoring: false` within a pie's model. + +`env.partialScoring` allows you to override the flag within a pie. It will take precedence over any flag set within a pie's model. + +> Dev Note: Currently this is implemented in the controllers of the pies, there may be a case for moving it elsewhere? + +### options ### Reserved `options` Properties @@ -53,7 +65,7 @@ The following properties are reserved properties that can be passed in the `opti They are used to enable/disable and configure certain features that may be available in the assessment item. | Property | Property Type | Summary | -|--------------------|---------------|----------------------------------------------| +| ------------------ | ------------- | -------------------------------------------- | | calculator | Object | Calculator Tool, basic and advanced | | notepad | Boolean | Note taking tool | | ruler | Boolean | Ruler Tool | @@ -72,7 +84,6 @@ They are used to enable/disable and configure certain features that may be avail | closedCaptioning | String | Provide closed captioning for media | | strikeThrough | Boolean | Provide ability to strike-through options | - > BETA Release Note: full specification of these properties will be documented in upcoming releases of PIE framework ### Custom `options` Properties @@ -82,11 +93,11 @@ PIEs that need to allow for configuration options to be added when rendering the By convention, these properties should be scoped by organization name, e.g. ```json -{ - "options":{ - "corespring": { - "myCustomOption": "someValue" - } - } +{ + "options": { + "corespring": { + "myCustomOption": "someValue" + } + } } -``` \ No newline at end of file +```