Panel Integration

Overview

This section walks you through integrating panels into your Maestro Roku SDK implementation. Panels provide interactive modules that exist outside the main video player interface.

Integration Steps

1. Show or Hide the Panel

Control panel visibility using the showPanel field:

m.lib.showPanel = true  ' Show the panel
m.lib.showPanel = false ' Hide the panel

2. Open to a Specific Panel

Open the panel to a specific tab by name:

m.lib.openToPanel = "keyplays"  ' Opens to Key Plays panel
m.lib.openToPanel = "fantasy"   ' Opens to Fantasy panel
m.lib.openToPanel = "stats"     ' Opens to Stats panel

3. Listen for Tab Focus Changes

Monitor which tab is currently focused:

function onFocusedTabItem(event as Object)
    focusedIndex = event.getData()
    print "Current Focused Tab Index: " + focusedIndex.toStr()
end function

4. Pass External Data to Panels

Use the setDataToPanel field to pass external data to a specific panel:

m.lib.setDataToPanel = {
    panelName: "keyplays",
    data: {
        ' Your panel-specific data here
    }
}

5. Monitor Panel View Events

Listen for panel view events:

m.lib.observeField("userViewedPanel", "onUserViewedPanel")

function onUserViewedPanel(event as Object)
    panelData = event.getData()
    print "User viewed panel: " + panelData.panelName
end function

6. Handle Panel-Specific Events

Listen for panel-specific events:

m.lib.observeField("onPanelEvent", "onPanelEvent")

function onPanelEvent(event as Object)
    eventData = event.getData()
    print "Panel event received: " + formatJson(eventData)
end function

Managing Panel Focus

Moving Focus to the Panel

Use the setPanelFocus() function to move Roku focus into the panel:

' Show panel and move focus into it
m.lib.showPanel = true
m.lib.callFunc("setPanelFocus")

Handling Focus Transitions

The SDK communicates focus-related actions through the handleLoadingSceneAction field. Observe this field to handle when the user exits the panel:

' Observe focus actions from the SDK
m.lib.observeField("handleLoadingSceneAction", "onHandleLoadingSceneAction")

sub onHandleLoadingSceneAction(event)
    action = event.getData()
    if action = "returnFocus"
        ' User exited the panel, return focus to your UI
        m.yourUIElement.setFocus(true)
    end if
end sub

Complete Focus Management Pattern

' Show panel handler
sub showMaestroPanel()
    m.lib.showPanel = true
    m.lib.callFunc("setPanelFocus")
    ' Optionally adjust your video layout
    resizeVideoForPanel()
end sub

' Hide panel handler
sub hideMaestroPanel()
    m.lib.showPanel = false
    restoreVideoLayout()
    m.yourUIElement.setFocus(true)
end sub

' Observe showPanel changes
sub onShowPanel(event)
    isPanelShown = event.getData()
    if isPanelShown
        resizeVideoForPanel()
        m.lib.callFunc("setPanelFocus")
    else
        restoreVideoLayout()
        m.yourUIElement.setFocus(true)
    end if
end sub

Video Layout Management

When showing the panel, you may want to resize your video player to make room for the panel:

' Resize video to accommodate panel (left side)
sub resizeVideoForPanel()
    m.video.width = 1184
    m.video.height = 666
    m.video.translation = [50, 200]
end sub

' Restore video to full screen
sub restoreVideoLayout()
    m.video.width = 1920
    m.video.height = 1080
    m.video.translation = [0, 0]
end sub

SDK Cleanup and Destruction

Always destroy the SDK when exiting your video session to ensure proper analytics tracking and resource cleanup:

' Call this when user exits the video view
sub cleanup()
    if m.lib <> invalid
        ' Destroy SDK to ensure proper analytics tracking
        m.lib.callFunc("destroySDK")
        ' Remove panel from scene
        m.top.removeChild(m.lib)
        m.lib = invalid
    end if

    if m.componentLibrary <> invalid
        m.componentLibrary = invalid
    end if
end sub

danger

Always call destroySDK() before removing the panel from the scene. This ensures proper analytics session termination and prevents memory leaks.

Best Practices

