Skip to content

feat(env): add info about partialScoring #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
edeustace wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(env): add info about partialScoring #14

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 35 additions & 24 deletions site/docs/developing/environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 |
Expand All @@ -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
Expand All @@ -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"
}
}
}
```
```