Merge pull request #373 from rdkcentral/release/5.3.0

Release - v5.3.0

Author: michielvandergeest

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v5.3.0
+*16 feb 2023*
+
+- Added Subtitles plugin
+- Added support for overriding the key mappping at runtime (i.e. after the App is launched) (#276)
+- Added support for an optional path at the end of router paths (#362)
+- Added support for plugins to load local JSON files (#360)
+- Fixed a bug related to the Router plugin which results in not setting previous state when "on" data provider is used (#365)
+- Fixed incorrect positioning of the version label (#359)
+- Updated `@metrological/sdk` and `localCookie` NPM package paths
+- Fixed the Router plugin documentation regarding `backtrack` feature (#375)
+
 ## v5.2.0
 
 *20 oct 2022*

docs/_sidebar.md

@@ -2,6 +2,7 @@
 
 - Plugins
   - [Accessibility](/plugins/accessibility.md)
+  - [App](/plugins/app.md)
   - [Utils](/plugins/utils.md)
   - [Storage](/plugins/storage.md)
   - [Settings](/plugins/settings.md)

docs/changelog.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v5.3.0
+*16 feb 2023*
+
+- Added Subtitles plugin
+- Added support for overriding the key mappping at runtime (i.e. after the App is launched) (#276)
+- Added support for an optional path at the end of router paths (#362)
+- Added support for plugins to load local JSON files (#360)
+- Fixed a bug related to the Router plugin which results in not setting previous state when "on" data provider is used (#365)
+- Fixed incorrect positioning of the version label (#359)
+- Updated `@metrological/sdk` and `localCookie` NPM package paths
+- Fixed the Router plugin documentation regarding `backtrack` feature (#375)
+
 ## v5.2.0
 
 *20 oct 2022*

docs/plugins/app.md

@@ -0,0 +1,33 @@
+# App
+
+SDK provides various methods that can be used within the application.
+
+## Available Methods
+
+### overrideKeyMap
+
+This method can be used to merge and override the existing keymap (coming from `settings.json`) by using a custom keymap in runtime. The method will merge all key mappings by overriding the existing key mappings with the new ones when a key is defined in both keymaps.
+
+`keepDuplicates` flag is set to `false` by default, which means duplicated values (like two different keys trigger the `Back` action) will be removed from the final keymap. If `keepDuplicates` is set to `true`, duplicated **values** will be kept in the final keymap.
+
+#### Usage
+
+```js
+const customKeyMap = {
+    13: "Enter",
+    83: "Search"
+}
+
+this.application.overrideKeyMap(customKeyMap) // keepDuplicates = false
+```
+
+or
+
+```js
+this.application.overrideKeyMap(customKeyMap, true) // keepDuplicates = true
+```
+
+#### Parameters
+
+- `customKeyMap` : keymap object
+- `keepDuplicates`: flag to keep duplicated values in the final keymap or not. The default value is `false`.

docs/plugins/router/deeplinking.md

@@ -9,13 +9,13 @@ Deeplinking is an important feature, because:
 * Regular data providing for a specific route is still executed.
 * The configuration object's [boot](configuration.md#boot) key handles any general operations to be executed for a proper functioning of your App.
 
-## Backtracking
+## Backtrack
 
 When a user enters your App via a deeplink, there is technically *no* history available. By default, this would mean that a **Back** key press leads to exiting the App.
 
-On some platforms, this is not the desired behavior. For that reason, the Router plugin supports the *[backtracking](settings.md#backtracking)* functionality.
+On some platforms, this is not the desired behavior. For that reason, the Router plugin supports the *[backtrack](settings.md#backtrack)* functionality.
 
-When this feature is enabled (via the Platform Setting  `Router.backtracking`) and the **Back** key is pressed, the Router will *recursively* remove the last part of the hash, until it finds a valid path to navigate to.
+When this feature is enabled (via the Platform Setting  `Router.backtrack`) and the **Back** key is pressed, the Router will *recursively* remove the last part of the hash, until it finds a valid path to navigate to.
 
 #### NEXT:
 [History](history.md)

docs/plugins/router/navigation.md

@@ -96,6 +96,46 @@ Router.navigate({
 
 This results in: `#player/12/44`
 
+## Optional router path
+
+There might be some cases in which you need a route path with an optional parameter at the end. Normally, you would have to define two different routes to the same component, one with the optional parameter and one without. Starting with Lightning-SDK `v5.3.0`, you can specify an optional router path parameter by adding a `?` suffix to the last parameter name.
+
+Please note that only the last parameter of any path is allowed to be an optional parameter. For example, if you have a route path with three parameters, you can make only the last parameter optional, but not the second parameter.
+
+When we define an optional parameter like this:
+```js
+{
+  path: 'player/:assetId/:playlistId?',
+  component: Player
+  name: 'player'
+}
+```
+
+This will generate two paths internally as below:
+
+```js
+{
+    path: 'player/:assetId/:playlistId'
+    component: Player
+    name: 'player'
+}
+{
+    path: 'player/:assetId',
+    component: Player,
+    name: 'player'
+}
+```
+
+The following example would *not* work because only the last parameter of the path can be optional:
+
+```js
+{
+  path: 'player/:assetId?/:playlistId',
+  component: Player
+  name: 'player'
+}
+```
+
 
 ## isNavigating Method
 

docs/plugins/router/settings.md

@@ -18,7 +18,7 @@ For example:
           "lazyCreate": true,
           "lazyDestroy": true,
           "gcOnUnload": true,
-          "backtracking": true,
+          "backtrack": true,
           "reuseInstance": false,
           "destroyOnHistoryBack": false
         }
@@ -44,9 +44,9 @@ By default, Lazy Destroy is *disabled*. This results in faster navigating back t
 
 If you want to free up texture memory *directly* after a previous page has been destroyed and you do not want to wait for Lightning's (texture) garbage collection, you can set `gcOnUnload` to `true`. This forces a texture garbage collect directly after destroying the page.
 
-### backtracking
+### backtrack
 
-If you want to enable *backtracking* in your app, you set `backtracking` to `true`.
+If you want to enable *backtracking* in your app, you set `backtrack` to `true`.
 
 ### destroyOnHistoryBack
 

docs/plugins/subtitles.md

@@ -0,0 +1,144 @@
+# Subtitles
+
+You can use the *Subtitles* plugin to easily display Subtitles (or Closed Captions) in your App.
+
+The plugin comes with some basic styling of Subtitles and offers the option to customize them, such as font size, colors, and positioning.
+
+> The Subtitles plugins in the Lightning-SDK only offers an API for displaying Subtitles.
+
+> Retrieving subtitles from a video stream or a remote API is not part of the Plugin's functionality as it's very App and / or Platform specific.
+
+## Usage
+
+If you want to display Subtitles in your App, first import the Subtitles plugin from the Lightning SDK:
+
+```js
+import { Subtitles } from '@lightningjs/sdk'
+```
+
+## Available Methods
+
+### show
+
+Sets the visibility of Subtitles to `true`, to display Subtitles.
+
+```js
+Subtitles.show()
+```
+
+### hide
+
+Sets the visibility of Subtitles to `false`, to hide Subtitles.
+
+```js
+Subtitles.hide()
+```
+
+### text
+
+Sets the text of the Subtitles text.
+
+```js
+Subtitles.text('Subtitle Text')
+```
+
+### clear
+
+Clears the text of the Subtitles text.
+
+```js
+Subtitles.clear()
+```
+
+### styles
+
+Sets the styles of the Subtitles text. This is a short hand method for setting the following styles: `fontFamily`, `fontSize`, `fontColor`, `backgroundColor`, `textAlign`. If any of these styles are not set, the default values will be used.
+
+```js
+Subtitles.styles({
+  fontFamily: 'sans-serif',
+  fontSize: 45,
+  fontColor: 0xffffffff,
+  backgroundColor: 0x90000000,
+  textAlign: 'center',
+})
+```
+### fontFamily
+
+Sets the `fontFamily` style of the Subtitles text.
+
+```js
+Subtitles.fontFamily('sans-serif')
+```
+
+### fontSize
+
+Sets the `fontSize` style of the Subtitles text.
+
+```js
+Subtitles.fontSize(50)
+```
+
+### fontColor
+
+Sets the `fontColor` style of the Subtitles text
+
+```js
+Subtitles.fontColor(0xffffffff)
+```
+
+### backgroundColor
+
+Sets the `backgroundColor` style of the Subtitles text
+
+```js
+Subtitles.backgroundColor(0x90000000)
+```
+
+### textAlign
+
+Sets the `textAlign` style of the Subtitles text
+
+```js
+Subtitles.textAlign('center')
+```
+
+### position
+
+Sets the x and y positions of the Subtitles text.
+
+`x` value must be either a number or one of the following options: `'left'`, `'center'`, `'right'`. The default value for `x` is `'center'`.
+
+`y` value must be either a number or one of the following options: `'top'`, `'center'`, `'bottom'`. The default value for `y` is 'bottom'.
+
+```js
+Subtitles.position('center', 'top')
+Subtitles.position(100, 100)
+```
+
+### viewport
+
+Sets the width and height for the viewport of the Subtitles text. The viewport is the area in which the Subtitles text will be displayed. By default, Subtitles assumes the viewport is the same size as the App. If your video player is smaller, you can set the viewport to match the size of the video player to correctly position the Subtitles text.
+
+The first argument is the width of the viewport, the second argument is the height of the viewport.
+
+
+```js
+Subtitles.viewport(854, 480)
+```
+
+### maxWidth
+
+Sets the maximum width of the Subtitles text.
+
+```js
+Subtitles.maxWidth(1200)
+```
+
+### maxLines
+
+Sets the maximum number of lines for the Subtitles text.
+
+```js
+Subtitles.maxLines(2)
+```

index.js

@@ -43,3 +43,4 @@ export { default as TV } from './src/TV'
 export { default as Utils } from './src/Utils'
 export { default as VideoPlayer } from './src/VideoPlayer'
 export { default as Metadata } from './src/Metadata'
+export { default as Subtitles } from './src/Subtitles'