Show:

File: app/randomizers/select.js

  1. /**
  2. * @module exp-player
  3. * @submodule randomizers
  4. */
  5.  
  6. /**
  7. * Randomizer to allow selection of one (or arbitrary sequence) of defined frames.
  8. * This is intended to be used either within a {{#crossLink "Random-parameter-set"}}{{/crossLink}} randomizer with
  9. * different `parameterSets` picking out different values for `whichFrames`) or indirectly
  10. * via the {{#crossLink "Exp-frame-select"}}{{/crossLink}} frame (which allows setting `whichFrames` using a custom
  11. * `generateProperties` function). Note that you cannot add a `generateProperties` function
  12. * directly to a randomizer!
  13. *
  14. * To use, define a frame with "kind": "choice" and "sampler": "select",
  15. * as shown below, in addition to the parameters described under 'properties'.
  16. *
  17. ```json
  18. "frames": {
  19.     "select-randomizer-test": {
  20.         "sampler": "select",
  21.         "kind": "choice",
  22.         "whichFrames": 0,
  23.         "commonFrameProperties": {
  24.             "kind": "exp-lookit-text"
  25.         },
  26.         "frameOptions": [
  27.             {
  28.                 "blocks": [
  29.                     {
  30.                         "emph": true,
  31.                         "text": "Let's think about hippos!",
  32.                         "title": "FRAME 1"
  33.                     },
  34.                     {
  35.                         "text": "Some more about hippos..."
  36.                     }
  37.                 ]
  38.             },
  39.             {
  40.                 "blocks": [
  41.                     {
  42.                         "emph": false,
  43.                         "text": "Let's think about dolphins!",
  44.                         "title": "FRAME 2"
  45.                     }
  46.                 ]
  47.             }
  48.         ]
  49.     }
  50. }
  51. *
  52. * ```
  53. * @class Select
  54. */
  55.  
  56. var randomizer = function(frameId, frameConfig, pastSessions, resolveFrame) {
  57.  
  58.     // Data provided to randomizer (properties of frameConfig):
  59.  
  60.     /**
  61.      * List of frames that can be created by this randomizer. Each frame is an
  62.      * object with any necessary frame-specific properties specified. The
  63.      * 'kind' of frame can be specified either here (per frame) or in
  64.      * commonFrameProperties. If a property is defined for a given frame both
  65.      * in this frame list and in commonFrameProperties, the value in the frame
  66.      * list will take precedence.
  67.      *
  68.      * (E.g., you could include 'kind': 'normal-frame' in
  69.      * commmonFrameProperties, but for a single frame in frameOptions, include
  70.      * 'kind': 'special-frame'.)
  71.      *
  72.      * @property {Object[]} frameOptions
  73.      */
  74.  
  75.     /**
  76.      * Object describing common parameters to use in EVERY frame created
  77.      * by this randomizer. Parameter names and values are as described in
  78.      * the documentation for the frameType used.
  79.      *
  80.      * @property {Object} commonFrameProperties
  81.      */
  82.  
  83.     /**
  84.      * Index or indices (0-indexed) within frameOptions to actually use. This can be either a number
  85.      * (e.g., 0 or 1 to use the first or second option respectively) or an array providing
  86.      * an ordered list of indices to use (e.g., [0, 1] or [1, 0] to use the first then
  87.      * second or second then first options, respectively). All indices must be integers
  88.      * in [0, frameOptions.length).
  89.      *
  90.      * If not provided or -1, the entire frameOptions list is used in order. (If empty
  91.      * list is provided, however, that is respected and no frames are inserted by this
  92.      * randomizer.)
  93.      *
  94.      * @property {Number} whichFrames
  95.      */
  96.  
  97.     var thisFrame = {};
  98.     var frames = [];
  99.  
  100.     // If a single frame index is provided, convert to a single-element list
  101.     if ((typeof frameConfig.whichFrames) === 'number' && frameConfig.whichFrames != -1) {
  102.         frameConfig.whichFrames = [frameConfig.whichFrames];
  103.     } else if (!frameConfig.hasOwnProperty('whichFrames') || frameConfig.whichFrames == -1 || !frameConfig.whichFrames) {
  104.         frameConfig.whichFrames = [...frameConfig.frameOptions.keys()];
  105.     }
  106.  
  107.     for (var iFrame = 0; iFrame < frameConfig.whichFrames.length; iFrame++) {
  108.         if (frameConfig.whichFrames[iFrame] < 0 || frameConfig.whichFrames[iFrame] >= frameConfig.frameOptions.length) {
  109.             throw `Frame index in whichFrames out of range in select randomizer. All frame indices must be between 0 and frameOptions.length - 1.`;
  110.         }
  111.  
  112.         // Assign parameters common to all frames made by this randomizer
  113.         thisFrame = {};
  114.         Object.assign(thisFrame, frameConfig.commonFrameProperties);
  115.  
  116.         // Assign parameters specific to this frame (allow to override
  117.         // common parameters assigned above)
  118.         Object.assign(thisFrame, frameConfig.frameOptions[frameConfig.whichFrames[iFrame]]);
  119.  
  120.         thisFrame = resolveFrame(frameId + '-' + iFrame, thisFrame)[0];
  121.         frames.push(...thisFrame);
  122.     }
  123.  
  124.     /**
  125.      * Parameters captured and sent to the server
  126.      *
  127.      * @attribute conditions
  128.      * @param {Object[]} whichFrames the index/indices of the frame(s) used
  129.      */
  130.     return [frames, {'whichFrames': frameConfig.whichFrames}];
  131. };
  132. export default randomizer;
  133.  
  134.