<button/>

Owned by Jacques Marais
Last updated: May 03, 2024 by Hugo van Schalkwyk


Description and Examples

A simple clickable user interface button. Buttons will be placed in the user interface relative to where they are placed in the view xml.

The button label is specified as a key to a lang file entry and is required. Visibility bindings, appearance bindings, Button colours and icons, Tooltips and confirm dialog are also supported.

Buttons can be used for the following behaviour:

  • To execute a unit function and then invoke a navigation
  • To invoke a navigation without executing a unit function

"action" attribute

The value for the "action" attribute represents a unit function that will be executed. The function can either be specified using the fully qualified name or, if the function in in the unit that was specified for the view, only the name is required. The function can return one of two types that will determine the routing behaviour:

  • string return type: The string that is returned represents the navigation outcome of the function. For that outcome to be acted upon a navigation rule for that outcome is needed in the view.
  • DSL_VIEWS return type: DSL_VIEWS is a built in enum available to all DSL applications. The values in the enum represent the view names in your application. For example DSL_VIEWS.MyView will represent the view with name "MyView.vxml". A return type of DSL_VIEWS will result in navigation without the need for a navigation rule in the view therefore facilitating dynamic navigation. Note that the DSL_VIEWS enum and dynamic navigation will only be available from Helium 1.4.0 onwards.

Example code snippet
<button label="button.increment_counter" action="incrementCounter"/>
<navigation outcome="counter_result" target="CounterResult"/>
string incrementCounter() {
	counter = counter+1;
	return "counter_result";
}

"outcome" attribute

 An alternative usage of buttons is to simply use the "outcome" attribute instead of "action". The value for the "outcome" attribute represents a string literal outcome for which a navigation rule is required. In the case where only an outcome is used navigation can, therefore, be achieved without a unit.

Example code snippet
<button label="button.increment_counter" outcome="view_count"/>
<navigation outcome="view_count" target="CounterResult"/>

using "action" and "outcome"

The final possible usage of a button is to use both "outcome" and "action" together. In this case the logic in the unit function will be executed after which the outcome specified for the "outcome" attribute will be respected. Note that even when returning a string or DSL_VIEWS value from the action function binding, the outcome specified for the "outcome" attribute will be prioritised.

Example code snippet
<button label="button.increment_counter" outcome="counter_result" action="incrementCounter"/>
<navigation outcome="counter_result" target="CounterResult"/>
string incrementCounter() {
	counter = counter+1;
}




Additional Mentions and References