further improvements to structure

README.md

@@ -50,61 +50,80 @@ The attributes listed below are used in *config.json* to configure **Spoor**, an
 
 ## Attributes
 
-### **\_spoor** (object): 
+### \_spoor (object): 
 
 The `_spoor` object contains the setting `_isEnabled` and the `_tracking`, `_reporting` and `_advancedSettings` objects.
-
-> **\_isEnabled** (boolean): Enables/disables this extension. If set to `true` (the default value), the plugin will try to connect to a SCORM conformant LMS when the course is launched via *index_lms.html*. If one is not available, a 'Could not connect to LMS' error message will be displayed. This error can be avoided during course development either by setting this to `false` or - more easily - by launching the course via *index.html*. This latter technique is also useful if you are developing a course that could be run either from an LMS or a regular web server.  
 
-#### **\_tracking** (object): 
+##### \_isEnabled (boolean):
+Enables/disables this extension. If set to `true` (the default value), the plugin will try to connect to a SCORM conformant LMS when the course is launched via *index_lms.html*. If one is not available, a 'Could not connect to LMS' error message will be displayed. This error can be avoided during course development either by setting this to `false` or - more easily - by launching the course via *index.html*. This latter technique is also useful if you are developing a course that could be run either from an LMS or a regular web server.  
 
-This object defines what kinds of data to record to the LMS. It consists of the following settings:
+#### \_tracking (object): 
 
->**\_shouldSubmitScore** (boolean): Determines whether the assessment score will be reported to the LMS. Note that SCORM only supports one score per SCO, so if you have multiple assessments within your course, one aggregated score will be recorded. Acceptable values are `true` or `false`. The default is `false`.  
+This object defines what kinds of data to record to the LMS. It consists of the following settings:
 
->**\_shouldStoreResponses** (boolean): Determines whether the user's responses to questions should be persisted across sessions (by storing them in `cmi.suspend_data`) or not. Acceptable values are `true` or `false`. The default is `true`. Note that if you set this to `true`, the user will not be able to attempt questions within the course again unless some mechanism for resetting them is made available (for example, see `_isResetOnRevisit` in [adapt-contrib-assessment](https://github.com/adaptlearning/adapt-contrib-assessment)).
+##### \_shouldSubmitScore (boolean):
+Determines whether the assessment score will be reported to the LMS. Note that SCORM only supports one score per SCO, so if you have multiple assessments within your course, one aggregated score will be recorded. Acceptable values are `true` or `false`. The default is `false`.  
 
->**\_shouldStoreAttempts** (boolean): Determines whether the history of the user's responses to questions should be persisted across sessions (by storing them in `cmi.suspend_data`) or not. Acceptable values are `true` or `false`. The default is `false`.
+##### \_shouldStoreResponses (boolean):
+Determines whether the user's responses to questions should be persisted across sessions (by storing them in `cmi.suspend_data`) or not. Acceptable values are `true` or `false`. The default is `true`. Note that if you set this to `true`, the user will not be able to attempt questions within the course again unless some mechanism for resetting them is made available (for example, see `_isResetOnRevisit` in [adapt-contrib-assessment](https://github.com/adaptlearning/adapt-contrib-assessment)).
 
->**\_shouldRecordInteractions** (boolean): Determines whether the user's responses to questions should be tracked to  the `cmi.interactions` fields of the SCORM data model or not. Acceptable values are `true` or `false`. The default is `true`. Note that not all SCORM 1.2 conformant Learning Management Systems support `cmi.interactions`. The code will attempt to detect whether support is implemented or not and, if not, will fail gracefully. Occasionally the code is unable to detect when `cmi.interactions` are not supported, in those (rare) instances you can switch off interaction tracking using this property so as to avoid 'not supported' errors. You can also switch off interaction tracking for any individual question using the `_recordInteraction` property of question components. All core question components support recording of interactions, community components will not necessarily do so.
+##### \_shouldStoreAttempts (boolean):
+Determines whether the history of the user's responses to questions should be persisted across sessions (by storing them in `cmi.suspend_data`) or not. Acceptable values are `true` or `false`. The default is `false`.
 
