New loading modes, in progress

Jakefile

@@ -255,6 +255,13 @@ desc(_dfit_nl(['Run tests for the distribution.',
                'Requires: `karma`, `karma-mocha-reporter`.']));
 task('test', ['dist-min', 'test-dist']);
 
+// test-debug ==================================================================
+
+desc(_dfit_nl(['Run tests with debug for the unminified distribution.',
+               'Usage: Just call {jake test}.',
+               'Requires: `karma`, `karma-mocha-reporter`.']));
+task('test-debug', ['dist', 'test-dist-debug']);
+
 // test-dist ===================================================================
 
 desc(_dfit_nl(['Test the distribution which already exists.',
@@ -272,6 +279,24 @@ task('test-dist', { async: true }, function() {
                            complete(); });
 });
 
+// test-dist-debug =============================================================
+
+desc(_dfit_nl(['Test the unminified distribution which already exists.',
+               'Usage: Just call {jake test-dist-debug}.',
+               'Requires: `karma`, `karma-mocha-reporter`.']));
+task('test-dist-debug', { async: true }, function() {
+    _print('Running tests');
+
+    jake.exec([ Binaries.KARMA, 'start',
+                _loc(Tests.Config),
+                '--single-run=false',
+                '--debug'
+              ].join(' '), EXEC_OPTS,
+              function() { _print('Tests finished successfully');
+                           _print(DONE_MARKER);
+                           complete(); });
+});
+
 // docs ========================================================================
 
 desc(_dfit_nl(['Generate Docco docs and compile API documentation into '+

doc/embedding.md

@@ -246,9 +246,11 @@ URL | `IFRAME`/`div` | JS Object | Default | Description
 `z`/`zoom` | `anm-zoom` | `zoom` | `1` | animation zoom
 `t`/`from` | `anm-start-from` | - | `0` | a time to start playing from (multiplier is 10ms, so `310` means _3s 100ms_)
 `p`/`at` | `anm-stop-at` | - | - | a time of animation where to stop at, when Player was initialized (multiplier is 10ms, so `310` means _3s 100ms_)
-- | _`div`-only:_ `anm-src` | - | - | JSON for the animation  to load from
+- | _`div`-only:_ `anm-src` | - | - | JSON for the animation to load from
+- | _`div`-only:_ `anm-importer` | - | `animatron` | Importer to use with this JSON
 `m`/`mode` | `anm-mode` | `mode` | - | (_deprecated_) a mode of a Player, one of: ...
-`lm`/`lmode` | `anm-loading-mode` | `loadingMode` | `onplay` | `onplay` means to start loading an animation when user clicks _Play_ button (and show _thumbnail_ before), `onrequest` means to start loading animation only when the script asked for it and expect it to be completely loaded when user clicks _Play_ button
+`lm`/`lmode` | `anm-loading-mode` | `loadingMode` | `rightaway` | see [section below][lmodes-pmodes]
+`pm`/`pmode` | `anm-playing-mode` | `playingMode` | `onrequest` | see [section below][lmodes-pmodes]
 - | `anm-events` | `handleEvents` | `false` | allows animation to catch and process user mouse/keyboard events by itself (has a meaning for games or infographics)
 - | `anm-debug` | `debug` | `false` | show debug information like FPS and paths/bounds of objects
 `bg`/`bgcolor` | `anm-bg-color` | `bgColor` | `transparent` | set background color of an animation (if it is set, it can't be overriden), format is `#00ff00`
@@ -263,6 +265,58 @@ URL | `IFRAME`/`div` | JS Object | Default | Description
 `me`/`errors` | `anm-mute-errors` | `muteErrors` | `false` | do not stop playing if some errors happened during the playing process, just log them
 `ver`/`version` | - | - | `latest` | override player version used to play this project
 
+## Loading Modes and Playing Modes
+
+Most times, you'll only need `autoPlay` option. But in some cases you may wish to configure loading and playing precisely.
+
+First, some quick tips:
+
+* if you want scene to load and play immediately when you specified source, just set `autoPlay` to `true`, no loading / playing mode needed;
+* if you want to postpone loading even when you specified animation source with HTML attribute, set `loadingMode` to `onrequest`;
+* if you want loading to always automatically happen before playing (i.e. to load scene just when user pressed Play button or you called `play` method, and play it then), set `loadingMode` to `onplay`;
+* if you want loading to happen in background i.e. when you specified source with HTML attribute, but player to start only when user hovers over it, set `playingMode` to `onhover`, leave `loadingMode` being default; ...only when user scrolled down to it — set `playingMode` to `wheninview`;
+
+Loading modes are:
+
+* `rightaway` _(default)_ — searches for an animation source where possible (i.e. HTML tag attribute) and, if finds it, tries to load it on player creation; if source wasn't found, waits for user to call `.load` manually as for 'onrequest';
+* `onrequest` — waits for user to manually call `.load` method; if animation source was passed i.e. through HTML tag attribute, waits for user to call `.load` method without parameters and uses this URL as a source; this allows user to completely control a moment of loading; if `.load` method was called with some values, this call cancels postponed load and overrides it;
+* `onplay` — when play button was pressed or `.play` method was called, automatically starts loading a scene and plays it just after; even if scene was passed with HTML attributes, waits for `.play` call;
+* `onidle` — not yet implemented;
+
+Playing modes are:
+
+* `onrequest` _(default)_ — waits for user to manually call `.play` method or press play button;
+* `onhover` — starts playing animation (if loaded before) when user hovered with mouse over the player canvas;
+* `wheninview` — starts playing animation (if loaded before) when at least some part of canvas appears in user's browser viewport;
+
+
+Loading Mode | Playing Mode | `autoPlay` | HTML attr. | `forSnaphot`/manual load | Result
+-------------|--------------|------------|------------|-----------|---
+`rightaway` | `onrequest` | `false` | none | yes | loads a scene from `.load` call and waits for a call to `.play` method (or play button to be pressed)
+`rightaway` | `onrequest` | `true` | none | yes | loads a scene from `.load` call and immediately starts playing it
+`rightaway` | `onrequest` | `false` | has | - | immediately loads a scene specified in HTML attributes and waits for a call to `.play` method (or play button to be pressed)
+`rightaway` | `onrequest` | `true` | has | - | immediately loads a scene specified in HTML attribute and then starts playing it
+`onrequest` | `onrequest` | `false` | none | yes | loads a scene from `.load` call and waits for a call to `.play` method (or play button to be pressed)
+`onrequest` | `onrequest` | `true` | none | yes | loads a scene from `.load` call and immediately starts playing it
+`onrequest` | `onrequest` | `false` | has | - | waits for user to call `.load` method w/o attributes, then loads scene (specified in HTML attributes) and waits for a call to `.play` method (or play button to be pressed)
+`onrequest` | `onrequest` | `true` | has | - | waits for user to call `.load` method w/o attributes, then loads scene (specified in HTML attributes) and immediately plays it
+`onplay` | `onrequest` | `false` | none | yes | do not loads the scene passed with a `.load` call, but postpones loading to a next call to `.play` method (or play button to be pressed), then loads and plays it just after that
+`onplay` | `onrequest` | `true` | none | yes | do not loads the scene passed with a `.load` call, but postpones it to a call to `.play` method, but since it is called immediately, loads and plays the scene as soon as Player ready to do so
+`onplay` | `onrequest` | `false` | has | - | do not loads the scene specified with HTML attributes, but postpones loading to a next call to `.play` method (or play button to be pressed), then loads and plays it just after that
+`onplay` | `onrequest` | `true` | has | - | do not loads the scene specified with HTML attributes, but postpones it to a call to `.play` method, but since it is called immediately, loads and plays the scene as soon as Player ready to do so
+`rightaway` | `onhover` | any | has | - | immediately loads a scene specified in HTML attributes and waits for user to move mouse over a Player to start playing
+`rightaway` | `onhover` | any | none | yes | loads a scene from a `.load` call  and waits for user to move mouse over a Player to start playing
+`rightaway` | `wheninview` | any | has | - | immediately loads a scene specified in HTML attributes and waits for user to scroll down to a Player to start playing
+`rightaway` | `wheninview` | any | none | yes | loads a scene from a `.load` call and waits for user to scroll down to a Player to start playing
+`onplay` | `onhover` | any | has | - | do not loads the scene specified with HTML attributes, but postpones loading to a moment when user will move mouse over the Player, then loads and plays it just after that
+`onplay` | `onhover` | any | none | yes | do not loads the scene passed with a `.load` call, but postpones loading to a moment when user will move mouse over the Player, then loads and plays it just after that
+`onplay` | `wheninview` | any | has | - | do not loads the scene specified with HTML attributes, but postpones loading to a moment when user will scroll down to the Player position, then loads and plays it just after that
+`onplay` | `wheninview` | any | none | yes | do not loads the scene passed with a `.load` call, but postpones loading to a moment when user will scroll down to the Player position, then loads and plays it just after that
+`onrequest` | `onhover` | any | has | - | same as `onplay`/`onhover`, since `.play` method is called on mouse hover
+`onrequest` | `onhover` | any | none | yes | same as `onplay`/`onhover`, since `.play` method is called on mouse hover
+`onrequest` | `wheninview` | any | has | - | same as `onplay`/`wheninview`, since `.play` method is called on scroll down
+`onrequest` | `wheninview` | any | none | yes | same as `onplay`/`wheninview`, since `.play` method is called on scroll down
+
 [permanent]: https://github.com/Animatron/player/blob/docs/doc/embedding.md
 
 [iframe]: #iframe
@@ -274,3 +328,4 @@ URL | `IFRAME`/`div` | JS Object | Default | Description
 [adding-events]: #adding-events
 [create-player]: #custom-scene-with-createplayer
 [for-snapshot]: #snapshot-with-forsnapshot
+[lmodes-pmodes]: #loading-modes-and-playing-modes

examples/configuration.js

@@ -8,6 +8,20 @@ var currentMode; // embed, config, publish, html
 
 var shortVersion = true;
 
+var loadingModes = [
+    { value: 'rightaway', name: 'right away', description: 'loads animation just immediately when finds it\'s source (i.e. from HTML attribute)' },
+    { value: 'onrequest', name: 'on request', description: 'waits for user to manually call .load() method' },
+    { value: 'onplay', name: 'on play', description: 'when play button was pressed, starts loading a scene and plays it just after' }/*,
+    { value: 'onidle', name: 'on idle', description: ' waits for pause in user actions (mouse move, clicks, keyboard) to load the animation' },*/
+];
+
+var playingModes = [
+    { value: 'onrequest', name: 'on request', description: 'same to autoPlay: false, waits for user to manually call .play() method' },
+    { value: 'rightaway', name: 'right away', description: 'same to autoPlay: true' },
+    { value: 'onhover', name: 'on hover', description: 'starts playing animation when user hovered with mouse over the player canvas' },
+    { value: 'wheninview', name: 'when in view', description: 'starts playing animation when Player appeares in browser viewport' }
+];
+
 function getElm(id) { return document.getElementById(id); }
 
 function collectOptions() {
@@ -25,6 +39,7 @@ function collectOptions() {
     if (!getElm('opts-bg-color').disabled) options.bgColor = getElm('opts-bg-color').value;
     if (!getElm('opts-ribbons').disabled) options.ribbonsColor = getElm('opts-ribbons').value;
     if (!getElm('opts-loading').disabled) options.loadingMode = getElm('opts-loading').selectedIndex;
+    if (!getElm('opts-playing').disabled) options.playingMode = getElm('opts-playing').selectedIndex;
     if (!getElm('opts-thumbnail').disabled) options.thumbnail = getElm('opts-thumbnail').value;
     //if (!getElm('opts-images').disabled) options.imagesEnabled = getElm('opts-images').checked;
     if (!getElm('opts-audio').disabled) options.audioEnabled = getElm('opts-audio').checked;
@@ -134,12 +149,30 @@ function init() {
         'loading': { label: 'Loading', type: 'select',
                      create: function() {
                          var select = document.createElement('select');
-                         var onPlay = document.createElement('option');
-                         onPlay.innerText = onPlay.textContent = 'on play';
-                         var onRequest = document.createElement('option');
-                         onRequest.innerText = onRequest.textContent = 'on request';
-                         select.appendChild(onPlay);
-                         select.appendChild(onRequest);
+                         for (var i = 0, il = loadingModes.length, mode; i < il; i++) {
+                             var option = document.createElement('option');
+                             option.innerText = option.textContent = loadingModes[i].name;
+                             select.appendChild(option);
+                         }
+                         select.setAttribute('title', loadingModes[0].description);
+                         select.addEventListener('change', function() {
+                             select.setAttribute('title', loadingModes[select.selectedIndex].description);
+                         });
+                         return select;
+                     },
+                     modify: function(elm, form) { elm.selectedIndex = 0; } },
+        'playing': { label: 'Playing', type: 'select',
+                     create: function() {
+                         var select = document.createElement('select');
+                         for (var i = 0, il = playingModes.length, mode; i < il; i++) {
+                             var option = document.createElement('option');
+                             option.innerText = option.textContent = playingModes[i].name;
+                             select.appendChild(option);
+                         }
+                         select.setAttribute('title', playingModes[0].description);
+                         select.addEventListener('change', function() {
+                             select.setAttribute('title', playingModes[select.selectedIndex].description);
+                         });
                          return select;
                      },
                      modify: function(elm, form) { elm.selectedIndex = 0; } },
@@ -195,7 +228,8 @@ var optionsMapper = function(mode, options) {
             function numberOption(v) { return v; };
             function colorOption(v) { return (v.indexOf('#') >= 0) ? v.slice(1) : v; };
             function booleanOption(v) { return v ? '1' : '0'; };
-            function loadingModeOption(v) { return (v === 1) ? 'onrequest' : 'onplay' };
+            function loadingModeOption(v) { return loadingModes[v].value };
+            function playingModeOption(v) { return playingModes[v].value };
 
             return {
                 width: extractOption('width', 'w', 'width', numberOption),
@@ -209,6 +243,7 @@ var optionsMapper = function(mode, options) {
                 startFrom: extractOption('startFrom', 't', 'from', parseTime),
                 stopAt: extractOption('stopAt', 'p', 'at', parseTime),
                 loadingMode: extractOption('loadingMode', 'lm', 'lmode', loadingModeOption),
+                playingMode: extractOption('playingMode', 'pm', 'pmode', playingModeOption),
                 bgColor: extractOption('bgColor', 'bg', 'bgcolor', colorOption),
                 ribbonsColor: extractOption('ribbonsColor', 'rc', 'ribcolor', colorOption),
                 audioEnabled: extractOption('audioEnabled', 's', 'audio', booleanOption),
@@ -227,7 +262,8 @@ var optionsMapper = function(mode, options) {
             function textOption(v) { return '\'' + v + '\''; };
             function colorOption(v) { return '\'' + v + '\''; };
             function booleanOption(v) { return v ? 'true' : 'false'; };
-            function loadingModeOption(v) { return (v === 1) ? '\'onrequest\'' : '\'onplay\'' };
+            function loadingModeOption(v) { return '\'' + loadingModes[v].value + '\''; };
+            function playingModeOption(v) { return '\'' + playingModes[v].value + '\''; };
             function thumbnailOption(v) { return v; };
 
             return {
@@ -240,6 +276,7 @@ var optionsMapper = function(mode, options) {
                 speed: extractOption('speed', numberOption),
                 zoom: extractOption('zoom', numberOption),
                 loadingMode: extractOption('loadingMode', loadingModeOption),
+                playingMode: extractOption('playingMode', playingModeOption),
                 bgColor: extractOption('bgColor', colorOption),
                 ribbonsColor: extractOption('ribbonsColor', colorOption),
                 thumbnail: extractOption('thumbnail', textOption),
@@ -262,7 +299,8 @@ var optionsMapper = function(mode, options) {
             function textOption(v) { return v; };
             function numberOption(v) { return v; };
             function booleanOption(v) { return v ? 'true' : 'false'; };
-            function loadingModeOption(v) { return (v === 1) ? 'onrequest' : 'onplay' };
+            function loadingModeOption(v) { return loadingModes[v].value };
+            function playingModeOption(v) { return playingModes[v].value };
 
             return {
                 width: extractOption('width', 'anm-width', numberOption),
@@ -276,6 +314,7 @@ var optionsMapper = function(mode, options) {
                 startFrom: extractOption('startFrom', 'anm-start-from', parseTime),
                 stopAt: extractOption('stopAt', 'anm-stop-at', parseTime),
                 loadingMode: extractOption('loadingMode', 'anm-loading-mode', loadingModeOption),
+                playingMode: extractOption('playingMode', 'anm-playing-mode', playingModeOption),
                 bgColor: extractOption('bgColor', 'anm-bg-color', colorOption),
                 ribbonsColor: extractOption('ribbonsColor', 'anm-rib-color', colorOption),
                 thumbnail: extractOption('thumbnail', 'anm-thumbnail', textOption),

package.json

@@ -70,7 +70,8 @@
     "jasmine-core": "^2.3.4",
     "karma": "^0.12.37",
     "karma-chrome-launcher": "^0.2.0",
-    "karma-mocha-reporter": "^1.0.2",
-    "karma-jasmine": "^0.3.6"
+    "karma-jasmine": "^0.3.6",
+    "karma-jasmine-ajax": "^0.1.13",
+    "karma-mocha-reporter": "^1.0.2"
   }
 }

spec/Runner.html

@@ -2,14 +2,16 @@
 <html>
 <head>
   <meta charset="utf-8">
-  <title>Jasmine Spec Runner v2.2.0</title>
+  <title>Jasmine Spec Runner v2.3.4</title>
 
-  <link rel="shortcut icon" type="image/png" href="lib/jasmine-2.2.0/jasmine_favicon.png">
-  <link rel="stylesheet" href="lib/jasmine-2.2.0/jasmine.css">
+  <link rel="shortcut icon" type="image/png" href="lib/jasmine-2.3.4/jasmine_favicon.png">
+  <link rel="stylesheet" href="lib/jasmine-2.3.4/jasmine.css">
 
-  <script src="lib/jasmine-2.2.0/jasmine.js"></script>
-  <script src="lib/jasmine-2.2.0/jasmine-html.js"></script>
-  <script src="lib/jasmine-2.2.0/boot.js"></script>
+  <script src="lib/jasmine-2.3.4/jasmine.js"></script>
+  <script src="lib/jasmine-2.3.4/jasmine-html.js"></script>
+  <script src="lib/jasmine-2.3.4/boot.js"></script>
+
+  <script src="lib/jasmine-2.3.4/mock-ajax.js"></script>
 
   <!-- include source files here... -->
   <script src="../dist/player.js"></script>
@@ -19,6 +21,7 @@
   <script src="./search.spec.js"></script>
   <script src="./mouse.spec.js"></script>
   <script src="./time.spec.js"></script>
+  <script src="./loading-modes.spec.js"></script>
 
 </head>