Skip to end of metadata
Go to start of metadata


ComponentController

Extends: Group

Description

The ComponentController component implements the basic default view management. It essentially implements the view stack. Further, the component also handles view to view navigation, back button handling, and showing and closing views. The developer can use ComponentController to call the show() function to add views to the view stack and make them visible. Developers do not need to create ComponentController instances in their channels. This is created on the channel's scene by SGDEX if the scene is extended from BaseScene.

Interface

Fields

FieldTypeDefaultUse
currentViewNode-

Holds the reference to the view that is currently shown

allowCloseChannelOnLastViewBooleanTrueIf true, the channel closes when the back button is pressed or if the previous view set the view's close field to true
allowCloseLastViewOnBackBooleanTrueIf true, the current view is closed, and the user can open another view through the new view's wasClosed callback


Functions

FunctionDescription
showCalled to add a view to the view stack and make it visible

 

Example

Using ComponentController  Expand source

BaseScene

Extends: Scene

Description

As with any other Roku SceneGraph based channel, SGDEX channels implement a main scene that host all other channel views and components; this scene is derived from BaseScene.  BaseScene provides a variety of default functionality. The function show() should be overridden in the channel to implement any view specific initialization.

Interface

Fields

FieldTypeDefaultDescription

ComponentController

Node-

This field holds the ComponentController instance created by SGDEX for use in the channel

Read Only

exitChannelBooleanFalse

Exits channel if set to true

Write Only

themeAssociative array{ }

Theme is used to customize the appearance of all SGDEX views

For common fields, see SGDEXComponent

For view-specific views, refer to:


Theme attributes can be global so that they apply to any view that supports the specific theme attribute. They can also be set at the view level in which case, they apply to that view component type only:

Make All Views Have Red Text  Expand source
Make All Grid View Text Red  Expand source

 

These attributes can also be set on specific view instances. For example, this specific grid is set to have red text:

Use view's theme field to set its theme


The model can also be used to create a hierarchy of themes. For example, the code below makes the text of all views red, globally, except for all grid view instances (this is green). The text color theme attribute is further modified for the specific view2 instance, which the code sets to white.

Because textColor is globally set to red, the detailsView instance will have red text as the theme overrides rides in the hierarchy impact details views.

 Expand source
updateThemeAssociative array{ }

Used to updatethemeattributes. This field can be set to a theme config similar to the original theme field. Only the attributes that need to be changed have to be set

Note: When changing many theme fields, do this withas few updates as possible to prevent frequent redraws

 

Example

Using BaseScene  Expand source

ContentHandler

Extends: Task

Description

Content Handlers are responsible for all content loading tasks in SGDEX. Channels typically extend ContentHandler to implement specific content or data loading tasks. ContentHandlers should implement a function called GetContent(). This function is called by SGDEX, allowing the handler to make application specific API calls or perform other operations to load the content associated with the handler.

Interface

Fields

FieldTypeDefaultDescription
contentNode-Modified in the GetContent() function by adding/updating the Content Nodes being rendered by the associated view
offsetInteger0When working with paged data, offset reflects which page of content SGDEX is expecting to populate using ContentHandler
pageSizeInteger0When working with paged data, pageSize reflects the number of items SGDEX is expecting to populate using ContentHandler
failedBooleanFalse

Indicates if the ContentHandler failed to load the requested content

If GetContent() sets this field to true, SGDEX will try to load the content again using the ContentHandler instance.
Alternatively, the channel can set a new HandlerConfig to the content field. This causes SGDEX to use the new config when it re-tries using the ContentHandler

If the HandlerConfig is not updated, SGDEX will re-use the original one for subsequent tries

HandlerConfigAssociative array{ }Contains a reference to the ContentHandler config

 

Example

Using ContentHandler  Expand source

EntitlementHandler

Extends: Task

Description

Entitlement Handlers are used together with the EntitlementView component to let developers leverage Roku Billing for buildinng a basic SVOD for their channels. The Entitlement Handler is used to let SGDEX know about the subscription products associated with the channel.

The developer can implement a Handler in the channel that extends EntitlementHandler. In this handler, they can override two functions:

  • ConfigureEntitlements(config) [Required]
  • OnPurchaseSuccess(transactionData) [Optional]

For ConfigureEntitlements, the channel can update the config with its own params.

The config should contain the following fields:

config.products [Array] of AAs having fields

  • config.products.code [String]: Product code in ChannelStore
  • config.products.hasTrial [Boolean]: True if the product's trial period has expired

OnPurchaseSuccess is a callback that allows the developer to inject some custom logic on purchase success by overriding this subroutine. The default implementation for this callback is set to taking no action.

Interface

Fields

FieldTypeDefaultDescription
contentNode-The content node from EntitlementView is passed here; the developer can use it in the handler
viewNode-It refers to theEntitlementViewwhere the specific handler was created

 

Example

Using EntitlementHandler  Expand source

RAFHandler

Extends: Task

Description

