Naming your controls
Last updated on November 22, 2024Naming your controls will make referencing them much easier.
On this page:
- Automatic control names
- Why name your controls
- Where and when to name controls
- Naming conventions and guidance
- What happens if you change a name
Automatic control names
All controls on a form must have a name that is unique within the entire form.
When you add a new control, Orbeon will automatically name it based on type and sequence added, such as:
- section-01
- grid-03
- control-27
These names are functional, but not that usable.
Why name your controls
Control names are used as the variables that you'll reference when you do things like:
- Perform data calculations
- Combine text and data
- Set conditions for visibility and interaction
- Copy data for autogenerated PDF layout
- And much more
It's a lot easier to remember a name like dayRate than it is control-32.
Where and when to name controls
The Control Name field is found in the Basic Settings tab of the Control Settings.
The Control Settings are where you can also:
- Set display options for the control (depending on type)
- Make a field required or validate the data
- Insert formulas for things like calculations or visibility
- Set up formatted and personalized labels, hints, and help
Consider adjusting control settings when you've placed and sized your control on the form before going onto the next control. This will help limit the chances you forget something.
Controls need to exist and be named first
If you try to create some sort of condition or calculation that refers to a control that doesn't exist yet, Orbeon will mark your expression (formula) as invalid. This helps prevent typos and logic errors.
- If you haven't built the control yet, wait until it exists before referencing it
- If you haven't renamed the other control yet, you can use the current name and Orbeon will update the formula when you do
Naming conventions and guidance
You'll want to name your controls in a way that's easy to recognize and type in formulas.
Perhaps the most common convention is called camel case, where:
- Descriptive words are combined without spaces
- The first letter of each word, except the first one, is capitalized
Examples of this convention are:
- applicantGivenName
- hourlyRate
- preference
Another common convention is using hyphens between lower-case words:
- applicant-given-name
- hourly-rate
- preference
Camel case has generally been around longer, is quicker to type, and easier to recognize as a variable amongst a bunch of other function and process names. Consider using this convention as your default one.
Also consider conferring with your developers for their preference. If you expect your forms will be interacting with other systems, it could be helpful to align with them and their expectations.
When naming your controls, try to:
- Be consistent within a form
- Be consistent across your all your forms
- Align with your developers
It's okay to vary your names. Consistency across your team and developers just helps to quickly identify data elements and match things up.
What happens if you change a name
Realized that you need to change givenName to applicantGivenName? No worries.
Orbeon is quite 'smart' when it comes to managing control names and variables. If you change a control name, any formula referencing that control is updated with the new name automatically when you save the form.