Skip to content

Software Simulations

Software Simulations

Ali can handle simple software simulations where the software can be built as HTML elements within a course. This page serves as technical documentation of the component and how to implement the individual elements.

Due to the nature of simulations, an example will not be reproduced here. Please ensure that the code examples are enabled when viewing this page, as most of the useful documentation is contained in example code.

Adding ali-simulation to a Course

The ali-simulation source code must be added to the project before running any installation scripts via npm. The code examples in this document should help you in correctly adding the items listed below.

  1. Start by adding a new entry for ali-simulation as the last item in the svnDependencies node in the package.json configuration file. The new entry should be named "ali-simulation" and the value should be the url to the latest tag in SVN. You can get the URL to the tag by locating the tag in Cornerstone, and right-clicking the tag name and selecting “Copy URL”.  Be sure to remove your username from the resulting URL.Remember that JSON encoding requires double quotes, not single quotes.At this point, you should run any standard install scripts, ensuring that the ‘ali-simulation’ code is downloaded and installed in the node_modules directory.
  2. Next, Babel needs to know to use ES6 language compilation for the simulation package. Locate the babel-loader module entry and alter the exclude directive to include ali-simulation in babel-loaders ES6 Parsing. This must be done to both  webpack.config.dev.babel.js and webpack.config.prod.babel.js.
  3. To include the simulation code in your project, locate /src/js/interactions.js and add a new import statement below the existing, importing the simulation base code. Then at the bottom of the file, add the code necessary to expose the Simulation class to the global scope.
  4. To include the simulation’s base styles in your project, locate src/scss/content.scss. Within this file, locate the import statements for the other ali-interactions, and add a new import statement for ali-simulations. Note that the “~” (tilde) preceding the path is required.
  5. Finally, the simulation code is minimally styled. You will be required to write custom styles for your project. Create a new stylesheet document in /src/scss/content/interactions and name it _simulation.scss. This is where you’ll place your custom styles for all simulations in your course. Return to the /src/scss/content.scssfile and add an import below the one you just added, importing the custom styles.
    • Best practices dictate that you use a main wrapping class to “namespace” your simulation styles.
    • For an example of custom styles, see the _kids.scss example file in the /scssdirectory of the ali-simulations project.
// Adding the new SVN dependency in `/package.json`
...

},
"svnDependencies": {
  "aligo": "svn://...",
  "ali-interactions": "svn://...",
  "ali-simulation" : "svn://url/to/ali-simulation/tags/number"
}
// Allowing babel-loader ES6 Compilation in *both* `/webpack.config.dev.babel.js` and `webpack.config.prod.babel.js`
...
{
 test : /\.js$/,
 use : 'babel-loader',
 exclude : /node_modules\/(?!(ali-interactions|ali-simulation))/
 },
// in `/src/js/interactions.js`

import Simulation from 'ali-simulation/simulation'; 

...

if ( Simulation ) {
  window.Simulation = Simulation;
}
/* in `/src/scss/content.scss` */

@import "~ali-simulation/scss/simulation"; /* import the package styles */
@import "content/interactions/simulation"; /* your custom styles */

Basic Building Blocks

Simulations have a few basic requirements in order for them to function:

  • Simulations should contain no more than 10 screens.
  • Simulation screens should contain no more than 5 usable input fields.
    • These fields can be text inputs, radio button groups, checkboxes, select dropdowns or text areas.
    • Text areas are not validated! The simulation only checks to see if they’re non-empty.

Additional details on each type of input field will be documented later in this document.

For the most part, simulations are built declaratively — that is, you specify the details and behavior of the simulation using HTML tags and custom data attributes. While the Simulation class does not prohibit custom code within a particular screen, this should be kept to a minimum and should never attempt to alter the behavior of the simulation itself.

The simulation element must have a unique id and use the class .simulation as well as any custom namespace you use for styles. Within that should be a single child with the class .screen-container.

Simulations are not automatically initialized like other components. You must include a scriptblock at the bottom of your content page with basic initialization code, using Simulation.create.

Simulation.create() takes two parameters:

  • A reference to the base simulation element.
  • An object literal containing the options for the simulation.

