Add ability to specify substep order (#779)

The substep plugin currently shows each substep in the order in which
it appears in the HTML.  This is not always an ideal fit for some
presentation styles, where it would be helpful to specify a different
order (e.g., to add annotations to an image).

This commit allows users to specify a custom order via the
`data-substep-order` attribute.  Substeps without a
`data-substep-order` attribute are revealed last.

This commit also updates the Substep README to document the new
feature.

js/impress.js

@@ -2081,6 +2081,20 @@
             'useAMPM': false
         };
         break;
+    case 'zh-CN':
+    case 'zh-cn':
+        lang = {
+            'noNotes': '<div class="noNotes">当前帧没有备注</div>',
+            'restart': '重新开始',
+            'clickToOpen': '点击以打开演讲者控制界面',
+            'prev': '上一帧',
+            'next': '下一帧',
+            'loading': '加载中',
+            'ready': '就绪',
+            'moving': '移动中',
+            'useAMPM': false
+        };
+        break;
     case 'en': // jshint ignore:line
     default : // jshint ignore:line
         lang = {
@@ -4009,12 +4023,28 @@
 
     var showSubstepIfAny = function( step ) {
         var substeps = step.querySelectorAll( ".substep" );
-        var visible = step.querySelectorAll( ".substep-visible" );
         if ( substeps.length > 0 ) {
-            return showSubstep( substeps, visible );
+            var sorted = sortSubsteps( substeps );
+            var visible = step.querySelectorAll( ".substep-visible" );
+            return showSubstep( sorted, visible );
         }
     };
 
+    var sortSubsteps = function( substepNodeList ) {
+        var substeps = Array.from( substepNodeList );
+        var sorted = substeps
+            .filter( el => el.dataset.substepOrder )
+            .sort( ( a, b ) => {
+                var orderA = a.dataset.substepOrder;
+                var orderB = b.dataset.substepOrder;
+                return parseInt( orderA ) - parseInt( orderB );
+            } )
+            .concat( substeps.filter( el => {
+                return el.dataset.substepOrder === undefined;
+            } ) );
+        return sorted;
+    };
+
     var showSubstep = function( substeps, visible ) {
         if ( visible.length < substeps.length ) {
             for ( var i = 0; i < substeps.length; i++ ) {
@@ -4030,8 +4060,9 @@
     var hideSubstepIfAny = function( step ) {
         var substeps = step.querySelectorAll( ".substep" );
         var visible = step.querySelectorAll( ".substep-visible" );
+        var sorted = sortSubsteps( visible );
         if ( substeps.length > 0 ) {
-            return hideSubstep( visible );
+            return hideSubstep( sorted );
         }
     };
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "impress.js",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "lockfileVersion": 1,
   "requires": true,
   "dependencies": {

src/plugins/substep/README.md

@@ -9,6 +9,12 @@ alternatively hide one (for `prev()`). Only once all substeps are shown, will a
 actually move to the next step, and only when all are hidden will a call to `prev()` move to the
 previous one.
 
+By default, this plugin reveals substeps in the order in which they appear in the HTML.  If you
+would like to reveal them in a different order, you can supply an integer to `data-substep-order`.
+If you do so, this plugin will reveal the substeps in ascending order; any substeps without a
+specified `data-substep-order` will be revealed after all substeps with a specified order have
+been revealed.
+
 Calls to `goto()` will be ignored by this plugin, i.e. `goto()` will transition to whichever step is
 the target.
 

src/plugins/substep/substep.js

@@ -61,12 +61,28 @@
 
     var showSubstepIfAny = function( step ) {
         var substeps = step.querySelectorAll( ".substep" );
-        var visible = step.querySelectorAll( ".substep-visible" );
         if ( substeps.length > 0 ) {
-            return showSubstep( substeps, visible );
+            var sorted = sortSubsteps( substeps );
+            var visible = step.querySelectorAll( ".substep-visible" );
+            return showSubstep( sorted, visible );
         }
     };
 
+    var sortSubsteps = function( substepNodeList ) {
+        var substeps = Array.from( substepNodeList );
+        var sorted = substeps
+            .filter( el => el.dataset.substepOrder )
+            .sort( ( a, b ) => {
+                var orderA = a.dataset.substepOrder;
+                var orderB = b.dataset.substepOrder;
+                return parseInt( orderA ) - parseInt( orderB );
+            } )
+            .concat( substeps.filter( el => {
+                return el.dataset.substepOrder === undefined;
+            } ) );
+        return sorted;
+    };
+
     var showSubstep = function( substeps, visible ) {
         if ( visible.length < substeps.length ) {
             for ( var i = 0; i < substeps.length; i++ ) {
@@ -82,8 +98,9 @@
     var hideSubstepIfAny = function( step ) {
         var substeps = step.querySelectorAll( ".substep" );
         var visible = step.querySelectorAll( ".substep-visible" );
+        var sorted = sortSubsteps( visible );
         if ( substeps.length > 0 ) {
-            return hideSubstep( visible );
+            return hideSubstep( sorted );
         }
     };