Ad API 3 > Component Basics

Component States

The typical component lifecycle, including all possible state transitions, is displayed in the diagram below.

Here is what each state actually means:

• No State: Component’s state before the Flite Runtime is aware of its existence. 
• Unloaded: Component’s state when the Runtime is aware of its existence, but has not yet loaded the component by running the constructor method.
• Loaded: Component’s state after its constructor method has been run, but before the initialize method is invoked. 
• Initialized: Component’s state after its initialize method has been called. 
• Enabled: This state is typically set either by the component’s own code or by its parent component. Its intended meaning is roughly equivalent to the component being in focus, but can be interpreted and used in a different way if desired. This state’s effect on a component is controlled via the component’s stateChange method. 
• Disabled: This state is typically set either by the component’s own code or by its parent component. Its intended meaning is roughly equivalent to the component losing focus, but can be interpreted and used in a different way if desired. This state’s effect on a component is controlled by the component’s stateChange method. 
• Unloaded: Component’s state when it has been unloaded from the Runtime. This will happen when the user browses to another page and the entire ad is unloaded; when the component is dynamically resized but the component’s resize method has not been implemented; or for a variety of other reasons.

State Changes

Whenever the state of a component or one of its children changes, its stateChange method is invoked. Implement this method to execute some code when the state changes. Only the Enabled, Disabled and Unloaded states are made available via the API. See the State API documentation for the string constants corresponding to these three states. The other states are only used by the Flite Runtime.

The two component states that you will primarily be dealing with are the Enabled and Disabled states. Once the component is loaded, initialized, and displayed in the user’s browser, these are the only two states that are relevant until it is unloaded.

A component may go back and forth between the Enabled and Disabled states many times as the user interacts with the ad. These state transitions are typically controlled either by the component’s own code or by the component’s parent’s code. The Runtime does not control these states, and there is no default behavior associated with them, so you may interpret them as you wish. However, the intent of these states is for the enabled state to be roughly equivalent to the component being in focus, and the disabled state to be roughly equivalent to the component being out of focus.

Below are several examples of how the Enabled, Disabled, and Unloaded states may be used. 

Example 1: Gallery navigation. Consider a gallery navigation component. This component may have several clickable thumbnails allowing users to navigate to any of its child components. When a thumbnail is clicked, the corresponding component is enabled (or put in focus) and all the other children are disabled (or taken out of focus). The gallery’s stateChange interface method is invoked every time this happens, triggering the gallery to redraw and display the currently enabled component. In this scenario, the various child components may toggle back and forth between the Enabled and Disabled states many times as the user navigates the ad. 

Example 2: Video. Consider a video component. The user may start watching the video, and then click on a different item in the gallery navigation (let’s say, a Twitter feed), switching the video component to the Disabled state, and making it no longer visible in the ad. In most situations, you will want to stop playback once the video is no longer in focus. You can do so by acting on the video component’s Disabled state using the stateChange method.

Example 3: Cleaning up. When a component is dynamically unloaded from the ad, its parent may want to clean up any references to that component. For instance, suppose one of the child components in your gallery is unloaded. The gallery will want to remove the thumbnail corresponding to that component from its display. This can be done by acting on the Unloaded state in the stateChange method.

See the Component Hierarchy section to learn how the Enabled and Disabled states travel up and down the component hierarchy.