-#### **\_reporting** (object): 
+##### \_shouldRecordInteractions (boolean):
+Determines whether the user's responses to questions should be tracked to  the `cmi.interactions` fields of the SCORM data model or not. Acceptable values are `true` or `false`. The default is `true`. Note that not all SCORM 1.2 conformant Learning Management Systems support `cmi.interactions`. The code will attempt to detect whether support is implemented or not and, if not, will fail gracefully. Occasionally the code is unable to detect when `cmi.interactions` are not supported, in those (rare) instances you can switch off interaction tracking using this property so as to avoid 'not supported' errors. You can also switch off interaction tracking for any individual question using the `_recordInteraction` property of question components. All core question components support recording of interactions, community components will not necessarily do so.
 
+#### \_reporting (object):
 This object defines what status to report back to the LMS. It consists of the following settings:
 
->**\_onTrackingCriteriaMet** (string): Specifies the status that is reported to the LMS when the tracking criteria (as defined in the `_completionCriteria` object in config.json) are met. Acceptable values are: `"completed"`, `"passed"`, `"failed"`, and `"incomplete"`. If you are tracking a course by assessment, you would typically set this to `"passed"`. Otherwise, `"completed"` is the usual value.
+##### \_onTrackingCriteriaMet (string):
+Specifies the status that is reported to the LMS when the tracking criteria (as defined in the `_completionCriteria` object in config.json) are met. Acceptable values are: `"completed"`, `"passed"`, `"failed"`, and `"incomplete"`. If you are tracking a course by assessment, you would typically set this to `"passed"`. Otherwise, `"completed"` is the usual value.
 
->**\_onAssessmentFailure** (string): Specifies the status that is reported to the LMS when the assessment is failed. Acceptable values are `"failed"` and `"incomplete"`. Some Learning Management Systems will prevent the user from making further attempts at the course after status has been set to `"failed"`. Therefore, it is common to set this to `"incomplete"` to allow the user more attempts to pass an assessment.  
+##### \_onAssessmentFailure (string):
+Specifies the status that is reported to the LMS when the assessment is failed. Acceptable values are `"failed"` and `"incomplete"`. Some Learning Management Systems will prevent the user from making further attempts at the course after status has been set to `"failed"`. Therefore, it is common to set this to `"incomplete"` to allow the user more attempts to pass an assessment.  
 
