General Variable Tips

When setting up variable options for users of your widget in WidgetStudio, it is helpful to remember to make them as useful and clear as possible. Of course if you make a widget only for yourself, feel free to be as sparse as you want. Your future self, however, may wish for more explanation.

In working with WidgetStudio over the last few weeks, I've developed some best practices. Here is what I think about when making my options:

Expose what Makes Sense

A widget is very useful when more of its underlying options are exposed for the user. The point of WidgetStudio is to allow a user to make adjustments without getting into the code, so try to expose as many of them as possible. I think of it like I would FileMaker: What would I want to adjust if this were a layout. Here's what I've exposed much of the time.

  • Text
    • Any heading text
    • Paragraph text (as necessary)
    • Default text of the library
  • Styles
    • Background colors
    • Heading color and alignment
    • Padding
    • Alignment
    • Font family and size
    • Note: You can expose an entire CSS Snippet. I'd stay away from that for the most part, instead exposing each one individually

Meaningful Variables

Since the variables, the __variableHere__ are written in the code editor and are not directly exposed to the widget user, it is okay to be a bit generic with your variables (of course they must be unique). I've found it very useful to give the variable name the same name as the option.

autoswitch: __autoswitch__,//switches between hour and minute
meridians: __meridians__,
setCurrentTime: __setCurrentTime__<br>

In styles, I've simply named the variable after the element and the targeted style:

h1 {
	color: __h1Color__;
	text-align: __h1TextAlign__;
}

Make them semi-meaningful for you the developer.

Clear Labels

Labels are required and must be unique. They are exposed to the user as labels for the customization options, and they are used as variable names when deploying to FileMaker.

Labels can have spaces in them. WidgetStudio will remove spaces to make them valid variables.

And, as with FileMaker variables, it is best to use only alpha-numeric characters.

Input Types

The input types options will give your users the best chance to fill in the correct type of value. Use them appropriately. 

Values

Fill in default values so that users can see how it will look when they first open the widget. Make these meaningful.

Help Text

Provide as much help text as possible, and review the help text in the customization area. If you run out of room in this area, you can always post more help in the Widget Info section.

Possible Values

Give the user the possible options for input types of Popups or dropdowns. This is very important when a library needs certain values for an option.

Categories

By default, any data variables will be grouped into generic groups such as "Color" and "Sample Data" and "General Options"

That works for simple widgets. But for complex ones, it is advisable to group each option into groups that make sense. In this example, I've grouped them by widget part.

Any variable with a category and a sort will be placed into that group, overriding the default groups. That means I can put color variables with data variables since it makes sense to place those together.

Sorts

 As with the groups, a logical sort order makes it easy for a user to follow the customization. in the above example I sorted the Color variable to the top in each of the series groups.