The available options for Simulations are:

  • peekDuration – Number of milliseconds before dialogs are auto-closed.
  • user – If set, this name will be the username for all input binding that utilizes a username in the pattern.
  • dateFormat – A reference function that takes a Date object as it’s only parameter, and returns a formatted string. The default function returns a date in YYYY-MM-DD format.
  • messages – An object literal containing any of the following fields:
    • fieldsOnScreen – Message displayed to the user in the status dialog, indicating the number of fields required on the current screen.
    • fieldsOnScreenARIALabel – The aria-label for the button that serves as a status element when there are no errors.
    • errorDialogText – Lead-in text for the dialog listing each error currently on screen.
    • errorsOnScreenARIALabel – The aria-label for the button that serves as a status element when there are no errors.
    • escapeDefaultMessage – The default message displayed when the user has exhausted their attempts for the current screen. This message is only used if a .escape-message element is not found.
<div id="my-simulation" class="simulation custom-namespace">
 <div class="screen-container">
    <!-- Only form.screen elements can be within the screen-container -->
 </div>
</div>
<script>
 if( window.Simulation ){
   Simulation.create( document.getElementById( 'my-simulation' ), 
     {
         peekDuration: 3000 ,
         user: "Mary Trainer" ,
         dateFormat : function(d){ return "tomorrow" } ,
         messages : {
             fieldsOnScreen : "You don't need to know." ,
             fieldsOnScreenARIALabel : "Heh" ,
             errorDialogText : "You suck this much %d" ,
             errorsOnScreenARIALabel : "You suck %d" ,
             escapeDefaultMessage : "I can't believe we have to do this for you."
         }
    }
  );
} 
</script> 

Screens

The simulation handles accessibility by displaying a serial list of screens to be displayed for the simulation. Screens have the following required elements:

  • Each screen element must be of type form and use the class .screen
  • All form.screenelements must be a direct child of the .screen-containerelement.
  • Screens are displayed in source order — that is the first screen must be the first child of .screen-container, the second screen must be the second child, etc.
    • The first screen element must also have the class .active to ensure that it is displayed before the Simulation JavaScript is initialized to prevent FOUT.
  • The form.screen tag should have the attribute data-attempts and have an unsigned integer value equal to the number of times the user can attempt the screen before the simulation provides the correct answer. If this value is not supplied, the default number of attempts is 3.
  • The first child of the form.screen must be a span with the class of .sr-onlythat contains the alternate text description for the non-interactive portions of the current screen.
  • The second child of the form.screen must be a header element that contains the instructions to the user for this screen. This field is HTML enabled, but should not contain interactive elements.
    • Note: The prompt text, when applied in the UI, can only be 2 lines in height. Any additional text will be clipped.
  • The third child of the form.screen must be a div element with the class of .escape-message that contains feedback to to the user in the event that they have used all their attempts as well as instructions of what to do next. This field is HTML enabled, but should not contain interactive elements.

All other children of the screen items should be either labels, fieldsetsor button elements, depending on the fields or actions required in the screen.

<form id="screen-2" class="screen" data-attempts="2">
    <span class="sr-only">This is the alt-text of this screen</span>
    <header>
        <p>This is the prompt displayed to the user as instructions for this screen.</p>
    </header>
    <div class="escape-message">
        <p>This is the escape message when the user exceeds their attempts</p>
    </div>
</form>

The “Next” Button

In order to move to the next screen of the simulation, you must create a “next” button. The appearance of this element is dependent on the content of the simulation (whether you want it to appear as if it were within the application your simulating or control the simulation). The only strict requirements are that:

  • It is an HTML button tag (not a link or other element)
  • That the button tag as the attribute data-next="true"
  • If the button does not have a text label (for instance, it has an image background), you must add an aria-labelattribute.
<form id="screen-1" class="screen active" data-attempts="3">
    <!-- Required elements here -->

    <button id="element-1" data-next="true" aria-label="Workload">&nbsp;</button>
 </form>

Text Input Fields

  • Text input fields should wrapped in a label tag. The label should be a direct child of the .screen element.
  • The first child of the label must be the a span with the class of .label-text containing the visible label for the element.
    • If the label is not visible on the application you are simulating, use the .sr-onlyclass in addition to the .label-textclass.
  • The input tag should come directly after the span.label-textelement and be of type text.
    • psudo-text types (such as number or date) are not supported at this time.
  • The input tag must have a data-nameattribute that contains the logical name or label of the form element.
    • This will be used in error messages to indicate the field the user needs to fix.
  • The input tag must have a data-required attribute containing the value the user must enter into this field.
    • Multiple, comma delimited values may be supplied so long as the total length of the field does not exceed 64 characters.
  • The input tag must have an a data-hintattribute containing the text hint displayed when this field value is incorrect.
    • This hint should be very brief.

