« HELP CENTER

Ad API 3 > Component Basics

Component Hierarchy

Ad Studio 3 allows components to have children. This concept of hierarchy is important for building and organizing your ad’s structure; moreover, certain components require children to perform their function. Please refer to the Key Concepts section of the Ad Studio 3 documentation for more on hierarchy in ads.

When creating a component, you can enable or disable its capacity to have children. One example of a built-in component that uses children is the Gallery component, which allows a user to navigate between its child components using a filmstrip of thumbnails. A user can click a thumbnail to display the child component associated with that thumbnail.

In this section, we go over how to enable components to have children, and discuss some features of the parent-child component relationship that you will need to understand in order to create components that can have children.

Adding and accessing children

In order to tell Ad Studio that your component can have children, do the following:

  1. In Component Studio, click the  icon at the top to launch the Configuration screen. 
  2. Check the Component can have child components checkbox. 
  3. Click Publish Changes to publish the new setting. 

You will now be able to add children to this component in Ad Studio. When the component is initialized by the Flite Runtime, its children's descriptions are passed to its initialize function, allowing the component to access them.

Children’s geometry

You can choose whether or not a component controls its children’s geometry (i.e., their X/Y position, width and height). You can do so in Component Studio as follows:

  1. In Component Studio, click the  icon at the top to launch the Configuration screen.
  2. Check the Component controls the geometry of its children checkbox. 
  3. Click Publish Changes to publish the new setting. 

Any children of this component will now have their x, y, width and height settings grayed out in Ad Studio. This prevents users from changing the child’s geometry in the Ad Studio interface, but does not prevent the child’s geometry from being changed programmatically by the Flite Runtime or by another component.

In order to prevent a component’s geometry from being changed programmatically, include the following code when initializing your component: 

    descr = api.library.getContainerDescription (componentKey); 
    descr.lockProperties ("x", "y", "width", "height");

Enabled and disabled states

There are two important things to keep in mind when dealing with enabled and disabled states in the context of parent and child components:

  • Enabled state travels up the family tree. This means that whenever a component is enabled, all of its parents (and grandparents, etc.) automatically become enabled as well. This makes a lot of sense if you think of the enabled state as being a rough equivalent to focus. When a component is in focus, its parent is necessarily in focus as well. 
  • Disabled state travels down the family tree. This means that whenever a component is disabled, all of its children (and grandchildren, etc.) become disabled as well. Again, this makes sense when thinking about focus. When an element loses focus, all of its sub-elements necessarily lose focus as well.