The RAFHandler component is the SGDEX wrapper for the Roku Ad Framwork (RAF). The developer extends this component in the channel and implements ConfigureRAF(adIface as Object).

They can further implement any desired configuration supported by RAF in ConfigRAF().


Example

Using RAFHandler  Expand source

SGDEXComponent

Extends: Group

Description

This is the base component for all SGDEX views.

Interface

Fields

FieldTypeDefaultDescription
themeAssociative array{ }

Theme is used to set view specific theme fields

To update a value, use updateTheme

For a list of the common attributes for all view, refer to Common theme attributes

Usage

See the theme attribute description in the BaseScene component section above

updateThemeAssociative array{ }

Used to update view specific theme fields

Usage is same as theme field but here, only the field that needs to be updated is set

For global updates, set the updateTheme field on the channel's scene. This assumes the scene is extended from BaseScene

styleString""

Indicates what style to use for a view

The style is view specific

For example, GridView supports standard and hero styles

posterShapeString""Indicates what poster shape to use for the posters rendered on the view
contentNode-

Holds the view content. The content structure is defined by the specific view

closeBooleanFalse

A control field that tells the view manager to close a view

wasClosedBooleanFalseIndicates when a view is closed and removed from the view manager
saveStateBooleanFalseIndicates when a view is hidden, and a new top view is opened
wasShownBooleanFalseIndicates when a view was shown for the first time or restored after the top view was closed

CategoryListView

Extends: SGDEXComponent

Description

CategoryListView represents the SGDEX category list view that has two lists; one for categories and another for the items in the category.

Interface

Fields

FieldTypeDefaultDescription
initialPositionVector2D[0, 0]Indicates where initial focus is set on the itemsList: 1st coordinate = category, 2st coordinate = item in this category
selectedItemVector2D[0, 0]

Array with 2 integers; returns the section and item in the current section that was selected

Read Only

focusedItemInteger0

Returns the currently focused item index (within all categories)

Read Only

focusedItemInCategoryInteger0Returns the currently in focus item index from the current focusedCategory
focusedCategoryInteger0Returns the currently in focus category index
jumpToItemInteger0

Jumps to an item in the items list (within all categories)

This field must be set after setting the content field only

Write Only

animateToItemInteger0

Animates to an item in the items list (within all categories)

Write Only

jumpToCategoryInteger0

Jumps to a category

Write Only

animateToCategoryInteger0

Animates to a category

Write Only

jumpToItemInCategoryInteger0

Jumps to an item in the current category

Write Only

animateToItemInCategoryInteger0

Animates to an item in the current category

Write Only

themeAssociative array{ }

Used to change the color of the grid view elements

Note: Set TextColor and focusRingColor to have a generic theme and only change attributes that would not use it

For all the Possible values of the field, refer to CategoryListView theme attributes

contentNode-

Follows the model below to build a proper content node

Possible fields

Category fields:

FieldDescription
TITLETitle displayed for the category name
CONTENTTYPEMust be set to SECTION
HDLISTITEMICONURLThe image file for the icon to be displayed to the left of the list item label when the list item is not in focus
HDLISTITEMICONSELECTEDURLThe image file for the icon to be displayed to the left of the list item label when the list item is in focus
HDGRIDPOSTERURLThe image file for the icon to be displayed to the left of the section label when the screen resolution is set to HD

Item List fields:

FieldDescription
titleThe title shown
descriptionDescription for an item, maximum 4 lines
hdPosterUrlThe image URL for an item


Example

Using CategoryListView  Expand source

 

VideoView

Extends: SGDEXComponent

Description

VideoView is the SGDEX component is used by channels to play content. It includes a number of different features, including:

  • Playback of a single video or a video playlist;
  • Loading of content via HandlerConfigVideo before playback;
  • Showing endcards view after a video playback ends;
  • Loading of endcard content via HandlerConfigEndcard before the video ends for performance benefit;
  • Handling of RAF - handlerConfigRAF is set in the content node;
  • Video.state field is aliased to make tracking of states easier;
  • Theme support

Interface

Fields

FieldTypeDefaultDescription
endcardCountdownTimeInteger10

Returns the endcard countdown time

Indicates how long the endcard is shown for before the next video starts playing

endcardLoadTimeInteger10Returns the time at which the video ends so that the endcard content can start loading
alwaysShowEndcardsBooleanFalseConfig that indicates when the VideoView shows the endcard with the default next item and the repeat button even if the content getter is not specified by the user
isContentListBooleanTrueIndicates if the content is a playlist or an individual item
jumpToItemInteger0

Jumps to an item in the playlist

This field must be set after setting the content field 

controlString""

Controls "play" and "prebuffer" and starts loading content from Content Getter

If any other control is defined, itissetdirectlyto the video node

endcardTriggerBooleanFalseTrigger to notify channel that endcard loading has started
currentIndexInteger-1Indicates what is the index of the current item - index of a child in the content
stateString""State of the Video Node
positionInteger0Playback position in seconds
durationInteger0Playback duration in seconds
currentItemNode-