Text input fields may also have the following optional values used for data binding the value of the field to the value of another:

  • The input tag may have a data-bindattribute. The value of this attribute must contain the ID name of another input text element from a previous screen.
    • When the screen that contains this element is initialized, the element’s value will be populated using the value from the element indicated by the data-bindattribute.
    • The binding is one-way.
  • The input tag may have a data-patternattribute. The value of this attribute must be a string pattern to be applied to the value from the contents of the element indicated by the data-bindattribute.
    • If data-patternis used, the input text element must have a valid data-bind attribute.
    • The data-pattern string has the following available replacement variables:
      • %v – The value from the element indicated by data-bind
      • %u – The name of the user. If the currentUser option is not set, the simulation will attempt to gather the user’s name from the LMS. If this is not available, the system will use “Current User.”
      • %d – The current date. This will be formatted by the function provided by thedateFormatfunction provided in the initialization options.
<label id="element-3">
   <span class="label-text">My First Field</span>
   <input type="text" 
          data-name="My Field" 
          data-required="Hello" 
          data-hint="You should enter 'Hello'." 
          data-bind="element-2-input" 
          data-pattern="%v [says %u on %d]">
</label>

Textarea Fields

  • Textarea fields should wrapped in a label tag. The label should be a direct child of the .screen element.
  • The first child of the label must be the a span with the class of .label-text containing the visible label for the element.
    • If the label is not visible on the application you are simulating, use the .sr-onlyclass in addition to the .label-textclass.
  • The textarea tag should come directly after the span.label-textelement.
  • The textarea tag must have a data-nameattribute that contains the logical name or label of the form element.
    • This will be used in error messages to indicate the field the user needs to fix.
  • The textarea tag must have a data-required attribute. This value is used to provide default text to the field when the user fails to enter correct data.
  • The textarea tag must have an a data-hintattribute containing the text hint displayed when this field is left empty.

Textarea fields may also have the following optional values used for data binding the value of the field to the value of another:

  • The textarea tag may have a data-bindattribute. The value of this attribute must contain the ID name of another input text element from a previous screen.
    • When the screen that contains this element is initialized, the element’s value will be populated using the value from the element indicated by the data-bindattribute.
    • The binding is one-way.
  • The textarea tag may have a data-patternattribute. The value of this attribute must be a string pattern to be applied to the value from the contents of the element indicated by the data-bindattribute.
    • If data-patternis used, the input text element must have a valid data-bind attribute.
    • The data-pattern string has the following available replacement variables:
      • %v – The value from the element indicated by data-bind
      • %u – The name of the user. If the currentUser option is not set, the simulation will attempt to gather the user’s name from the LMS. If this is not available, the system will use “Current User.”
      • %d – The current date. This will be formatted by the function provided by thedateFormatfunction provided in the initialization options.
<label id="element-4">
   <span class="label-text">My First Field</span>
   <textarea type="text" 
             data-name="My Field" 
             data-required="Hello" 
             data-hint="You should enter 'Hello'."></textarea>
</label>

Select Dropdown Fields

  • Select tag should wrapped in a label tag. The label should be a direct child of the .screen element.
  • The first child of the label must be the a span with the class of .label-text containing the visible label for the element.
    • If the label is not visible on the application you are simulating, use the .sr-onlyclass in addition to the .label-textclass.
  • The select tag should come directly after the span.label-textelement.
  • The select tag must have a data-nameattribute that contains the logical name or label of the form element.
    • This will be used in error messages to indicate the field the user needs to fix.
  • The select tag must have a data-required attribute. This value must correspond to the valueattribute of the correct child option.
  • The select tag must have an a data-hintattribute containing the text hint displayed when this field is left empty.
  • Options within the select tag must have a value attribute.

Select tags do not support data binding.

<label id="element-5">
    <span class="label-text sr-only">Do you want a Coke?</span>
    <select class="yellow" 
            data-required="y" 
            data-name="Want a Coke" 
            data-hint="You know you do."> 
        <option value="0">&nbsp;</option>
        <option value="y">Yes, I want this!</option>
        <option value="n">No, I don't want this.</option>
    </select> 
</label>

