Improve Specifc Slide action: trigger other playlists + relative slides.

Author: Steve Therrien

HELP.md

@@ -8,7 +8,35 @@ Command | Description
 ------- | -----------
 Next Slide | Advances to the next slide in the current document. If at the end of a document, will advance to the start of the next document in the playlist.
 Previous Slide | Moves to the previous slide in the current document. If at the start of a document, will move to the start of the previous document in the playlist.
-Specific Slide | Moves to that slide number. A slide number of `0` will trigger the current slide, which can be used to bring back a slide that was cleared using `Clear All` or `Clear Slide`.
+Specific Slide | Moves to that presentation/slide number. See the `Specific Slide` section below.
+
+### Specific Slide
+This action has two parameters:
+
+**Slide Number**: Moves to the slide number specified.
+
+A whole number greater than 0 will move the presentation to that slide number.
+
+A slide number of `0` will trigger the current slide, which can be used to bring back a slide that was cleared using `Clear All` or `Clear Slide`.
+
+A relative number (prefixed with `+` or `-`) will move the presentation +/- that many slides. `+3` will jump ahead three slides, and `-2` will jump back two slides. Try to avoid using `-1` or `+1` relative numbers; use the `Next Slide` and `Previous Slide` actions instead, as they perform better. 
+
+
+**Presentation Path**: Lets you trigger a slide in a different presentation, even from a different playlist.
+
+*Important: Presentation path numbering starts at 0, meaning `0` will trigger a slide in the first presentation in the playlist.*
+
+A single number, like `3`, will let you trigger a slide in the *fourth* presentation in the **current playlist**. 
+
+A path like `1:3` will trigger presentation #4 in playlist #2.
+
+Playlists in groups (or nested groups) are identified using periods. `1.1.0:2` means "The second playlist is a group. The second item in that group is another group. Select the first playlist in that group. Choose the third presentation in the playlist."
+
+The below image may make this more clear:
+
+![specific-slide](documentation/images/specific-slide.png)
+
+
 
 ## Clear/Logo
 Command | Description
@@ -20,6 +48,16 @@ Clear Slide | Clears the current slide (foreground and background)
 Clear Telestrator | Clears all annotations drawn with the telestrator
 Clear to Logo | Clears all the layers and shows the logo image set in ProPresenter
 
+### Clear All
+Note: When the `Clear All` action is triggered against ProPresenter for Windows, the current slide will be lost but on Mac it's preserved.
+
+For example, if you're on slide #5, trigger `Clear All`, and then trigger `Next Slide`:
+- On Mac you'll be on slide #6
+- On Windows, you'll be on slide #1
+
+You can work around this PC limitation by using the `Specific Slide` action with a relative slide number of `+1` to move to the next slide. This would move you to slide #6 after the `Clear All` action.
+
+
 ## Stage Display
 Command | Description
 ------- | -----------
@@ -35,9 +73,3 @@ $(propresenter:current_slide) | The number of the active slide (>= 1), or "N/A"
 $(propresenter:total_slides)  | The total number of slides in the current document, or "N/A" if unknown.
 $(propresenter:presentation_name) | The name of the current presentation, or "N/A" if unknown.
 $(propresenter:connection_status) | The current connection status to ProPresenter ("Disconnected" or "Connected").
-
-
-----
-
-
-FOR BEST PERFORMANCE ADD DOCUMENT TO PLAYLIST (propresenter like to dump loads of info down the connection if you use it directly from the library)

documentation/images/specific-slide.png

@@ -331,12 +331,20 @@ instance.prototype.actions = function(system) {
 			label: 'Specific Slide',
 			options: [
 				{
-					 type: 'textinput',
-					 label: 'Slide Number',
-					 id: 'slide',
-					 default: 1,
-					 regex: self.REGEX_SIGNED_NUMBER
-				}
+					type: 'textinput',
+					label: 'Slide Number',
+					id: 'slide',
+					default: 1,
+					regex: self.REGEX_SIGNED_NUMBER
+				},
+				{
+					type: 'textinput',
+					label: 'Presentation Path',
+					id: 'path',
+					default: '',
+					tooltip: 'See the README for more information',
+					regex: '/^$|^\\d+$|^\\d+(\\.\\d+)*:\\d+$/'
+				},
 			]
 		},
 		'clearall': { label: 'Clear All' },
@@ -393,21 +401,40 @@ instance.prototype.action = function(action) {
 			break;
 
 		case 'slideNumber':
-			var index = parseInt(opt.slide) - 1;
+			var index = self.currentState.internal.slideIndex;
+
+			if(opt.slide[0] === '-' || opt.slide[0] === '+') {
+				// Move back/forward a relative number of slides.
+				index += parseInt(opt.slide.substring(1), 10) * ((opt.slide[0] === '+') ? 1 : -1);
+				index = Math.max(0, index);
+			} else {
+				// Absolute slide number. Convert to an index.
+				index = parseInt(opt.slide) - 1;
+			}
 
 			if(index < 0) {
 				// Negative slide indexes are invalid. In such a case use the current slideIndex.
-				// This allows the "Specific Slide", when set to 0 (index is -1), to trigger the
-				//  current slide again. Can be used to bring back a slide after using an action
-				//  like 'clearAll' or 'clearText'. 
+				// This allows the "Specific Slide", when set to 0 (thus the index is -1), to
+				//  trigger the current slide again. Can be used to bring back a slide after using
+				//  an action like 'clearAll' or 'clearText'. 
 				index = self.currentState.internal.slideIndex;
 			}
 
+			var presentationPath = self.currentState.internal.presentationPath;
+			if(opt.path.match(/^\d+$/) !== null) {
+				// Is a relative presentation path. Refers to the current playlist, so extract it
+				//	from the current presentationPath and append the opt.path to it.
+				presentationPath = presentationPath.split(':')[0] + ':' + opt.path;
+			} else if (opt.path !== '') {
+				// Use the path provided. The option's regex validated the format.
+				presentationPath = opt.path;
+			}
+
 			cmd = JSON.stringify({
 				action: "presentationTriggerIndex",
 				slideIndex: index,
 				// Pro 6 for Windows requires 'presentationPath' to be set.
-				presentationPath: self.currentState.internal.presentationPath
+				presentationPath: presentationPath
 			});
 			break;
 
@@ -504,7 +531,7 @@ instance.prototype.onWebSocketMessage = function(message) {
 		case 'presentationSlideIndex':
 			// Update the current slide index.
 			var slideIndex = parseInt(objData.slideIndex, 10);
-			
+
 			self.currentState.internal.slideIndex = slideIndex;
 			self.updateVariable('current_slide', slideIndex + 1);
 			break;