« HELP CENTER

Component Development Guide > Guidelines & Best Practices

Parameter Architecture

The component parameters you expose through Component Studio will be seen and used by all ad developers and designers who use your component. This means you have to design these configuration parameters to be easy to understand and use. Some specific advice on parameter architecture follows.

Overall design

  • Make it configurable – within reason. It is important to strike a balance between flexibility and simplicity. A component should have enough configuration parameters to satisfy the majority of advertisers who might be interested in using it, but not so many that it is too much for an ad developer to process. For instance, you will want to add parameters that control the appearance of the various elements in your component, because you want to allow designers to skin the component to match their branding. But you don’t need to expose the text of every single error message as a parameter, or to make the font of every single text snippet individually configurable. It is advisable to make some assumptions and generalizations for the sake of simplicity, usability, and clarity. Follow the 80/20 rule -- 80% of ad designers will be happy with 20% of the functionality. You just have to pick the right 20%. 
  • Keep it simple. Ideally, what a parameter does should be clear from its name alone, e.g. “Submit button text”, “Email instructions font”, etc. If you find that you cannot explain what your parameter does in a short name, consider simplifying the parameter’s functionality, or splitting it into multiple parameters. For instance, it may be tempting to combine the font, color, and size of a particular text element into a single parameter. We do not recommend doing this.

Naming

  • Be succinct. Parameter names should be short. Try to summarize the parameter’s function in as few words as possible. If you feel a longer name is merited, consider using help text in conjunction with a shorter name.
  • Be consistent. All parameters in your component should have a consistent naming scheme. For instance, suppose your component has some title text and body text. if you have a parameter called “Title Font Size”, its body text counterpart should be called “Body Font Size”, and not “Body Text Size”. Similarly, the two text fields used for these two parameters should be the same size.
  • No colons. In Flite’s built-in components, we typically do not use a colon at the end of a parameter label. Please follow this convention in your component parameter labels.

Appearance

  • Right-size. Component Studio gives you the ability to change the size for some types of components. Use this functionality. For instance, if you have a text field for specifying a font size, make it the right size to fit a two-digit number. This is a good visual cue for an ad designer configuring your component.
  • Right-type. There are many different types of components you can make – text boxes, dropdown menus, checkboxes, date pickers, and so on. Familiarize yourself with the available types, and make sure to select the type that makes the most sense for each component. For instance, if you expect one of a set of seven responses, you may want to use a dropdown menu rather than a text field; if you are looking for a binary response (yes/no, true/false), you may want to use a checkbox; etc.
  • Use help text where necessary. Much of the time, the function of a parameter is fairly clear from its name – but sometimes it isn’t. In such a situation, add some help text to clear things up. For instance, you may have a text area parameter, where people can use Markdown syntax to format the resulting text. In this situation, you may want to add some help text, e.g. “Use Markdown syntax to add some basic formatting”.
  • Use post-labels where appropriate. Post-labels allow you to enter text after the control instead of before. This is almost always the right way to go for checkboxes. For checkbox controls, people typically expect the text explaining the checkbox to be on the right side of the checkbox, not on the left. For most other controls, the label is usually expected to be on the left.

Parameter layout

  • Group settings logically. Group settings by topic or function. For instance, you may have a number of settings that control what a particular button looks like on a page – the button text; the font, size, and color of the text; the size and color of the button itself; etc. All of these settings should be grouped together. This immediately lets the component user see how they can alter that particular element, and lets them make well-informed decisions. It also reduces the length of component names. A parameter that otherwise would be called "Submit Button Text Color", would now be named "Text Color", because it would be inside the "Submit Button" group.
  • Source/Layout/Style paradigm. As a starting point, we recommend grouping all your parameters into three tabs:
    • Source: Parameters required to contact a third-party API and/or obtain the content that should appear in the component;
    • Layout: Parameters required to arrange content and other elements in the component; and
    • Style: Parameters required to change the look and feel ofvarious component elements.
    We use this same paradigm, or a very similar one, for all our built-in Flite Hub App components (Feed, Twitter, YouTube, etc.). For some components, this may not fit as well, or perhaps an additional tab may be necessary. However, we have found this to be an excellent starting point.
  • Consider user flow. When ordering parameters, consider how an ad developer might think about the parameters when configuring the component, and which parameters they might associate with each other. For instance, if element B appears immediately below element A in the component, you will generally want parameters relating to element B to appear after parameters for element A.