Provide experimental orientation lock option

#375

www/index.html

@@ -771,7 +771,7 @@
                             <h4 class="panel-group-heading">Display settings</h4>
                             <div class="column">
                                 <div id="displaySettingsDiv" class="panel panel-info" style="clear: left;">
-                                    <div class="panel-heading">Display size and theme</div>
+                                    <div class="panel-heading">Display size, theme and orientation</div>
                                     <div class="panel-body">
                                         <div class="row">
                                             <div class="col-sm-12">
@@ -818,7 +818,13 @@
                                                     <span class="checkmark"></span>
                                                     <b>Fix UI bug with secondary displays</b> (increases load and resize time, turn off if not needed)
                                                 </label>
-
+                                                <b title="Attempt to lock the display orientation (intended for mobile, if the app is installed: may not work in other contexts).">Attempt to lock display orientation:</b>
+                                                <select title="Attempt to lock the display orientation (intended for mobile, if the app is installed: may not work in other contexts). 'Natural' attempts to match the orientation of the underlying operating system." name="lockDisplayOrientation" id="lockDisplayOrientationDrop" class="dropdown">
+                                                    <option value="">Unlocked</option>
+                                                    <option value="natural">Natural</option>
+                                                    <option value="portrait">Portrait</option>
+                                                    <option value="landscape">Landscape</option>
+                                                </select>
                                             </div>
                                         </div>
                                     </div>

www/js/app.js

@@ -1380,6 +1380,37 @@ define(['jquery', 'zimArchiveLoader', 'uiUtil', 'util', 'utf8', 'cache', 'images
             settingsStore.setItem('hideActiveContentWarning', params.hideActiveContentWarning, Infinity);
             refreshCacheStatus();
         });
+        // Run lockDisplayOrientation on startup
+        if (params.lockDisplayOrientation) {
+            uiUtil.lockDisplayOrientation(params.lockDisplayOrientation);
+            document.getElementById('lockDisplayOrientationDrop').value = params.lockDisplayOrientation;
+        }
+        document.getElementById('lockDisplayOrientationDrop').addEventListener('change', function (event) {
+            var that = this;
+            var message = event.target.value ? ('<p>Attempting to set the orientation lock to: ' + event.target.value + '</p>') : '<p>Attempting to clear the orientation lock.</p>';
+            if (event.target.value) message += '<p><i>Please be aware that this setting may only work in mobile contexts where the app is installed or in standalone mode.</i></p>'
+                return uiUtil.lockDisplayOrientation(event.target.value).then(function (rtn) {
+                    if (rtn === 'unsupported') {
+                        uiUtil.systemAlert('It appears that the Screen Orientation Lock API is not supported on this device!');
+                    } else {
+                        params.lockDisplayOrientation = event.target.value || '';
+                        settingsStore.setItem('lockDisplayOrientation', params.lockDisplayOrientation, Infinity);
+                        that.value = params.lockDisplayOrientation || '';
+                    }
+                }).catch(function (err) {
+                    // Note that in desktop contexts, the API might reject, but could still work
+                    if (err.name === 'NotSupportedError') {
+                        params.lockDisplayOrientation = event.target.value || '';
+                        settingsStore.setItem('lockDisplayOrientation', params.lockDisplayOrientation, Infinity);
+                        that.value = params.lockDisplayOrientation || '';
+                        if (params.lockDisplayOrientation) uiUtil.systemAlert('<p>The Screen Orientation Lock API returned the following error, but this is expected on Desktop devices.</p>' + 
+                            "<p>If the app is installed, and it doesn't work, please reset this manually to 'Unlocked' or try a different setting.</p>");
+                    } else {
+                        uiUtil.systemAlert('There was an error setting the requested orientation: ' + err.toString());
+                        that.value = params.lockDisplayOrientation;
+                    }
+                });
+        })
         document.getElementById('debugLibzimASMDrop').addEventListener('change', function (event) {
             var that = this;
             var message = '<p>App will reload to apply the new setting.</p>'
@@ -1395,7 +1426,7 @@ define(['jquery', 'zimArchiveLoader', 'uiUtil', 'util', 'utf8', 'cache', 'images
                     that.value = params.debugLibzimASM || '';
                 }
             });
-        })
+        });
         $('input:checkbox[name=openExternalLinksInNewTabs]').on('change', function () {
             params.openExternalLinksInNewTabs = this.checked ? true : false;
             settingsStore.setItem('openExternalLinksInNewTabs', params.openExternalLinksInNewTabs, Infinity);

www/js/init.js

@@ -130,6 +130,7 @@ params.localUWPSettings = /UWP/.test(params.appType) ? Windows.Storage.Applicati
 appstate['target'] = 'iframe'; // The target for article loads (this should always be 'iframe' initially, and will only be changed as a result of user action)
 params['mapsURI'] = getSetting('mapsURI') || (/UWP|Windows/.test(params.appType) ? 'bingmaps:' : 'https://www.openstreetmap.org/'); // Protocol with colon ('bingmaps:') or URL with final slash ('https://www.openstreetmap.org/')
 params['debugLibzimASM'] = getSetting('debugLibzimASM'); // 'wasm|asm' Forces use of wasm or asm for libzim decoder. You can also set this as an override URL querystring e.g. ?debugLibzimASM=wasm;
+params['lockDisplayOrientation'] = getSetting('lockDisplayOrientation'); // 'portrait|landscape' (or empty for no lock)
 params['noHiddenElementsWarning'] = getSetting('noHiddenElementsWarning') !== null ? getSetting('noHiddenElementsWarning') : false; // A one-time warning about Hidden elements display
 
 // Apply any override parameters in querystring (done as a self-calling function to avoid creating global variables)

www/js/lib/uiUtil.js

@@ -993,6 +993,30 @@ define(rqDef, function(util) {
         });
     }
 
+    /**
+     * Attempts to lock the display orientation using the Screen Orientation Lock API
+     * @param {string} val A valid value in the API, e.g. '', 'natural', 'portrait', 'landscape' 
+     * @returns 
+     */
+    function lockDisplayOrientation(val) {
+        if (screen && screen.orientation && screen.orientation.lock) {
+            if (val) {
+                return screen.orientation.lock(val).then(function () {
+                    console.log(val ? ('Display orientation locked to ' + val) : 'Display orientation unlocked.');
+                }).catch(function (error) {
+                    console.warn('Error locking display orientation (but in some contexts, it may have worked anyway)', error);
+                });
+            } else {
+                screen.orientation.unlock();
+                return Promise.resolve();
+            }
+        } else {
+            console.warn('The screen.orientation.lock API is not supported on this device!');
+            return Promise.resolve('unsupported');
+        }
+    }
+    
+
     /**
      * Finds the closest <a> or <area> enclosing tag of an element.
      * Returns undefined if there isn't any.
@@ -1048,6 +1072,7 @@ define(rqDef, function(util) {
         extractHTML: extractHTML,
         checkServerIsAccessible: checkServerIsAccessible,
         initTouchZoom: initTouchZoom,
+        lockDisplayOrientation: lockDisplayOrientation,
         reportAssemblerErrorToAPIStatusPanel: reportAssemblerErrorToAPIStatusPanel,
         reportSearchProviderToAPIStatusPanel: reportSearchProviderToAPIStatusPanel,
         warnAndOpenExternalLinkInNewTab: warnAndOpenExternalLinkInNewTab,