Select Multiple

  • Select tag should wrapped in a label tag. The label should be a direct child of the .screen element.
  • The first child of the label must be the a span with the class of .label-text containing the visible label for the element.
    • If the label is not visible on the application you are simulating, use the .sr-onlyclass in addition to the .label-textclass.
  • The select tag should come directly after the span.label-textelement.
  • The select tag must have a data-nameattribute that contains the logical name or label of the form element.
    • This will be used in error messages to indicate the field the user needs to fix.
  • The select tag must have a data-hintattribute containing the text hint displayed when this field is left empty.
  • The select tag must have a data-required attribute. This value must be a comma separated list of values, corresponding to the valueattribute of the correct child options.
  • The select tag must have a data-type attribute with either contains or selected:
    • A value of selected requires that the user has selected all of the options with the values specified.
    • A value of contains requires that the select element contains only the options with the value specified.
      • This options is used for a very specific interaction where options are dynamically added via another process not contained within the simulation base code.
  • Options within the select tag must have a value attribute.

Select tags do not support data binding.

<label id="element-5">
    <span class="label-text sr-only">What are the first two letters of the alphabet?</span>
    <select class="yellow" 
            data-required="a,b" 
            data-type="selected"
            data-name="Letters" 
            data-hint="Choose 'A' and 'B'."> 
        <option value="a">A</option>
        <option value="b">B</option>
        <option value="c">C</option>
    </select> 
</label>

Checkboxes

  • input[type="checkbox"] elements should wrapped in a label tag. The label should be a direct child of the .screen element.
  • input[type="checkbox"]elements do not require the span.label-text element.
    • If supplied, the .label-text may appear before or after the checkbox.
    • If the label is not visible on the application you are simulating, use the .sr-onlyclass in addition to the .label-textclass.
  • The input[type="checkbox"]element must have a data-nameattribute that contains the logical name or label of the form element.
    • This will be used in error messages to indicate the field the user needs to fix.
  • The input[type="checkbox"] element must have a data-required attribute. The value of this attribute should be checked or unchecked.
  • The input[type="checkbox"] element must have an a data-hintattribute containing the text hint displayed when this field is left empty.

Select input[type="checkbox"] elements do not support data binding.

</label><label id="element=6">
    <input type="checkbox" 
           value="greet" 
           data-name="Greeting" 
           data-required="checked" 
           data-hint="You should select this."> 
    Say hello?
</label>

Radio Button Groups

Radio buttons are slightly different, as each group of controls implies a single option.

  • All radio buttons in the current group must be wrapped in a fieldset element.
  • The first child of the label must be the a span with the class of .label-text containing the visible label for the element.
    • If the label is not visible on the application you are simulating, use the .sr-onlyclass in addition to the .label-textclass.
    • Do not use a legend tag as it cannot be styled and may cause accessibility issues with the simulation.
  • input[type="radio"] elements should wrapped in a label tag. The label should be a direct child of the .screen element.
  • All input[type="radio"]elements in a group must have the same name.
  • input[type="radio"]elements do not require the span.label-text element.
    • If supplied, the .label-text may appear before or after the checkbox.
    • If the label is not visible on the application you are simulating, use the .sr-onlyclass in addition to the .label-textclass.
  • Only one of the input[type="radio"]elements within a group should have the following attributes:
    • The input[type="radio"]element must have a data-nameattribute that contains the logical name or label of the form element.
      • This will be used in error messages to indicate the field the user needs to fix.
    • The input[type="radio"] element must have a data-required attribute. The value of this attribute must be checked.
    • The input[type="radio"] element must have an a data-hintattribute containing the text hint displayed when this field is left empty.

Select input[type="radio"] elements do not support data binding.

<fieldset id="element-7">
    <span class="label-text">Greeting</span>
    <label>
        <input type="radio" 
               name="aa" 
               value="yo"> Yo!
    </label>
    <label>
        <input type="radio" 
                 name="aa" 
                 value="hello" 
                 data-name="Greeting" 
                 data-required="checked" 
                 data-hint="Option 'Hello' should be selected."> Hello 
    </label>
</fieldset>

Error Tool Tips

Error tooltips may be positioned using one of the specified classes applied to the surrounding label or fieldset. The available classes are .tooltip-top, .tooltip-right or .tooltip-left .The default (no class) appears below the element.

<label id="element-8" class="tooltip-top">
    <span class="label-text">Date:</span>
    <input class="yellow" 
           type="text" 
           data-name="Date" 
           data-required="03/07/2018" 
           data-hint="Enter the date">
 </label>