Add API to switch UI variants

[protyposis]

Implements #101 and provides multiple ways to switch between UI variants via the public UIManager API:

interface UIConfig {
  /** 
   * A configuration flag that allows to turn off automatic UI variant switching to allow purely 
   * externally triggered switching through `resolveUiVariant` and/or directly through 
   * `switchToUiVariant` (default `true`)
   */
  autoUiVariantResolve?: boolean;
}

class UIManager {
  /**
   * An event that is triggered just before the next UI variant is resoved and the UI variant 
   * is switched. It is fired when the switch is triggered from an automatic switch and when 
   * calling `resolveUiVariant` and can be used to modify the `UIConditionContext` before 
   * the UI variant is resoved.
   */
  onUiVariantResolve: EventDispatcher<UIManager, UIConditionContext>;

  /*
   * Returns the list of UI variants as passed into the constructor of `UIManager`.
   */
  getUiVariants(): UIVariant[];
  /*
   * Switches to a passed in UI variant taken from the list returned by `getUiVariants()`.
   */
  switchToUiVariant(uiVariant: UIVariant): void;
  /*
   * Triggers a UI variant switch according to the current `UIConditionContext` and allows 
   * to overwrite internal context properties.
   */
  resolveUiVariant(context: Partial<UIConditionContext> = {}): void;
}

Examples

All the following examples can be combined in all kinds of combinations. Im many cases it will make sense to disable automatic switching and handle the switching purely through the API with switchToUiVariant, but there might be cases where automatic switching is wanted but certain modifications in the behavior are desired. In the latter case it makes sense to combine resolveUiVariant and/or switchToUiVariant with onUiVariantResolve.

const uiConfig: UIConfig = {};

const uiManager = new UIManager(player, [{
  // Add a UI variant for ads
  ui: buildAdsUi(),
  condition: (context: UIConditionContext) => {
    return context.isAd;
  },
}, {
  // Add a UI variant for the main content
  ui: buildDefaultUi(),
}], uiConfig);

Example 1: Modify automatic switches

uiManager.onUiVariantResolve.subscribe((sender, context) => {
  // Avoid switching to the ads UI depending on our custom `preventAdsUi` flag
  if (context.isAd && preventAdsUi === true) {
    context.isAd = false;
  }
});

Example 2: Trigger a switch

// Switch to the ads UI independently from the content and player events
// This will reset as soon as any monitored player event is fired (e.g. `ON_PAUSED`)
uiManager.resolveUiVariant({ isAd: true });

Example 3: Disable automatic switching and trigger a switch by player events

// Disable automatic switching
uiConfig = {
  autoUiVariantResolve: false,
};

// Show ads UI when ad starts
player.addEventHandler(player.EVENT.ON_AD_STARTED, () => {
  uiManager.resolveUiVariant({ isAd: true });
});

// Switch back to default UI when ad is finished
player.addEventHandler(player.EVENT.ON_AD_FINISHED, () => {
  uiManager.resolveUiVariant({ isAd: true });
});

Example 4: Switch directly to desired variant

const myUiVariants = uiManager.getUiVariants();
// We know the index because we have defined the UI variant list and passed it into the UIManager
const myAdsUiVariant = myUiVariants[0];

// Show ads UI when ad starts
player.addEventHandler(player.EVENT.ON_AD_STARTED, () => {
  uiManager.switchToUiVariant(myAdsUiVariant);
});

[protyposis]

API discussed and accepted in the player architecture meeting 2018-05-22.

[Reevn]

LGTM 👍