Add support for data-state-captions and data-state-descriptions

terrill · terrill · commit 013f5ece5093 · 2022-02-05T13:46:34.000-08:00
diff --git a/README.md b/README.md
@@ -242,6 +242,7 @@ The following attributes are supported on both the `<audio>` and `<video>` eleme
 #### Captions
 
 -   **data-captions-position** - optional; specify default position of captions relative to the video (either "below" or "overlay"; "below" is the default if not specified). Users can override this setting in Captions Preferences.
+-   **data-state-captions** - optional; "on" or "off". Captions are on by default if they're available, but this allows website owners to override that setting. If users enable captions, their preference will be saved in a cookie, and that will override the default setting on future visits.
 
 #### Transcript
 
@@ -383,7 +384,7 @@ available, add a **data-desc-src** attribute to the `<source>` element for
 that video. The value of this attribute is a path pointing to the
 described version of the video. With this method, the described version
 of the video can be played instead of the non-described version, and the
-two versions can be swapped with clicking the "D" button on the
+two versions can be swapped with clicking the "Descriptions" button on the
 controller.
 
 If descriptions are available using either of the above methods, a
@@ -406,6 +407,9 @@ by screen readers or browsers  (for example, if the sole video source is a descr
 In such cases, use **data-descriptions-audible="false"** to prevent browsers and screen readers 
 from announcing the description text. 
 
+If description is available through either of the above methods, it is off by default and users must enable it using the "Descriptions" button on the player control. Website owners can override   
+this setting and change the default state to "on" using **data-state-descriptions="on"**. If users have turned descriptions off on the same website, their preference will be saved in a cookie, and that will override the default setting on future visits.
+
 #### Sign language
 
 Sign language translation is supported in a separate video player,
diff --git a/build/ableplayer.dist.js b/build/ableplayer.dist.js
@@ -166,14 +166,7 @@ var AblePlayerInstances = [];
 		else {
 			this.useChaptersButton = true;
 		}
-
-		if ($(media).data('use-descriptions-button') !== undefined && $(media).data('use-descriptions-button') === false) {
-			this.useDescriptionsButton = false;
-		}
-		else {
-			this.useDescriptionsButton = true;
-		}
-
+		
 		// Control whether text descriptions are read aloud 
 		// set to "false" if the sole purpose of the WebVTT descriptions file
 		// is to integrate text description into the transcript
@@ -204,6 +197,22 @@ var AblePlayerInstances = [];
 			this.descReader = 'browser';
 		}
 
+		// Default state of captions and descriptions 
+		// This setting is overridden by user preferences, if they exist 
+		// values for data-state-captions and data-state-descriptions are 'on' or 'off' 
+		if ($(media).data('state-captions') == 'off') {
+			this.defaultStateCaptions = 'off';
+		}
+		else {
+			this.defaultStateCaptions = 'on'; // on by default
+		}
+		if ($(media).data('state-descriptions') == 'on') {
+			this.defaultStateDescriptions = 'on';
+		}
+		else {
+			this.defaultStateDescriptions = 'off'; // off by default
+		}
+
 		// Headings
 		// By default, an off-screen heading is automatically added to the top of the media player
 		// It is intelligently assigned a heading level based on context, via misc.js > getNextHeadingLevel()
@@ -5497,9 +5506,18 @@ var AblePlayerInstances = [];
 			if (this.prefCaptions === 1) { 
 				this.captionsOn = true; 
 			}