->**\_resetStatusOnLanguageChange** (boolean): If set to `true` the status of the course is set to "incomplete" when the languge is changed using the [adapt-contrib-languagePicker plugin](https://github.com/adaptlearning/adapt-contrib-languagepicker). Acceptable values are `true` or `false`. The default is `false`.  
+##### \_resetStatusOnLanguageChange (boolean):
+If set to `true` the status of the course is set to "incomplete" when the languge is changed using the [adapt-contrib-languagePicker plugin](https://github.com/adaptlearning/adapt-contrib-languagepicker). Acceptable values are `true` or `false`. The default is `false`.  
 
-#### **\_advancedSettings** (object): 
+#### \_advancedSettings (object): 
 
 The advanced settings objects contains the following settings. Note that you only need to include advanced settings if you want to change any of the following settings from their default values - and you only need to include those settings you want to change.
 
->**\_scormVersion** (string): This property defines what version of SCORM is targeted. Only SCORM 1.2 is officially supported by Adapt. SCORM 2004 should work, but the Adapt team don't include this version in testing. To enable SCORM 2004 support, change this value to `"2004"` and include the relevant SCORM 2004 packaging files (*imsmanifest.xml* and others - you can find examples over at [scorm.com](http://scorm.com/scorm-explained/technical-scorm/content-packaging/xml-schema-definition-files/)). The default is `"1.2"`.  
+##### \_scormVersion (string):
+This property defines what version of SCORM is targeted. Only SCORM 1.2 is officially supported by Adapt. SCORM 2004 should work, but the Adapt team don't include this version in testing. To enable SCORM 2004 support, change this value to `"2004"` and include the relevant SCORM 2004 packaging files (*imsmanifest.xml* and others - you can find examples over at [scorm.com](http://scorm.com/scorm-explained/technical-scorm/content-packaging/xml-schema-definition-files/)). The default is `"1.2"`.  
 
->**\_showDebugWindow** (boolean): If set to `true`, a pop-up window will be shown on course launch that gives detailed information about what SCORM calls are being made. This can be very useful for debugging SCORM issues. Note that this pop-up window will appear automatically if the SCORM code encounters an error, even if this is set to `false`. You can also hold down the keys <kbd>d</kbd>+<kbd>e</kbd>+<kbd>v</kbd> to force the popup window to open. The default is `false`. 
+##### \_showDebugWindow (boolean):
+If set to `true`, a pop-up window will be shown on course launch that gives detailed information about what SCORM calls are being made. This can be very useful for debugging SCORM issues. Note that this pop-up window will appear automatically if the SCORM code encounters an error, even if this is set to `false`. You can also hold down the keys <kbd>d</kbd>+<kbd>e</kbd>+<kbd>v</kbd> to force the popup window to open. The default is `false`. 
 
->**\_suppressErrors** (boolean): If set to `true`, an alert dialog will NOT be shown when a SCORM error occurs. Errors will still be logged but the user will not be informed that a problem has occurred. Note that setting `_showDebugWindow` to `true` will still cause the debug popup window to be shown on course launch, this setting merely suppresses the alert dialog that would normally be shown when a SCORM error occurs. *This setting should be used with extreme caution as, if enabled, users will not be told about any LMS connectivity issues or other SCORM tracking problems.*
+##### \_suppressErrors (boolean):
+If set to `true`, an alert dialog will NOT be shown when a SCORM error occurs. Errors will still be logged but the user will not be informed that a problem has occurred. Note that setting `_showDebugWindow` to `true` will still cause the debug popup window to be shown on course launch, this setting merely suppresses the alert dialog that would normally be shown when a SCORM error occurs. *This setting should be used with extreme caution as, if enabled, users will not be told about any LMS connectivity issues or other SCORM tracking problems.*
 
->**\_commitOnStatusChange** (boolean): Determines whether a "commit" call should be made automatically every time the SCORM *lesson_status* is changed. The default is `true`.  
+##### \_commitOnStatusChange (boolean):
+Determines whether a "commit" call should be made automatically every time the SCORM *lesson_status* is changed. The default is `true`.  
 
->**\_commitOnAnyChange** (boolean): Determines whether a "commit" call should be made automatically _every time_ any SCORM value is changed. The default is `false`. Setting `_commitOnAnyChange` to `true` will disable 'timed commits'. **Note:** enabling this setting will make the course generate a lot more client-server traffic so you should only enable it if you are sure it is needed and, as it may have a detrimental impact on server performance, after careful load-testing. An alternative might be to first try setting a lower value for `_timedCommitFrequency`.
+##### \_commitOnAnyChange (boolean):
+Determines whether a "commit" call should be made automatically _every time_ any SCORM value is changed. The default is `false`. Setting `_commitOnAnyChange` to `true` will disable 'timed commits'. **Note:** enabling this setting will make the course generate a lot more client-server traffic so you should only enable it if you are sure it is needed and, as it may have a detrimental impact on server performance, after careful load-testing. An alternative might be to first try setting a lower value for `_timedCommitFrequency`.
 
->**\_timedCommitFrequency** (number): Specifies the frequency - in minutes - at which a "commit" call will be made. Set this value to `0` to disable automatic commits. The default is `10`.  
+##### \_timedCommitFrequency (number):
+Specifies the frequency - in minutes - at which a "commit" call will be made. Set this value to `0` to disable automatic commits. The default is `10`.  
 
->**\_maxCommitRetries** (number): If a "commit" call fails, this setting specifies how many more times the "commit" call will be attempted before giving up and throwing an error. The default is `5`.  
+##### \_maxCommitRetries (number):
+If a "commit" call fails, this setting specifies how many more times the "commit" call will be attempted before giving up and throwing an error. The default is `5`.  
 
->**\_commitRetryDelay** (number): Specifies the interval in milliseconds between commit retries. The default is `2000`.
+##### \_commitRetryDelay (number):
+Specifies the interval in milliseconds between commit retries. The default is `2000`.
 
->**\_commitOnVisibilityChangeHidden** (boolean): Determines whether or not a "commit" call should be made when the [visibilityState](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilityState) of the course page changes to `"hidden"`. This functionality helps to ensure that tracking data is saved whenever the user switches to another tab or minimises the browser window - and is only available in [browsers that support the Page Visibility API](http://caniuse.com/#search=page%20visibility). The default is `true`.
+##### \_commitOnVisibilityChangeHidden (boolean):
+Determines whether or not a "commit" call should be made when the [visibilityState](https://developer.mozilla.org/en-US/docs/Web/API/Document/visibilityState) of the course page changes to `"hidden"`. This functionality helps to ensure that tracking data is saved whenever the user switches to another tab or minimises the browser window - and is only available in [browsers that support the Page Visibility API](http://caniuse.com/#search=page%20visibility). The default is `true`.
 
->**\_manifestIdentifier** (string): Used to set the `identifier` attribute of the `<manifest>` node in imsmanifest.xml - should you want to set it to something other than the default value of `"adapt_manifest"`. Strictly speaking, this value is meant to be unique for each SCO on the LMS; in practice, few LMSes require or enforce this.
+##### \_manifestIdentifier (string):
+Used to set the `identifier` attribute of the `<manifest>` node in imsmanifest.xml - should you want to set it to something other than the default value of `"adapt_manifest"`. Strictly speaking, this value is meant to be unique for each SCO on the LMS; in practice, few LMSes require or enforce this.
 
->**\_exitStateIfIncomplete** (string): Determines the 'exit state' (`cmi.core.exit` in SCORM 1.2, `cmi.exit` in SCORM 2004) to set if the course hasn't been completed. The default behaviour will cause the exit state to be set to an empty string for SCORM 1.2 courses, or `"suspend"` for SCORM 2004 courses. The default behaviour should be left in place unless you are confident you know what you are doing!
+##### \_exitStateIfIncomplete (string):
+Determines the 'exit state' (`cmi.core.exit` in SCORM 1.2, `cmi.exit` in SCORM 2004) to set if the course hasn't been completed. The default behaviour will cause the exit state to be set to an empty string for SCORM 1.2 courses, or `"suspend"` for SCORM 2004 courses. The default behaviour should be left in place unless you are confident you know what you are doing!
 
->**\_exitStateIfComplete** (string): Determines the 'exit state' (`cmi.core.exit` in SCORM 1.2, `cmi.exit` in SCORM 2004) to set when the course has been completed. The default behaviour will cause the exit state to be set to an empty string for SCORM 1.2 courses, or `"normal"` for SCORM 2004 courses. The default behaviour should be left in place unless you are confident you know what you are doing! Note: if you are using SCORM 2004, you can set this to `"suspend"` to prevent the LMS from clearing all progress tracking when a previously-completed course is re-launched by the learner.
+##### \_exitStateIfComplete (string):
+Determines the 'exit state' (`cmi.core.exit` in SCORM 1.2, `cmi.exit` in SCORM 2004) to set when the course has been completed. The default behaviour will cause the exit state to be set to an empty string for SCORM 1.2 courses, or `"normal"` for SCORM 2004 courses. The default behaviour should be left in place unless you are confident you know what you are doing! Note: if you are using SCORM 2004, you can set this to `"suspend"` to prevent the LMS from clearing all progress tracking when a previously-completed course is re-launched by the learner.
 
 <div float align=right><a href="#top">Back to Top</a></div>  
 
@@ -120,7 +139,7 @@ When **Spoor** is installed, *scorm_test_harness.html* can be used instead of *i
 
 Note that due to the data storage limitations of browser cookies, there is less storage space available than an LMS would provide. In particular having `_shouldRecordInteractions` enabled can cause a lot of data to be written to the cookie, using up the available storage more quickly - it is advised that you disable this setting when testing via *scorm_test_harness.html*. As of v2.1.1, a browser alert will be displayed if the code detects that the cookie storage limit has been exceeded.
 
-### SCORM Error Messages  
+### SCORM Error Messages
 As of v3.6.0 it's possible to amend and/or translate the error messages that are shown by this extension whenever an LMS error is encountered. See [*example.json*](https://github.com/adaptlearning/adapt-contrib-spoor/blob/master/example.json) for the data that needs to be added to course/_lang_/course.json
 
 Note that you only need to include those you want to amend/translate.