Creation Guidelines and Conventions

Components provide a lot of freedom to users with regards to packaging re-usable content. However, there are some guidelines that if followed will reduce the potential for confusion when your component is applied to a number of projects.

Favor Groups over Controls

While it is possible to create components from a single control, this is generally only useful for the simplest of components. In order to manage interactive state, provide feedback and handle input it is better to use a group to provide a consistent namespace for controls and variables.

Use a Consistent Name Prefix

Components are intended to be created in the context of one project and then shared and used in other projects. However, since a component packages all of its images, fonts, scripts and animations with it, there is always the potential for name conflicts to occur. To minimize the change of conflict it is suggested that you name all of resources with a prefix that links them to component. For example Crank provided components use following naming convention:

  • A prefix name is established using a prefix of SBC followed by the name of the component. For example SBCPushButton

  • All image resources use the prefix name (e.g., SBCPushButtonBevel.png)

  • All animation definitions use the prefix name (e.g., SBCPushButtonFadeOut)

  • All Lua script files use the prefix name (e.g., SBCPushButton.lua)

Keep Lua Scripts Isolated

In order to avoid any conflict within the Lua namespace it is important to not only identify the Lua script file(s) used by the component but also to ensure that all of the Lua functions and variables used by the component do not conflict with anything else in the application. This means ensuring only a minimal set of callback functions are exposed and that the local keyword is rigorously applied.

Provide Change Notification via callback Variable

In many component situations is it desirable to remove the user from the mechanics of what a component is doing within the UI and to simply provide status information as a final result. For example a check-box button might have a selected/unselected state or a slider might have a percentage result that they indicate. In these cases it is a convention to use a variable associated with the group named callback that is typed as a Lua function variable. This allows the user to set different callback functions for different instances of the component but use the same controlling logic.