Check Panel Availability: Ensure the panel you're trying to open is configured in your Maestro page.
Data Validation: Always validate data before passing it to panels.
Focus Management: Always observe handleLoadingSceneAction to handle focus transitions properly.
Video Layout: Resize your video player when showing the panel to provide a better user experience.
Clean Up Resources: When done with the SDK, call destroySDK() to clean up all listeners and ensure proper analytics tracking.
Append Before Config: Always append the panel to your scene (m.top.appendChild(m.lib)) before setting the config.

Example: Complete Panel Integration

This example shows a complete integration with a video player and custom UI controls:

' Step 1: Initialize the SDK
sub initSDK()
    ' Create component library and fetch the SDK
    m.componentLibrary = createObject("roSGNode", "ComponentLibrary")
    m.componentLibrary.uri = "https://roku-sdk.us-central1-master.gcp.maestro.io/4.1.14/maestrokit.zip"
    m.componentLibrary.observeField("loadStatus", "onLibraryLoadStatusChanged")
end sub

' Step 2: Create MaestroPanel when library is ready
sub onLibraryLoadStatusChanged()
    if m.componentLibrary.loadStatus = "ready"
        ' Create MaestroPanel instance
        m.lib = createObject("roSGNode", "MaestroPanelLib:MaestroPanel")

        ' Observe essential events
        m.lib.observeField("showPanel", "onShowPanel")
        m.lib.observeField("handleLoadingSceneAction", "onHandleLoadingSceneAction")
        m.lib.observeField("focusedTabItem", "onFocusedTabItem")
        m.lib.observeField("trackingEvent", "onTrackingEvent")

        ' Append to scene BEFORE setting config
        m.top.appendChild(m.lib)

        ' Finish setup
        finishSetup()
    end if
end sub

' Step 3: Configure the SDK
sub finishSetup()
    ' Configure with your site and page IDs
    m.lib.config = {
        siteID: "66956c7680975a8bb6bf8f75",
        pageID: "68f7b3bc543627ba334e0104",
        useProdEnv: false
    }

    ' Set panel dimensions
    m.lib.width = 1280
    m.lib.height = 720

    ' Set focus to your UI (not the panel)
    m.settingConfig.setFocus(true)
end sub

' Step 4: Handle show/hide panel actions
sub onItemSelected(event)
    index = event.getData()
    action = m.settingConfig.content.getChild(index)?.title

    if action = "ShowPanel"
        m.lib.showPanel = true
        m.lib.callFunc("setPanelFocus")
        minVideo()
    else if action = "HidePanel"
        m.lib.showPanel = false
        maxVideo()
    end if
end sub

' Handle panel visibility changes
sub onShowPanel(event)
    isPanelShown = event.getData()
    if isPanelShown
        minVideo()
        m.lib.callFunc("setPanelFocus")
    else
        maxVideo()
        m.settingConfig.setFocus(true)
    end if
end sub

' Handle focus return from SDK
sub onHandleLoadingSceneAction(event)
    action = event.getData()
    if action = "returnFocus"
        maxVideo()
        m.settingConfig.setFocus(true)
    end if
end sub

' Video layout helpers
sub minVideo()
    m.video.width = 1184
    m.video.height = 666
    m.video.translation = [50, 200]
end sub

sub maxVideo()
    m.video.width = 1920
    m.video.height = 1080
    m.video.translation = [0, 0]
end sub

' Step 5: Cleanup when exiting
sub cleanup()
    maxVideo()
    if m.lib <> invalid
        m.lib.callFunc("destroySDK")
        m.top.removeChild(m.lib)
        m.lib = invalid
    end if
    if m.componentLibrary <> invalid
        m.componentLibrary = invalid
    end if
end sub

Panel Integration

Overview​

Integration Steps​

1. Show or Hide the Panel​

2. Open to a Specific Panel​

3. Listen for Tab Focus Changes​

4. Pass External Data to Panels​

5. Monitor Panel View Events​

6. Handle Panel-Specific Events​

Managing Panel Focus​

Moving Focus to the Panel​

Handling Focus Transitions​

Complete Focus Management Pattern​

Video Layout Management​

SDK Cleanup and Destruction​

Best Practices​

Example: Complete Panel Integration​