Channel Table

Channel Tables, or a list of which channels are available, their names, URI's, and so on, can be handled in many ways. In most cases, an XHR request is sent from the portal to the operators backend server, which responds with the channel table for that STB.

In this example portal, a default channel table is inserted into the boot image as it gets built. In addition, if an Infocast server broadcasts a channel table to the population of STBs then this would be received and would take priority over the default table. In both of these cases, the table is received and handled by the TOI Information Service. It appears as a configuration object which can be saved to flash memory, and the portal can attach callback events to this object to be notified of any changes.

Configuration objects are useful in many other situations too, for example, storing the current channel, volume, mute state, the profile of the end-user currently logged in, etc. Saving these to flash memory means that should the STB restart, the values will be preserved and the portal can resume with the previous values. The TOI API also makes extensive use of configuration objects for controlling the STB behaviour and reading its status, which we will look at later on.

toi.informationService.addEventListener(
  toi.informationService.ON_OBJECTS_CHANGED,
  onChannelListChange);
toi.informationService.subscribeObject(onChannelListChange,
                                       "apps.portal.channeltable", true);

Here, the portal registers an event listener for ToiInformationService::ON_OBJECTS_CHANGED. This Event Identifier occurs when the value of any configuration object changes. As there are hundreds of objects, a subscription mechanism is also used here. The call to ToiInformationService::subscribeObject() passes the listener function (must be the same function as the one passed to addEventListener), and the name of the object the portal wants to listen on. The third parameter, the 'false' flag, indicates if the portal would like to trigger the event now, too. This can be useful for initialization sometimes.

The name of the object, apps.portal.channeltable is arbitrary, and you can use whatever names you want for your custom objects. This portal uses some more custom objects for handling volume, which we will look at next.

When the list changes

When the value of apps.portal.channeltable changes (this could be due to the Infocast server broadcasting a new table, or some unrelated part of the portal altering the object, for example) the Information Service will call the onChannelListChange listener.

function onChannelListChange(event)
{
  try {
    channelList = JSON.parse(event.objects[0].objectItem.value);
    currentChannelIndex = -1;
    if (channelList.length > 0) {
      sortChannels();
      framework.emit("ChangeChannel", 0, true);
    }
  }
  catch (ex) {
    channelList = [];
    currentChannelIndex = -1;
    framework.emit("UpdateChannel",
                   {"name":   "[no channels]",
                   "number": "-" });
  }
}

The event parameter to the listener is of type ToiInformationObjectsChangedEvent. This provides the object(s) that have changed, and their new value. Since the channel table is represented as a JSON object, JSON.parse() is invoked to convert it into a JavaScript object. Just in case there are any issues with the formatting of the table, an exception handler is placed around the JSON.parse() call.

To simplify this example portal, when a change to the channel table occurs, the portal automatically zaps to the first channel in the new list. Obviously, in a real-world situation you should check if the channel currently playing is still in the table. You could also handle changes to just the channel names and numbers, the channel ordering, etc. This stuff was considered beyond the scope of the example portal.