@signageos/front-applet 4.11.0

package/docs/README.md

@@ -0,0 +1,5 @@
+# Documentation
+
+These files are build and downloaded by the official repository of [signageOS Documentation](https://gitlab.com/signageos/documentation). 
+**Please observe the format that is written in [Contribution Guide](https://gitlab.com/signageos/documentation/-/blob/master/CONTRIBUTING.md).**
+

package/docs/js-api/js-api-introduction.md

@@ -0,0 +1,73 @@
+---
+title:  Api Home
+author: Josef Kral
+date:   4.2.2018
+type:   rest-api
+tags:
+- rest_api
+- js_api
+- api
+description: "[Content JS API] General introduction to signageOS JS API"
+---
+# Applet Javascript API
+
+Applet JS API gives you **full control over the devices** with a standardized interface. 
+You can use the same functions across all devices with the same result. Applet JS API is available automatically within your Applet out-of-the-box.
+
+Applet JS API supports content-playback features and device management features.
+
+### About signageOS APIs
+
+In signageOS there are 2 main groups of APIs:
+- `Client-side` - JS API available for both **signageOS Open** and signageOS Platform plans
+- `Server-side` - REST API available in **signageOS Platform plan only**
+
+::: alert alert--tip
+All APIs are standardized and available across all [supported devices](/category/supported-devices-guides).
+:::
+
+## Content-playback APIs
+Content-playback API is an API for managing content on screen. 
+
+::: table-responsive
+| Domain | Description |
+| ------ | ----------- |
+| **[Basic information](/api/js/content/js-applet-basics)** | General information required to use the signageOS JS API |
+| [Applet Resources](/api/js/content/js-applet-resources) | Pre-load necessary files required by your HTML5 player/Applet |
+| [Display](/api/js/content/js-display) | Query features supported by the display |
+| [Browser](/api/js/content/js-browser) | Opening managed web-browser on Android devices inc. whitelisting, blacklisting and other features |
+| [Command](/api/js/content/js-command) | Sending business or technical logs through signageOS in secured offline-ready way |
+| [File system](/api/js/content/js-file-system) | Full-featured file system API including ZIP and folder management |
+| [Hardware](/api/js/content/js-hardware) | Hardware-specific APIs like LED lights on Philips 10BDL |
+| [Serial](/api/js/content/js-hardware-serial) | Control external devices via serial |
+| [Inputs](/api/js/content/js-input) | Controller inputs like IR remote unified under one API |
+| [Fonts](/api/js/content/js-loading-fonts) | Make it easy to load additional fonts into SoC devices |
+| [Synchronized playback](/api/js/content/js-sync-playback) | API for creating synced playback and videowalls  |
+| [Timings](/api/js/content/js-timing) | Managing Timing/Applet switching from JS  |
+| [Video Inputs aka PiP](/api/js/content/js-video-inputs-internal-ports) | Show HDMI/DP/VGA as a part of your content via PiP feature |
+| [Video Playback](/api/js/content/js-video) | Playing accelerated gapless videos via native video player |
+| [Video Streams](/api/js/content/js-video-stream) | Playing video streams (RTSP, HLS, UDP) via native video player  |
+| [Sensors](/api/js/content/js-sensors) | Using sensors and IoT devices in your application  |
+| [Monitors](/api/js/content/js-monitors) | Information about monitors |
+:::
+
+## Device management APIs
+Device management API is for managing, updating firmware, and other settings on the device.
+
+::: table-responsive
+| Domain | Description |
+| ------ | ----------- |
+| [Management](/api/js/management/1-js-management) | Information about the device and power action like Reboot, Restart,.. |
+| [Firmware](/api/js/management/2-js-management-firmware) | Get FW version and upgrade FW from remote location |
+| [Remote Control](/api/js/management/3-js-management-remote-control) | Manage IR Remote control functionality |
+| [Display](/api/js/management/4-js-management-power) | Manage display power - timers, restart and reboot |
+| [Screen](/api/js/management/5-js-management-screen) | Manage brightness, orientation and resolution, display on/off |
+| [Time](/api/js/management/6-js-management-time) | Set time, timezone and get current settings |
+| [Volume](/api/js/management/7-js-management-volume) | Control system volume level |
+| [Package](/api/js/management/8-js-management-package) | Install and manage packages |
+| [Debug](/api/js/management/9-js-management-debug) | Enable/disable debug mode |
+| [Application](/api/js/management/10-js-management-application) | Get application version and upgrade application from remote location |
+| [Network](/api/js/management/11-js-management-network) | Manage network settings |
+| [Security](/api/js/management/12-js-management-security) | Control system security (PIN code) |
+| [Wi-Fi](/api/js/management/13-js-management-wifi) | Manage Wi-Fi |
+:::

package/docs/js-api/js-applet-basics.md

@@ -0,0 +1,294 @@
+---
+title:  Applet Basics
+author: Miroslav Behina
+date:   22.11.2018
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- js_api
+description: "[Content JS API] This thread contains basic methods of every Applet used to load necessary configuration or device identifications and how to create Applet."
+---
+
+# Applet Basics
+
+This thread contains basic methods of every Applet used to load necessary configuration or device identifications and how to create Applet.
+
+## All methods and properties
+::: table-responsive
+| Methods/Property  | Description | Supported since |
+| ----------------- | ----------- | :---------------: |
+| `onReady()`         | This method will wait until sOS object library and all dependencies are ready to be used. | 1.0.0 |
+| `restore()`         | Clear all previously played videos, streams, clear display view. | 1.0.0 |
+| `appletVersion`  | Returns current Applet version | JS API `4.5.0`, Front-display `7.8.0`|
+:::
+
+## Starting Applet
+
+Your applet logic should be started **after sOS object is loaded and ready**. To start your applet you can use this example snippet.
+
+### Javascript example:
+``` javascript
+/* 
+CLI generated Applet 
+*/
+sos.onReady().then(async function () {
+  startYourApplet(); // Example method to run
+  // Any other code
+}
+
+/* 
+Deprecated single file Applet options
+*/
+
+// option A
+window.addEventListener('sos.loaded', () => {
+  sos.onReady().then(() => {
+    startYourApplet(); // Example method to run
+    // Any other code
+  });
+});
+
+// option B
+async function startApplet() {
+			await sos.onReady();
+      // Any other code
+}
+window.addEventListener('sos.loaded', startApplet);
+```
+
+After sOS object is ready, there are global properties available, which can be used for Applet customization and device identification.
+
+### Javascript syntax:
+```javascript
+// Authentication hash string to secure access to device resources in REST API
+console.log(sos.authHash);
+ 
+// Parsed JSON object passed to Timing for current applet & current device together
+console.log(sos.config);
+```
+
+## onReady()
+This method will wait until sOS object library and all dependencies are ready to be used.
+
+::: alert alert--danger
+Every Applet must contain this method, otherwise it won't work.
+:::
+
+### Javascript example:
+```javascript
+/* 
+CLI generated Applet 
+*/
+sos.onReady().then(async function () {
+  console.log('sos is ready', sos); // Print sOS object into console
+    // Any other methods to prepare your content and applet
+}
+
+/* 
+Deprecated single file Applet options
+*/
+window.addEventListener('sos.loaded',() => {
+  sos.onReady().then(() => {
+    console.log('sos is ready', sos); // Print sOS object into console
+    // Any other methods to prepare your content and applet
+  });
+});
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/restore">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of Applet for basic start</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## restore()
+The typical case of usage for digital signage is playing a loop with some specified duration. This method should be called always when the loop is changed. It will clear all previously played videos, streams, clear display views, and notify for garbage collection.  
+It stops all video playback and clears out the memory. The following function should be triggered **only** in a case the whole playback needs to be restarted as it's completely switching the playback 'loop/playlist'.
+
+### Javascript example:
+```javascript
+/* 
+CLI generated Applet 
+*/
+sos.onReady().then(async function () {
+  console.log('sos is ready', sos);
+  // Any other methods to prepare, load and run content on screen
+  sos.restore();
+}
+
+/* 
+Deprecated single file Applet options
+*/
+window.addEventListener('sos.loaded', () => {
+  sos.onReady().then(() => {
+    console.log('sos is ready', sos);
+    // Any other methods to prepare, load and run content on screen
+    sos.restore();
+  });
+});
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/restore">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of Applet with restore() method</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## appletVersion
+This property returns current active Applet version.
+
+### Javascript example:
+
+```javascript
+/* 
+CLI generated Applet 
+*/
+sos.onReady().then(async function () {
+  console.log('Your applet version is ' + sos.appletVersion));
+}
+
+/* 
+Deprecated single file Applet options
+*/
+window.addEventListener('sos.loaded',() => {
+  sos.onReady().then(() => console.log('Your applet version is ' + sos.appletVersion));
+});
+```
+
+## Custom variables in Applet
+
+You can pass CUSTOM key-value variables to the Applet. To do that, add your values as a Timing configuration (over Box of [Timings API](/api/rest/timing/3-timing-post-one)). Then you can access your values via `sos.config` object.
+
+```javascript
+// Parsed JSON object passed to Timing for current applet & current device together
+console.log(sos.config.mySecretID);
+console.log(sos.config.imgUrl);
+```
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="/knowledge-base/applet-custom-config-on-device">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fas fa-hand-point-right svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Custom variables in Applet</h3>
+                <div class="wide-box__description">How to pass custom variables and cofiguration to your Applet</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## Applet JS API version
+
+Each feature has “Supported since” that states for the Applet JS API version. The Applet JS API component is called Front-Applet and its version can be selected under the Applet editor.
+
+## Capabilities
+
+Even tough we do our best to support as many features as possible on every platform, it's not possible to use certain features on certain platforms.
+That's why we also provide a capabilities API that allows you to check, if the particular device supports a feature before you try to use it.
+It's recommended that you always include capability checks in your code to prevent unexpected behavior or errors in your application.
+
+There are two kinds of capabilities - display and management.
+
+### Display capabilities
+
+Display capabilities refer to the capabilities of the display in terms of content, playback, peripherals, etc.
+
+::: table-responsive
+| Capability                     | Description                                                                               |
+| ------------------------------ | ----------------------------------------------------------------------------------------- |
+| `FILE_SYSTEM_EXTERNAL_STORAGE` | Device file system supports [external storage](/api/js/content/js-file-system) (i.e. flash drives)                          |
+| `FILE_SYSTEM_FILE_CHECKSUM`    | Device is can [calculate a file checksum](/api/js/content/js-file-system#getfilechecksum) |
+| `VIDEO_4K`                     | Device is capable of [playing 4K video](/api/js/content/js-video)                                                     |
+| `SERIAL`                       | Device supports communication with peripherals over [serial](/api/js/content/js-hardware-serial)                                |
+:::
+
+#### Javascript example:
+
+```javascript
+if (await sos.display.supports('VIDEO_4K')) {
+	// play 4K video
+}
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/capabilities-content">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of Content Capabilities</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+
+### Management capabilities
+
+Management capabilities refer to the capabilities of the display's internal state management.
+
+::: table-responsive
+| Capability                     | Description                                                                               |
+| ------------------------------ | ----------------------------------------------------------------------------------------- |
+| `BATTERY_STATUS` | Device can [report its battery status](/api/js/management/1-js-management#getbatterystatus). |
+| `WIFI` | Device can [connect to a Wi-Fi](/api/js/management/13-js-management-wifi#connect). |
+| `WIFI_SCAN` | Device can [scan surrounding Wi-Fi devices](/api/js/management/13-js-management-wifi#scandevices). |
+| `WIFI_AP` | Device is capable of [becoming a Wi-Fi endpoint](/api/js/management/13-js-management-wifi#enableap) that other devices can connect to. |
+| `SET_BRIGHTNESS` | Device can change its [screen brightness](/api/js/management/5-js-management-screen#setbrightness). |
+| `SET_TIME` | Device can change its [time settings](/api/js/management/6-js-management-time). |
+| `NTP_TIME` | Device can [synchronize its time with an NTP server](/api/js/management/6-js-management-time#setntp). |
+| `PACKAGE_INSTALL` | It's possible to [install additional packages](/api/js/management/8-js-management-package) on the device, managed by signageOS application. |
+| `SET_VOLUME` | Device can change its [audio volume](/api/js/management/7-js-management-volume). |
+| `SET_REMOTE_CONTROL_ENABLED` | Device can [disable control via IR remote](/api/js/management/3-js-management-remote-control) to increase security. |
+:::
+
+```javascript
+if (await sos.management.supports('WIFI')) {
+	// connect to wifi
+}
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/management-js-api/capabilities-management">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of Management Capabilities</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>

package/docs/js-api/js-applet-resources.md

@@ -0,0 +1,172 @@
+---
+title:  Applet Resources
+author: Miroslav Behina
+date:   22.11.2018
+type:   js-api
+tags:
+- applet
+- applet_api
+- api
+- js_api
+description: "[Content JS API] Often there are some JavaScripts and CSS styles necessary to be loaded for your Applet. It can be libraries like jQuery or even your whole application code. For these necessities offline API for saving, storing & loading files are ready."
+---
+
+# Applet Resources
+
+Often there are some JavaScripts and CSS styles necessary to be loaded for your Applet. 
+It can be libraries like jQuery or even your whole application code. For these necessities offline API for saving, storing & loading files are ready.
+
+
+## All methods
+::: table-responsive
+| Methods | Description | Supported since |
+| ------- | ----------- | ------ | :---------------: |
+| `addFile()` | Add single file to Applet before starting it. | 1.0.0 |
+| `addFiles()` | Add files to Applet before starting it. | 1.0.0 |
+| `addFilesSync()` | Add files to Applet before starting it in the set order to prevent race condition. | 1.0.0 |
+:::
+
+### File object
+Every method above, accept single object or array of objects depending by type. Every object **must have** these keys.
+
+::: table-responsive
+| Key | Type | Required | Description |
+| :-----: | :-----: | :----: | ------- |
+| `uri` | String | <div class="red">Yes</div> | URL of file |
+| `uid` | String | <div class="red">Yes</div> | Unique ID in Applet for future manage |
+| `type` | String | <div class="red">Yes</div> | Type of file. Example: `sos.offline.types.javascript`, `sos.offline.types.css`, `sos.offline.types.video` |
+|||| ^^ |
+| `flags` | Array | <div class="red">Yes</div> | Special flag for file |
+| `headers` | Array | <div class="yellow">No</div> |  Authorization headers |
+:::
+
+::: alert alert--info
+* The file URL must point to a file. If your URI leads to a 303 redirect (e.g. from http to http**s**), the API will not work.
+* There are some limitations for [Emulator](knowledge-base/box-emulator-limitations). 
+:::
+
+## addFile()
+Method `addFile()` will allow you to load single resource into applet. If you want to load more resource, use `addFiles()`.
+
+### Javascript Example
+```javascript
+const file = { // File that will be loaded into an applet
+    "uri": "https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js",
+    "uid": "jquery-2.2.4.min.js",
+    "type": sos.offline.types.javascript,
+    "flags": [sos.offline.flags.append(document.body)]
+}
+
+await sos.offline.addFile(file); // And finally load file
+```
+
+## addFiles()
+Method `addFiles()` will allow you to load array of your resources into Applet. Files are load in random order.
+
+### Javascript Example
+```javascript
+const files = [ // Array of files
+	{
+		"uri": "https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js",
+		"uid": "jquery-2.2.4.min.js",
+		"type": sos.offline.types.javascript,
+		"flags": [sos.offline.flags.append(document.body)]
+	},
+	{
+		"uri": "https://signageostest.blob.core.windows.net/test/applet-examples/benchmark-styles.css?v=1.0.0",
+		"uid": "benchmark-styles.css-v1.0.0",
+		"type": sos.offline.types.css,
+		"headers": { "Authorization": "Basic Zm9vOmJhcg==" },
+		"flags": [sos.offline.flags.append(document.head)]
+	}
+];
+
+await sos.offline.addFiles(files);
+```
+
+<div class="row d-flex align-content-stretch force-padding-20">
+    <div class="col-12 d-flex">
+        <a class="wide-box wide-box--white d-flex align-content-stretch widebox-kb-color" target="_blank" href="https://github.com/signageos/applet-examples/blob/master/examples/content-js-api/offline-resources">
+            <div>
+                <div class="wide-box__image d-flex align-items-center">
+                    <i class="fab fa-github svg-black"></i>
+                </div>
+            <div>
+                <h3 class="wide-box__title wide-box__title__small pl-85">Example of Applet that save files and load them in one file</h3>
+                <div class="wide-box__description">Working example on our Github</div>
+            </div>
+            </div>
+        </a>
+    </div>
+</div>
+
+## addFilesSync()
+Method `addFilesSync()` works same as method above, but all files are loaded in correct order. Otherwise, files are loaded in random order by file size.
+
+### Javascript example
+```javascript
+const files = [
+	{
+		"uri": "https://ajax.googleapis.com/ajax/libs/jquery/2.2.4/jquery.min.js",
+		"uid": "jquery-2.2.4.min.js",
+		"type": sos.offline.types.javascript,
+		"flags": [sos.offline.flags.append(document.body)]
+	},
+	{
+		"uri": "https://signageostest.blob.core.windows.net/test/applet-examples/benchmark-styles.css?v=1.0.0",
+		"uid": "benchmark-styles.css-v1.0.0",
+		"type": sos.offline.types.css,
+		"headers": { "Authorization": "Basic Zm9vOmJhcg==" },
+		"flags": [sos.offline.flags.append(document.head)]
+	}
+];
+
+sos.offline.addFilesSync(files).then(() => {
+	console.log('Now you can use jQuery and CSS file');
+	jQuery('#do').something();
+});
+```
+
+## Usage with Typescript
+You can also use all these methods with [signageOS TypeScript](/knowledge-base/dev-tools-cli-typescript).
+
+```typescript
+interface ISaveFile {
+	uid: string;
+	uri: string;
+	type: string;
+	headers?: { [key: string]: string };
+	flags?: IFlag[];
+}
+
+addFile(files: ISaveFile[]): Promise<void>;
+addFiles(files: ISaveFile[]): Promise<void>;
+addFilesSync(files: ISaveFile[]): Promise<void>;
+```
+
+Flags that can be optionally passed to the file object are available in flags property.
+
+```typescript
+interface IFlag {
+	type: 'append';
+	element: IElement;
+}
+```
+
+## Errors
+Although we are doing our best, following errors may occur when working with the Applet Resources.
+
+::: table-responsive
+| Code | Type | Message |
+| ---- | ---- | ------- |
+| 40101 | AppletResourcesError | File needs to be object |
+| 40102 | AppletResourcesError | File UID needs to be defined |
+| 40103 | AppletResourcesError | File flags needs to be Array |
+| 40104 | AppletResourcesError | File flag needs to be object |
+| 40105 | AppletResourcesError | Already loading file: `FILE_NAME` |
+|^^|^^| Your code has probably multiple occurrences of addFile/s methods. |
+| 40106 | AppletResourcesError | Already existing file: `FILE_NAME` |
+|^^|^^| File is already loaded or exists in Applet |
+| 49901 | FileNotFoundError    | File `FILE_ID` was not found |
+|^^|^^| Applet can not get file. URL is invalid. |
+:::