Action Manager

Centralizes user-intent actions (play, display, focus) and coordinates navigation, analytics, and state.

Core Concepts

• Use BaseView.dispatchAction({ actionType, payload }) to fire actions from any view. This automatically routes to the app ActionManager.
• ActionManager<T> implements IActionManager<T> and centralizes user-intent like showing screens or playing video.
• App managers (e.g., EWTNActionManager) override handlers (handlePlayAction, handleDisplayAction, etc.) and can add prehooks (paywall, login) before completing.
• Actions are HsAction<T> objects (observable). They expose state and finishState and helper methods setState() and setFinishState() for lifecycle signaling.

Cancel or Retarget

If an action becomes invalid (no nav controller, missing payload), set Failed. New actions can supersede in-flight ones.

Live Example (Basics)

How Actions Flow

• Views call dispatchAction(...) on themselves. Example (EWTN):

      this.dispatchAction({
        actionType: BaseActionType.Display,
        payload: {
          item: (event.view as IHosannaView<ViewState>).getCustomData<JsonData>()?.item
        }
      });

• The manager receives it and executes the appropriate handler. Example EWTNActionManager play/display:

  override handlePlayAction() {
    const payload = this.action?.payload;
    const item = payload?.item;
    const navController = payload?.origin?.getNavController() as unknown as INavController;
    if (!item || !navController) {
      this.action?.setState(ActionState.Failed);
      return;
    }
    const videoInfo = this.getVideoInfoForItem(item);
    const videoScreen = PlayerScreen({ videoInfo: videoInfo, sourceAction: this.action as HsAction });
    navController.push(videoScreen);
    this.action?.setState(ActionState.Completed);
  }

Key Components

Action Types

The framework includes several built-in action types defined in BaseActionType:

• Display: For displaying content
• Play: For playback actions
• PlayLive: For live playback scenarios
• ContentFocusIn: For focus events
• ContentBlur: For blur events
• ContentClick: For click events
• None: Default state

Action States

Actions can be in one of the following states (ActionState):

• Pending: Initial state of a new action
• Completed: Action has been successfully completed
• Failed: Action failed to complete
• Error: Action encountered an error

Core Features

1. Action Handling

The Action Manager provides several key methods for handling actions:

handleAction(action: HsAction<T>): boolean

This method:

• Validates the incoming action
• Cancels any pending actions
• Manages the new action
• Returns true if the action was handled successfully

2. Action Validation

isActionValid(action: HsAction<T>): boolean

Validates actions by checking:

• Action existence
• Action type validity
• Returns true if the action is valid

3. Action Management

manageAction(): boolean

Manages actions by:

• Dispatching to appropriate handlers based on action type
• Handling different action types through specific methods
• Returns true if the action was managed successfully

4. Pending Action Cancellation

cancelPendingAction(action: HsAction<T> | null): void

Handles the cancellation of pending actions when:

• A new action is received
• Manual cancellation is requested
• The action is in a Pending state

Extensibility

The Action Manager is designed to be extended through:

1. Custom Action Types: Extend the base action types for specific needs
2. Handler Override: Override default handler methods:
   • handlePlayAction()
   • handleDisplayAction()
   • handlePlayLiveAction()
   • handleContentFocusInAction()
   • handleContentBlurAction()
   • handleContentClickAction()

Usage Example

// Create a custom action
const action = new HsAction<BaseActionType>({
  actionType: BaseActionType.Display,
  payload: { /* action data */ }
});

// From inside a view subclass: returns the HsAction instance
const action = this.dispatchAction({ actionType: BaseActionType.Play, payload: { item, origin: this } });

// Manager updates lifecycle signals
action.setState(ActionState.Completed);
action.setFinishState(ActionState.Completed);

Best Practices

1. Action Validation: Always validate actions before processing
2. Error Handling: Handle action states appropriately
3. Cancellation: Properly manage pending actions
4. Extension: Extend the base ActionManager for custom behavior
5. State Management: Monitor and handle action state changes

Technical Considerations

• Actions are observable (HsAction extends HsObservable) and can be observed via @observableField updates on state/finishState.
• Support for generic action types
• Built-in state management
• Type-safe implementation through TypeScript
• Extensible architecture for custom implementations

Tip: Use finishState for outcomes

Use state to indicate start/instant status and finishState to record the final outcome. For example, when playing video, set state when navigation starts and finishState when playback ends.

This documentation provides a comprehensive overview of the Action Manager system in the Hosanna UI framework. For specific implementation details or custom extensions, refer to the API documentation or the source code.