-			else { 
+			else if (this.prefCaptions === 0) { 
 				this.captionsOn = false; 
 			}
+			else { 
+				// user has no prefs. Use default state. 
+				if (this.defaultStateCaptions === 'on')	{ 			
+					this.captionsOn = true; 
+				}
+				else { 
+					this.captionsOn = false; 
+				}
+			}
 		}
 		else { 
 			this.hasCaptions = false; 
@@ -7202,6 +7220,7 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
 		// In the latter two scendarios, this.refreshingDesc == true via control.js > handleDescriptionToggle()
 
 		// The following variables are applicable to delivery of description:
+		// defaultStateDescriptions == 'on' or 'off', defined by website owner (overridden by prefDesc) 
 		// prefDesc == 1 if user wants description (i.e., Description button is on); else 0
 		// prefDescPause == 1 to pause video when description starts; else 0
 		// prefDescVisible == 1 to visibly show text-based description area; else 0
@@ -7259,12 +7278,21 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
 
 		// Set the default state of descriptions
 		if (this.descMethod) { 
-			if (this.prefDesc) { 
+			if (this.prefDesc === 1) { 
 				this.descOn = true; 
 			}
-			else { 
+			else if (this.prefDesc === 0) { 
 				this.descOn = false; 
 			}
+			else { 				
+				// user has no prefs. Use default state. 
+				if (this.defaultStateDescriptions === 'on')	{ 			
+					this.descOn = true; 
+				}
+				else { 
+					this.descOn = false; 
+				}
+			}
 		}
 		else { 			
 			this.descOn = false;
diff --git a/build/ableplayer.js b/build/ableplayer.js
@@ -166,14 +166,7 @@ var AblePlayerInstances = [];
 		else {
 			this.useChaptersButton = true;
 		}
-
-		if ($(media).data('use-descriptions-button') !== undefined && $(media).data('use-descriptions-button') === false) {
-			this.useDescriptionsButton = false;
-		}
-		else {
-			this.useDescriptionsButton = true;
-		}
-
+		
 		// Control whether text descriptions are read aloud 
 		// set to "false" if the sole purpose of the WebVTT descriptions file
 		// is to integrate text description into the transcript
@@ -204,6 +197,22 @@ var AblePlayerInstances = [];
 			this.descReader = 'browser';
 		}
 
+		// Default state of captions and descriptions 
+		// This setting is overridden by user preferences, if they exist 
+		// values for data-state-captions and data-state-descriptions are 'on' or 'off' 
+		if ($(media).data('state-captions') == 'off') {
+			this.defaultStateCaptions = 'off';
+		}
+		else {
+			this.defaultStateCaptions = 'on'; // on by default
+		}
+		if ($(media).data('state-descriptions') == 'on') {
+			this.defaultStateDescriptions = 'on';
+		}
+		else {
+			this.defaultStateDescriptions = 'off'; // off by default
+		}
+
 		// Headings
 		// By default, an off-screen heading is automatically added to the top of the media player
 		// It is intelligently assigned a heading level based on context, via misc.js > getNextHeadingLevel()
@@ -5497,9 +5506,18 @@ var AblePlayerInstances = [];
 			if (this.prefCaptions === 1) { 
 				this.captionsOn = true; 
 			}
-			else { 
+			else if (this.prefCaptions === 0) { 
 				this.captionsOn = false; 
 			}
+			else { 
+				// user has no prefs. Use default state. 
+				if (this.defaultStateCaptions === 'on')	{ 			
+					this.captionsOn = true; 
+				}
+				else { 
+					this.captionsOn = false; 
+				}
+			}
 		}
 		else { 
 			this.hasCaptions = false; 
@@ -7202,6 +7220,7 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
 		// In the latter two scendarios, this.refreshingDesc == true via control.js > handleDescriptionToggle()
 
 		// The following variables are applicable to delivery of description:
+		// defaultStateDescriptions == 'on' or 'off', defined by website owner (overridden by prefDesc) 
 		// prefDesc == 1 if user wants description (i.e., Description button is on); else 0
 		// prefDescPause == 1 to pause video when description starts; else 0
 		// prefDescVisible == 1 to visibly show text-based description area; else 0
@@ -7259,12 +7278,21 @@ if (thisObj.useTtml && (trackSrc.endsWith('.xml') || trackText.startsWith('<?xml
 
 		// Set the default state of descriptions
 		if (this.descMethod) { 
-			if (this.prefDesc) { 
+			if (this.prefDesc === 1) { 
 				this.descOn = true; 
 			}
-			else { 
+			else if (this.prefDesc === 0) { 
 				this.descOn = false; 
 			}
+			else { 				
+				// user has no prefs. Use default state. 
+				if (this.defaultStateDescriptions === 'on')	{ 			
+					this.descOn = true; 
+				}
+				else { 
+					this.descOn = false; 
+				}
+			}
 		}
 		else { 			
 			this.descOn = false;
diff --git a/build/ableplayer.min.js b/build/ableplayer.min.js
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ableplayer",
-  "version": "4.4.16",
+  "version": "4.4.17",
   "description": "fully accessible HTML5 media player",
   "homepage": "http://ableplayer.github.io/ableplayer",
   "bugs": "https://github.com/ableplayer/ableplayer/issues",
diff --git a/scripts/ableplayer-base.js b/scripts/ableplayer-base.js
@@ -166,14 +166,7 @@ var AblePlayerInstances = [];
 		else {
 			this.useChaptersButton = true;
 		}
-
-		if ($(media).data('use-descriptions-button') !== undefined && $(media).data('use-descriptions-button') === false) {
-			this.useDescriptionsButton = false;
-		}
-		else {
-			this.useDescriptionsButton = true;
-		}
-
+		
 		// Control whether text descriptions are read aloud 
 		// set to "false" if the sole purpose of the WebVTT descriptions file
 		// is to integrate text description into the transcript
@@ -204,6 +197,22 @@ var AblePlayerInstances = [];
 			this.descReader = 'browser';
 		}
 
+		// Default state of captions and descriptions 
+		// This setting is overridden by user preferences, if they exist 
+		// values for data-state-captions and data-state-descriptions are 'on' or 'off' 
+		if ($(media).data('state-captions') == 'off') {
+			this.defaultStateCaptions = 'off';
+		}
+		else {
+			this.defaultStateCaptions = 'on'; // on by default
+		}
+		if ($(media).data('state-descriptions') == 'on') {
+			this.defaultStateDescriptions = 'on';
+		}
+		else {
+			this.defaultStateDescriptions = 'off'; // off by default
+		}
+
 		// Headings
 		// By default, an off-screen heading is automatically added to the top of the media player
 		// It is intelligently assigned a heading level based on context, via misc.js > getNextHeadingLevel()
diff --git a/scripts/description.js b/scripts/description.js
@@ -9,6 +9,7 @@
 		// In the latter two scendarios, this.refreshingDesc == true via control.js > handleDescriptionToggle()
 
 		// The following variables are applicable to delivery of description:
+		// defaultStateDescriptions == 'on' or 'off', defined by website owner (overridden by prefDesc) 
 		// prefDesc == 1 if user wants description (i.e., Description button is on); else 0
 		// prefDescPause == 1 to pause video when description starts; else 0
 		// prefDescVisible == 1 to visibly show text-based description area; else 0
@@ -66,12 +67,21 @@
 
 		// Set the default state of descriptions
 		if (this.descMethod) { 
-			if (this.prefDesc) { 
+			if (this.prefDesc === 1) { 
 				this.descOn = true; 
 			}
-			else { 
+			else if (this.prefDesc === 0) { 
 				this.descOn = false; 
 			}
+			else { 				
+				// user has no prefs. Use default state. 
+				if (this.defaultStateDescriptions === 'on')	{ 			
+					this.descOn = true; 
+				}
+				else { 
+					this.descOn = false; 
+				}
+			}
 		}
 		else { 			
 			this.descOn = false;
diff --git a/scripts/track.js b/scripts/track.js
@@ -263,9 +263,18 @@
 			if (this.prefCaptions === 1) { 
 				this.captionsOn = true; 
 			}
-			else { 
+			else if (this.prefCaptions === 0) { 
 				this.captionsOn = false; 
 			}
+			else { 
+				// user has no prefs. Use default state. 
+				if (this.defaultStateCaptions === 'on')	{ 			
+					this.captionsOn = true; 
+				}
+				else { 
+					this.captionsOn = false; 
+				}
+			}
 		}
 		else { 
 			this.hasCaptions = false; 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "ableplayer",`
`3`		`- "version": "4.4.16",`
	`3`	`+ "version": "4.4.17",`
`4`	`4`	`"description": "fully accessible HTML5 media player",`
`5`	`5`	`"homepage": "http://ableplayer.github.io/ableplayer",`
`6`	`6`	`"bugs": "https://github.com/ableplayer/ableplayer/issues",`