Indicates the current item in the content node

If changing this field manually, unexpected behavior can occur

Read Only

endcardItemSelectedNode-The content node of the selected endcard item
disableScreenSaverBooleanFalse

This is an alias of the video node's field of the same name

Refer to Video nodes for the description of the field

themeAssociative array{ }

Theme is used to change the color of the grid view elements

Note: Set TextColor and focusRingColor to have a generic theme and only change the attributes not using the generic theme

For the possible VideoView values, refer to:

For the possible EncardView values, refer to :


Example

Using VideoView  Expand source

DetailsView

Extends: SGDEXComponent

Description

DetailsView is the SGDEX equivalent of the springboard screen that was used in the legacy Roku SDK. It can be used to show poster art for content, text descriptions, and a set of action buttons defined by the buttons field. These buttons support the content metadata fields listed below for customizing the text and images displayed in the button.

Fields 

FieldTypeDescription
TITLEStringThe label for the list item
HDLISTITEMICONURL UriThe image file for the icon to be displayed to the left of the list item label when the list item is not in focus
HDLISTITEMICONSELECTEDURLUriThe image file for the icon to be displayed to the left of the list item label when the list item is in focus

Interface

Fields

FieldTypeDefaultDescription
buttonsNode-

The content node for a button's node

Has children with an ID and a title that is shown on the view

isContentList

BooleanTrue

Tells details view how your content is structured
If set to true it will take children of content to display on the view
If set to false it will take content and display it on the view

Write Only

allowWrapContentBooleanTrue

Defines the logic of showing content when pressing left on the first item or pressing right on the last item

If set to true, start playback from the first item (when pressing right) or starts it from the last item (when pressing left)

Write Only

currentItemNode-

Returns the currently displayed item

This field is set when the Content Getter finishes loading extra meta-data

Read Only

itemFocusedInteger0Indicates which item is currently focused
jumpToItemInteger0

Manually focuses on the desired item

Must be set after setting the content field

Write Only

buttonFocusedInteger0

Indicates which button is focused

Read Only

buttonSelectedInteger0

Is set when a button is selected by the user

Observed in the channel

Can be used to show the next screen or start a playback

Read Only

jumpToButton

Integer0

Interface for setting focused button

Write Only

theme

Associative array

{ }

Controls the color of visual elements

For a list of all the possible values, refer to DetailsView theme attributes

GridView

Extends: SGDEXComponent

Description

The GridView component defines a standard content grid. In conjunction with ContentHandlers, SGDEX grids can be implemented to support:

  • Content loading;
  • Lazy loading of the rows and an item in the row;
  • Lazy loading of the rows when a user is not browsing the grid 

Interface

Fields

FieldTypeDefaultDescription
rowItemFocusedVector2D[0, 0]Updated when focused item changes
Value is an array containing the index of the row and the items that were focused
rowItemSelectedVector2D[0, 0]Updated when an item is selected
Value is an array containing the index of the row and the items that were selected
jumpToRowItemVector2D[0, 0]

Sets grid focus to a specified item
Value is an array containing the index of the row and the items that should be focused

This field must be set after setting the content field only

themeAssociative array{ }

Controls the color of the visual elements

For the possible values of Grid view theme, refer to Gridview theme attributes

styleString""

Indicates what grid UI is used

Possible values

  • standard - Default grid style
  • hero - Default grid style
posterShapeString""

Controls the aspect ratio of the posters on the grid

Possible values

  • 16x9
  • portrait
  • 4x3
  • square
contentNode-

Controls how SGDEX loads the content for the view

Content metadata field that can be used:

 Expand source

Here,

  1. "ContentHandlerForRows" is the content handler that is called to get the content for the provided row
  2. Fields is an Associative Array of values that are set to the ContentHandler to pass additional data to it

Note: Passing the row itself or grid via fields might cause memory leaks

Set the row ContentHandler when parsing content in "CHRoot," so that it is called when data for that row is needed

 

Example

Using GridView  Expand source

 

EntitlementView

Extends: SGDEXComponent

Description

The EntitlementView gives developers a way to build a basic SVOD experience in their channel. It can be used to walk a user through the purchase of a Roku Billing subscription and also be  used after a purchase to enforce entitlement rules by checking whether a user owns a valid subscription.

There are two implementations of this view:

  1. A silent check of the available subscriptions;
  2. A check to show Entitlement view/flow

To pass configs to view, a user implements a handler that extends EntitlementHandler.

Interface

Fields

FieldTypeDefaultDescription
isSubscribedBooleanFalse[ObserveOnly] Sets to true/false and shows if a user is subscribed after:
  1. Checking via silentCheckEntitlement=true (see below)
  2. Exiting from the subscription flow initiated by adding a view to the view stack
silentCheckEntitlementBooleanFalse

Initiates silent entitlement checking (headless mode)

Write Only

 

Example

Using EntitlementView  Expand source
  • No labels