« HELP CENTER

Component Development Guide > Development Workflow

Parameterize

In the Build step, you created an app that incorporates your specialized service and can be used inside a Flite ad. However, at this point it does not meet the requirements of a Flite component, because ad designers have no way to configure it. The app may be useful for one particular advertiser, but it is not reusable.

Advertisers need to have a way to adapt the component’s functionality to fit their specific use case, and to configure the component’s look and feel in a way that is consistent with their branding; and they need to be able to do this without writing any code. In order to enable this, you need to parameterize your component.

There are several parts to the parameterization process:

  • Creating the parameters in Flite’s Component Studio
  • Grouping & arranging the parameters to make the layout more visually appealing for users as well as easier to understand
  • Using the parameters in your ActionScript 3 code to carry out the desired customization.

Creating and configuring parameters

To add a new parameter to your component, open it in Flite’s Component Studio and click the Add Setting button in the Edit Module. This creates a new setting block. To add a new parameter within a particular group (Tab, Section, or Disclosure), expand the group's geat menu, and select Add Setting. See the Component Studio documentation for more on parameter creation and configuration.

Next, expand the setting block (see image below) and fill in the required information.

  • Parameter: The name under which this parameter will be accessible through the Ad API.
  • Type: The type of parameter this is; this will determine what kind of form element will be used to enter the parameter information – a textbox, a checkbox, a dropdown menu, etc. You can also select Hidden to make the parameter hidden; such parameters will only be visible to the component developer, and are useful for debugging. Note that internally, the parameter value will always be stored as a string, regardless of the input type.
  • Label: The name under which this parameter will appear to component users in Ad Studio.
  • Help Text: The text that will appear underneath the parameter’s form element in Ad Studio; you can also display this text as a tooltip using the Render help text as tooltip checkbox. You can leave this blank if the parameter’s functionality is self-explanatory based on its Label.
  • Default Value: The default value for this parameter. Ad developers will be able to override this value when configuring the parameter in Ad Studio.

In addition to these fields, there may be additional information required depending on the Type of component you selected. For instance:

  • a Text Field (the default Type) lets you enter the control’s Width, in pixels, as well as the Maximum number of characters allowed;
  • a Date Picker lets you control how the date is displayed via the Date Format field;
  • and so on.

See the Component Studio documentation for more on the available parameter types and the input options available for each type.

Grouping and arranging parameters

A well-designed component will be flexible enough to meet the needs of 80% of advertisers. This will necessarily mean having a lot of parameters, and having them all appear in one long list would be overwhelming and confusing for ad designers. It is good practice to group these parameters into appropriately named tabs or sections, each containing a smaller and more easily digestible number of parameters.

Please take a look at the Parameter Architecture Guidelines article for best pratices around parameter creation and grouping. At a high level, we recommend grouping your parameters into the same three-tab Source / Layout / Style paradigm that we use for some of the built-in Flite Hub components (Twitter, Feed, YouTube). This will not be appropriate for all components, but is a good starting point. At a more granular level, it is useful to break parameters down into sections that are logically grouped by topic or function.

For example, take a look at the example in the image below. It shows the parameters for the Style tab of Flite's built-in Feed Component. The font parameter is global for the entire component; the font size and text color are controlled independently, and grouped into sections accordingly; and the link and separator colors are once again global.

Here is how you might go about creating the Source, Layout, and Style tabs, and filling out the Style tab as shown in the image above.

  1. Expand the Group menu at the top, and click Tab Set to create a new tab set.
  2. In the new tab set, expand the gear menu and select Add Tab. Do this three times to create three tabs.
  3. Rename the three tabs by clicking the pencil icon next to each tab to open its group editor, and changing the Label for each one. Name the first tab “Source”, the second one “Layout”, and the third one “Style”.
  4. Drag and drop any existing settings underneath the correct tabs.
  5. In the Style tab, expand the gear menu and select Add Setting. Do this three times to create three new parameters.
  6. Configure the parameters as described in the Creating parameters subsection above. These will be your font, link_color, and separator_color parameters.
  7. In the Style tab, expand the gear menu and select Add Section. Do this twice.
  8. Rename the two sections by clicking the pencil icon next to each one to open its group editor, and changing the Label for each one. Name the first one "Title" and the second one "Content".
  9. In the Title section, expand the gear menu and select Add Setting. Do this twice.
  10. Configure these parameters. these will be your title_font_size and title_text_color parameters.
  11. Repeat the previous two steps for the Content section.
  12. Drag and drop your sections and parameters to arrange them in the same order as in the image above.

Now if you click the Publish button, your settings and groups will be saved. You can view a preview of the grouping by going to your component's permalink. To view the parameters and groups exactly how an ad designer would see them, you will need to add this component to a test ad.

Using the parameters in code

You can access all the parameters you created in Component Studio through your component's initialize method, which is invoked when the component is loaded. The initialize method receives a resources object as an input. The parameters can be accessed via the resources.config object. 

For instance, to access the value of the title_text_color setting from the examples above, you can make the following call:

var title_color_string: String = resources.config.getValue ("title_text_color");

Alternatively, you can automatically convert the color string to an unsigned integer:

var title_color: uint = resources.config.getColor ("title_text_color");

You can then use this setting to change the title text color in your component. For more on the initialize method and the functions available on the resources.config object, see the initialize method documentation.

As you add new parameters to your component, you give customers more control over the component’s functionality and appearance, which increases the possibility of user error. Keep this in mind as you add new parameters, and include error checking in your code as necessary.

Uploading the SWF file

Once you finish updating your code, you must regenerate your SWF file and upload it into your component in Component Studio as described in the Replacing Your SWF File subsection of the Build step. As in the Build step, you may need to do this multiple times until you get everything right.