The ControlBar Control

IN THIS PAGE

What is a Control Bar?
ControlBar Concepts
ControlBar Methods
Adding a ControlBar Control to a UX Component
Using the ControlBar Builder
Videos

Description

An overview of the ControlBar Control, its methods, and the concepts behind it. ControlBar controls are an easy way to organize buttons in panel headers when building Mobile applications.

What is a Control Bar?

Documentation for the ControlBar API is available here

A ControlBar is similar to the toolbars that you see in your desktop applications. For example, all of the builders (e.g. UX Builder, Grid Builder) display a bar with multiple buttons across the top of the screen.

The primary use case for a ControlBar is to define the contents that appears in a UX component's Panel headers and footers. However, ControlBars are not limited to Panel headers and footers. Like other control types in the UX, they can be added anywhere in the UX. For example in a Panel body. Or even in UX components that do not use Panels at all.

Before ControlBars were available, developers would add a Panel header or footer to a Panel (e.g. a PanelCard, PanelLayout or PanelNavigator) and then put standard UX controls (typically buttons and static text controls) inside the Panel header or footer. Configuring these controls to achieve the layout that you wanted could be quite tricky. For example, a common pattern would be to create a header with a 'Back' button that was left justified, a title that was centered and a menu button that was right justified. Using a ControlBar in a header or footer, rather than individual controls, makes this much easier.

The image below shows a typical Panel header in a mobile application. The header consists of a series of buttons to perform different actions. Some of the buttons are left aligned and others are right aligned.

In the image below you can see how this layout was achieved using standard UX controls placed inside the PanelHeader container.

In order to right align the three buttons shown in header, it was necessary to wrap the controls in a container (CONTAINER_1) and then set the inline style for the container to:

ControlBar Concepts

In order to understand how ControlBars work you need to understand the following ControlBar concepts, each of which is explained in more detail below.

Layouts
Layout lines
ControlBar Items
Actions
Data
Disclosures

Layouts

A ControlBar control can have multiple 'layouts'. In this respect, a ControlBar is similar to a List control, a ViewBox control or a FormView control, all of which also can have multiple layouts.

You can dynamically select which of the ControlBar layouts to display. So, for example, you might use one layout for a phone in portrait mode, another layout for a phone in landscape mode, yet another layout for a tablet in portrait mode, etc. You can use Javascript to choose which ControlBar layout to set as the active layout, or you can use the Responsive Layout Settings genie to select the active layout.

Another example of where having a ControlBar with multiple layouts would be useful is in the case of a PanelNavigator. You could also define a ControlBar for the header section of the PanelNavigator and then dynamically change the layout that was shown depending on which PanelCard was shown in the PanelNavigator.

Layout Lines

Each layout that you define in a ControlBar can have one or more 'lines'. In many cases a layout will only have a single line. In the first image showing a typical Panel header, only a single 'line' would be needed in the ControlBar layout.

Each 'line' in a ControlBar layout is divided into three sections. These are:

before
middle
after

The 'before' section is for left justified content, and the 'after' section is for right justified content. The reason that these sections are not called 'left', 'center' and 'right' as you might have expected is that a ControlBar can be aligned to any edge of the screen. If a ControlBar is aligned to the top or bottom of the screen, the ControlBar is horizontal and 'before' does correspond to 'left' and 'after' does correspond to 'right'. However, ControlBars can also be aligned to the left or right of the screen. In these cases, the ControlBar will be rendered vertically, and the 'before' section will then correspond to the 'top' of the ControlBar and the 'after' section will correspond to the 'bottom' of the ControlBar.

Each line in a ControlBar layout can be conditionally shown or hidden by defining a Show expression for the line.

ControlBar Items

The content that you place in each of the Layout line sections are termed 'ControlBar Items'. There are several types of ControlBar items:

html: used to display text
htmlTitle: used to display text that will automatically truncate if there is not enough space to display all of the content
button: used to invoke an action
button-toggle: used to set a state. You can define 'two state' or 'multi-state' toggles
button-list: used to display a list of buttons, one (or multiple - depending on a setting) of which can be in the 'selected' state
disclosure-button: used to display a 'disclosure' (see below for definition)
edit: used to display a editable control, such as a text box, in the ControlBar
button-dropdownMenu: used to add a button that displays a dropdown menu when clicked

ControlBar items (with the exception of the 'html' item type) can have associated actions. For example, you can define actions for the following events on a ControlBar button:

Click
Downhold
Up
Down
Swipe

Actions

The code for each of these events is not defined directly in the definition of the ControlBar item. Instead, you define the code in 'actions'.

You can create as many 'actions' as you want. Each 'action' is given an arbitrary name.

Once you have defined an action (say 'myaction1') you associate a ControlBar item event with a particular action. So for example, you might set the 'click' event for a ControlBar button to 'myaction1'.

The advantage of putting your code in named 'actions' rather than directly in a ControlBar item's event (e.g. a button's Click event) is that you might define multiple buttons for display on different ControlBar layouts and each of these buttons can invoke the same action.

Data

ControlBars can have an arbitrary amount of data. The data for a ControlBar is defined as a series of name/value pairs. The values can either be strings, or objects.

For example, you might define a data item called 'name' and give it a value of 'Alpha Anywhere'. You could define another data item called 'address' and give it a value of:

{ address: '123 Main St', city: 'Lexington', state: 'MA'}

In this case the data item is an object and to reference the state you would use address.state as the data item name.

The common reason for defining data items in a ControlBar is to bind the text displayed by the ControlBar items to data values.

For example, you might define an 'html' ControlBar item called (say) 'html1'. You could set the text for this ControlBar item to a literal value (e.g. 'My Mobile App') or you might set the text to:

{name}

When the ControlBar was displayed if the 'name' item in the ControlBar's data was set to 'Alpha Software' the ControlBar would display this value. To change the text shown in the ControlBar, you simply update the value of the data item (using a method of the ControlBar - see ControlBar Methods below).

Similarly, you might define a 'button' ControlBar item and set the button text to '{name}'.

The curly braces are how you reference values from the ControlBar's data object. You can use the client side templating syntax when defining the text for a ControlBar item. For example:

{*if dataItem1 == 'A'}{dataitem2}{*else}{dataitem3}{*endif}

For more information on client-side templates see the documentation.

Data values can be set to update automatically when a 'watch' event fires. For example, when the value in a control that is being watched changes, a watch event will fire if that particular control is being watched. Watch events also fire when the UX changes 'state'. For example, when the UX goes from 'clean' to 'dirty', all of the watch events will fire.

You can also manually cause watch events to fire using this UX method:

{dialog.Object}.refreshClientSideComputations();

A common use case for setting data values with watch events is to control the enable/disable or shown/hidden state of ControlBar items. For example, say you have a button in the ControlBar to synchronize data. You would like this button to only be enabled if the List control is dirty.

To do this you would define an entry (call 'SyncDisabled' for example) in the ControlBar's Data collection. Let's assume that the value of the data property will be set to either false or true depending on whether the List has data to synch.

So, the Disabled expression for this button would be:

syncDisabled

We need to turn the value of the SyncDisabled data value to 'on' when the List has dirty data.

If we look at the enable expression for a standard sync button on the UX (button was created using the List genie), we see that the expression is defined as:

(dialog.listDetailView.LIST1.isDirty = true) AND (dialog.listDetailView.LIST1.mode <> 'search')

The syntax used for client-side enable functions is not Javascript. It is a special Xbasic like syntax that gets converted by Alpha Anywhere into Javascript.

The above enable expression can be expressed as a Javascript expression as follows:

(dialog.listDetailView.LIST1.isDirty ) && (dialog.listDetailView.LIST1.mode != 'search')

The watch event for the 'syncDisabled' data value could therefore be defined as:

return !(dialog.listDetailView.LIST1.isDirty ) && (dialog.listDetailView.LIST1.mode != 'search');

Notice that we are returning the inverse of the expression. If the expression (not including the leading ! character, which inverts a logical value) returns true (indicating that the button should be enabled), we want to return false (so that the Disabled expression for the button is false and the button is not disabled).

Disclosures

Disclosures are displayed when the user taps on a 'disclosure-button'. A disclosure can be:

any arbitrary html (defined in the Disclosure sections of the ControlBar builder)
another layout defined in the ControlBar

The images below show a typical use case for disclosures. The images are taken from the Gmail app running on an iPhone. In the first image the Gmail toolbar is shown with the disclosure in its closed state.

In this image the user has tapped on the 'disclosure button' (the down arrow in the above image) and the disclosure is now shown. Notice that the state of the 'disclosure button' has changed and it now displays an up arrow).

Building this type of behavior in your own apps is easy with the ControlBar.

When a disclosure is shown you can specify where on the screen it should be displayed and you can also specify if animation should be used when showing and hiding the disclosure.

You have a great deal of control over where the disclosure is shown. For example, the disclosure might extend below the ControlBar (as it does in the Gmail example shown above), it might overlay the ControlBar, or it might be displayed at a specific location on the screen.

You also have control over how a disclosure is hidden after it has been shown. The disclosure can be set to 'auto-hide' which means that as soon as the user taps on any part of the screen that is not part of the disclosure, the disclosure will close. Alternatively, when the user taps the 'disclosure button' a second time, the disclosure will close.

Only one disclosure can be shown at a time. If a button on a disclosure opens another disclosure, the first disclosure will be closed.

Injectible Content Inside a Disclosure

When you define a disclosure you specify the HTML to be shown by the disclosure. In some cases you will want the disclosure to display standard UX controls (e.g. text boxes, buttons, Lists, etc.)

In order to display standard UX controls in a disclosure you add the controls you want to display in the disclosure to the UX and then you wrap the controls in a Container with a sub-type of InjectibleContent.

Then when you are defining the HTML for the disclosure, you can insert a placeholder for the InjectibleContent. When the disclosure is displayed, the contents of the InjectibleContent container is injected into the disclosure.

ControlBar Methods

The ControlBar has several methods. These methods are documented in detail in the API documentation. Click here for details. This section will describe the more commonly used methods.

Updating ControlBar Data

The ControlBar data is often used to define the text shown on the ControlBar. For example, this pattern is very common:

Define a property in the ControlBar's data (called 'Label1' for example)
Define an HTML item for the ControlBar and set the text for this HTML item to {Label1}
Add this HTML item to the 'before', 'middle', or 'after' section on a 'Line' in a ControlBar Layout.

When the ControlBar is rendered, the text shown on the ControlBar for the HTML item will be the value of the 'Label1' data property.

To change the text that is displayed on the ControlBar you would need to update the value of the 'Label1' data property in the ControlBar. The .update() method is used for this. The .update() method allows you to update a single data property or an array of data properties.

For example:

//get a pointer to the ControlBar
var cbObj = {dialog.object}.getControl('CONTROLBAR_1')

//get the new value
var newValue = {dialog.object}.getValue('LIST1')

//update the data property.
cbObj.update('Label1',newValue);

When you call the <controlBar>.update() method, the ControlBar is automatically refreshed. There is no need to explicitly call the <controlBar>.refresh() method.

If you wanted to update several data properties you pass in an array of data property names and an array of values. For example:

var props = ['prop1','myObj.prop1'];
var vals = ['value1',true];
var cbObj = {dialog.object}.getControl('CONTROLBAR_1');
cbObj.update(props,vals);

It is preferable to update several data properties at once rather than calling the .update() method several times because that will only cause the ControlBar to refresh once, rather than each time the .update() method is called.

You can use Action Javascript to generate the code for the .update() method.

You can also use 'low level' techniques to update the ControlBar data. For example, the following code does the same thing as the .update() method:

//get pointer to ControlBar
var cb = {dialog.object}.getControl('CONTROLBAR_1');

//set a data property directly
cb.data.item1 = 'new value of item1';

//refresh the ControlBar
cb.refresh();

When any data values in the ControlBar data are changes, the ControlBar onChange event fires. The event gets an array of data properties that were changed and an array of the values for these properties.

The onChange event setting

Selecting the Active ControlBar Layout

It is common when using the ControlBar builder to add multiple Layouts to the ControlBar and then to dynamically select which Layout to display. For example, you might define different Layout for for Phone-Landscape, Phone-Portrait, Tablet-Portrait and Tablet-Landscape. The .setLayout() method allows you to dynamically select which Layout to show.

When you set the active Layout you can specify if animation should be used and if so, what type of animation and the animation duration.

For example, the following code sets the active Layout without animation:

var cbObj = {dialog.object}.getControl('CONTROLBAR_1');
cbObj.setLayout('Layout2');

Now, set the active Layout, but this time, use animation.

var cbObj = {dialog.object}.getControl('CONTROLBAR_1');
cbObj.setLayout('Layout2',{"type": "slide-in","duration": 200,"tween": "ease-in-out"});

The active ControlBar Layout can be set in the UX's Responsive Layout Settings. You can also use Action Javascript to generate the code.

As part of the ControlBar definition, you can specify that the active Layout should be dynamically computed using Javascript. Whenever the ControlBar is refreshed (using the .refresh() method), the Javascript to compute the active Layout is executed.

Summary of ControlBar Methods

<controlBar>.action(): Programmatically fire an action of the control bar.
<controlBar>.destroy: Destroy the control bar. This method should be called before the control bar is removed from the DOM.
<controlBar>.hideDisclosure(): Hide the currently shown disclosure.
<controlBar>.initializeItems(): Initialize items in the control bar. This is automatically called when the control bar is created. If item definitions are changed after creation, <controlBar>.initializeItems() must be called in order for the changes to take effect.
<controlBar>.populate(): Populate the control bar with new data.
<controlBar>.refresh(): Refresh the control bar.
<controlBar>.resizeDisclosure(): Resize the currently shown disclosure. This can be used if the layout of the control bar has changed.
<controlBar>.SetLayout(): Sets the ControlBar layout to use. You can specify the type of animation to use when the ControlBar is refreshed.
<controlBar>.showDisclosure(): Show a disclosure. You can specify where the disclosure is shown by specifying a "type". The "expand" family of types will expand the disclosure over the control bar area. In a horizontal layout "before" is left and "after" is right, in a vertical layout "before" is top and "after" is bottom. The "expand-element" type will expand the disclosure for the optionally passed in element, and "expand-element-cover" will do the same only covering the element. The "extend" family will extend the disclosure away from the "edge" defined in A5.ControlBar.edge. By default "extend" will show the disclosure without occluding the control bar. For instance if the "edge" is "top" then the disclosure will dropdown from the bottom edge of the control bar. The "extend-element" type will extend the disclosure for the optionally passed in element, and "extend-element-cover" will do the same only covering the element. The "cover" type will show the disclosure from the "edge" defined in A5.ControlBar.edge, sized to cover the entire control bar. The "outside" family of types will show the disclosure over the area outside the control bar on the opposite side from the edge of the control bar. The "screen" family of types will show the disclosure from the specified edge of the screen. The "explicit" type will show the disclosure in the passed in custom "rectangle".
<controlBar>.update(): Update values in the data. A single path and value may be passed in, or an array of paths and values.

Adding a ControlBar Control to a UX Component

The ControlBar control is one of the Other Controls in the UX Builder. To add a ControlBar control to a UX component, click on the [ControlBar] item in the toolbox, as shown in the image below.

When you add a ControlBar control to the UX you can edit its properties by clicking the smart field for the ControlBar properties property, or you can double click on the entry in the list of selected controls.

The ControlBar properties property

Using the ControlBar Builder

When you open the ControlBar builder the following dialog is shown:

The purpose of each pane in the builder is to define:

ControlBar data
ControlBar items
ControlBar actions
ControlBar layouts
ControlBar disclosures (if any)
Custom CSS used by the ControlBar (if any)
Custom Javascript used by the ControlBar (if any)

Defining Data

The Data pane allows you to define ControlBar data. You can define as many data items as you want.

Each data item has a unique name and a value.

The value can be a string, a JSON object, a Javascript value (e.g. true or false )or a function that returns a value.

For example:

setting1 = 'value of setting 1'
setting2 = {address: '123 main st.', city: 'boston'}
setting3 = {javascript}true

In the second example the data item's value is a JSON object. To refer to one of the properties in the object you use the full path. For example:

setting2.city

The primary purpose (although by no means their only purpose) is to provide content to be displayed on the ControlBar, or to be used in Enable/Disable expressions for controls that are placed on the ControlBar.

For example, you might have an HTML ControlBar item whose html text is set to:

{setting1}

When you edit a Data item or add a new Data item the following screen appears.

A powerful option when defining Data items is to specify that the value of the data item should be updated automatically when a 'watch' event fires. When you define a watch event you can specify which controls you want to watch. For example, if you specify that you want to watch the FIRSTNAME and LASTNAME controls, then whenever the value in one of these controls changes, the watch event will fire.

Watch events also fire when the state of the UX changes. For example, when the UX goes from a 'clean' state to a 'dirty' state.

You can also manually fire watch events using this method:

{dialog.Object}.refreshClientSideComputations([flagSynchronous]);

To specify that a data item should be updated automatically when a 'watch' event fires, click the checkbox on the above dialog. The dialog will change to this:

You can specify which controls you want to watch. You can leave this blank if you only want the watch event to fire when the UX state changes or when watch events are manually fired.

You can also specify the initial value of the data item. This is the value that the data item will have before the watch event fires the first time.

In the Javascript section you define the code that runs when the watch event fires. Your code must return a value. This is the value that the data item will be set to.

Note that your code an reference special 'system' fields (such as dialog.isDirty). The full list of available system fields can be seen by clicking on the 'Insert Field' button.

Defining Items

The Items pane is where you define the ControlBar's items. Items are the 'objects' that you place on the ControlBar layouts. There several different types of ControlBar items. These are: html, htmlTitle, button, button-toggle, button-list, button-disclosure and edit. Each of these is discussed below.

HTML ControlBar Item
The property sheet for the HTML item type is shown in the above image. The properties of note are:
Property
Description
Item size
allows you to specify the size (either width or height depending on whether the ControlBar is horizontal or vertical). You can leave this property blank and a default size will be used.
HTML text
the text you want to display. You can enter any HTML that you want (e.g. "My Mobile App"). The HTML that you enter is actually a client-side template. Therefore you can use client-side templating syntax. For example, to reference a property in the ControlBar's data, enclose the property name in curly braces (e.g. {appname} )
Show expression
a logical expression. If the expression evaluates to false, the item will not be shown on the ControlBar. The expression can reference data properties. For example, you might have a data property called 'UXState' and this property might have a value of 'dirty' or 'clean'. The Show expression could be set to: UXState == 'dirty'
For more information on client-side templates see the documentation.
htmlTitle ControlBar Item
The htmlTitle is used to add title text to the ControlBar layout. The contents of the htmlTitle will be automatically truncated if there is not enough space to display the contents. Users can tap the htmlTitle to view the full text of the item if it has been truncated.
In the image below, the ControlBar htmlTitle is shown on a wide device and a narrow device. Notice that the title text is clipped on the narrow device.
Unlike a html item, the htmlTitle item can be the only item in a Control Bar Layout Line section. For example, in the image below, the Control Bar Layout line is shown for a Control Bar. Notice that the htmlTitle item in the Middle section is the only item in this section.
Button ControlBar Item
ControlBar showing a Button item.
The property sheet for the Button item is shown below:
The standard display types for a button are available. These are:
- Text only
- Image only
- Text followed by Image
- Image followed by text
- Image above text
- Text above image
For buttons that include text, the text is any HTML that you want. You can reference ControlBar data properties in the text. For example {data1}.
The properties of note are:
Property
Description
Item size
allows you to specify the size (either width or height depending on whether the ControlBar is horizontal or vertical). You can leave this property blank and a default size will be used.
Item Actions
You can specify actions to execute on any of the button events (Click, Downhold, etc). You specify the button event by specifying the name of an Action. Actions are defined on the Action tab of the builder (discussed below)
Show expression
a logical expression. If the expression evaluates to false, the button will not be shown on the ControlBar. The expression can reference data properties. For example, you might have a data property called 'UXState' and this property might have a value of 'dirty' or 'clean'. The Show expression could be set to: UXState == 'dirty'
Disabled expression
a logical expression. If the expression evaluates to false, the button will be enabled. If true, the button will be disabled. The expression can reference data properties. For example, you might have a data property called 'UXState' and this property might have a value of 'dirty' or 'clean'. The Disabled expression could be set to: UXState == 'dirty'
Auto-hide disclosure
Specify if any open disclosure should be hidden when the button is tapped.
- Pre-defined Buttons
  Pre-defined buttons are built-in buttons for common tasks, such as searching a List or navigating to a Panel.
- Available Buttons
  Description
  Submit UX
  Uploads data from the UX Component controls and sends it to the Application Server. This is the equivallent of adding a button that calls the {dialog.object}.submit() method.
  Reset UX
  Resets values in all controls in the UX Component to their default values when the componenet was first loaded or after the last Submit action. This is the equivallent of adding a button that calls the {dialog.object}.resetForm() method.
  List DetailView Buttons
  Adds the List Detail View buttons for the specified List to the ControlBar.
  List Search Part Buttons
  Adds the List Search Part buttons for the specified List to the ControlBar.
  List Navigation Buttons
  Adds List Navigation buttons to the ControlBar. The List Navigation Buttons only apply to pageinated lists.
  Set Active Panel
  Adds a button to the ControlBar to activate a Panel Card, Panel Layout, or Panel Navigator.
  Docked Panel controller button
  Adds a button to [activate a Docked Panel].
  List Column Selector
  Adds the List Column Selector, used to reorder or toggle the display of columns in the specified List.
  To add a button, select one of the pre-defined button types and click the Select > button. If prompted, configure the button.
Button-Toggle ControlBar Item
Images show a Button-toggle in its two states: on and off
Button-toggle items can be defined as two-state, or multi-state. If two-state, then each click toggles between the button's true and false states. If multi-state, each click switches to the button's next state.
The property sheet for a button-toggle item is shown below:
The properties of note are:
Property
Description
Item size
allows you to specify the size (either width or height depending on whether the ControlBar is horizontal or vertical). You can leave this property blank and a default size will be used.
Type
whether the button is a two-state or multi-state toggle. If you select multi-state a builder is available to define the different states.
Initial state
for a two-state toggle, this is true or false, For a multi-state toggle, this is a 0 based number indicating which state should initially be selected.
- Multi-state Toggles
  To define a multi-state toggle, set the type to Multi-state and then click the smart field for the builder.
- The multi-state builder is shown below:
  The builder allows you to define as many states as you want. For each state you define the HTML and the Icon. The HTML is used if the Button Layout property is set to a button layout type that includes text. The icon is used if the Button Layout property is set to a button layout type that includes an icon.
  You can also specify the names of the data properties that are added to the ControlBar's Data object to define the multi-state toggle button.
- For example, in the image shown above, we specify that a root variable called myMultiStateButton should be added to the Data object and that the root variable will have two sub-properties (called value and data) that will hold the current state of the button-toggle and the definition of the various button states.
  Here is the Data definition that would be automatically added to the ControlBar's data for the above multi-state button definition:
```
"myMultiStateButton": {
    "value": 1,
    "data": [
        {"html": "State1","icon": ""},
        {"html": "State2","icon": ""},
        {"html": "State3","icon": ""]
    }
```
- If you prefer to add the above data structure to the ControlBar data yourself (on the Data tab of the builder), then you can point the button-toggle to use your hand-coded button-toggle definition by selecting the Point to existing definition in ControlBar data property in the builder.
Button-List ControlBar Item
The image below shows a ControlBar with a button-list Item.

Here is the Data definition that would be automatically added to the ControlBar's data for the above button-list button definition:

"myButtonList": {
    "value": [],
    "data": [
        {"html": "Button1","icon": "svgIcon=#alpha-icon-calendarWeek:icon,24","value": "1"},
        {"html": "Button2","icon": "svgIcon=#alpha-icon-cart:icon,24","value": "2"},
        {"html": "Button3","icon": "svgIcon=#alpha-icon-chartBar:icon,24","value": "3"}
    ]
}

If you prefer to add the above data structure to the ControlBar data yourself (on the Data tab of the builder), then you can point the button-list to use your hand-coded button-list definition by selecting the Point to existing definition in ControlBar data property in the builder.
A common pattern when using a button-list on a ControlBar is to use icons for each button and spread out the buttons so that they fill the width of the screen, as shown in the image below (in a vertical ControlBar, the buttons would fill the height of the screen).
To achieve this look the Fill width property is checked.
Button-Disclosure ControlBar Item
The Button-Disclosure item opens a disclosure when clicked. In the images below, the 'hamburger' button at the left edge of the ControlBar has been defined as a disclosure button.
When the button is clicked, the disclosure is shown (as shown in the image below).
The property sheet for the Disclosure-button item type is shown in the below image.
The properties of note are:
Property
Description
Item size
Allows you to specify the size (either width or height depending on whether the ControlBar is horizontal or vertical). You can leave this property blank and a default size will be used.
Disclosure name
The disclosure to show can either be another Layout (defined on the Layout pane of the builder) or a Disclosure (defined on the Disclosure pane of the builder). In the screen above, the disclosure is set to a Layout called 'menu'
Display type
Defines where the disclosure is displayed. There are many different display types available. See screenshot below. In this above example, the display type is set to outside-before which causes the disclosure to be shown perpendicular to the ControlBar layout (since the ControlBar is horizontal, the disclosure will therefore be vertical). The 'before' segment of the display type indicates that the disclosure will come in from the left edge.
Animate
Allows you to specify the animation (if any) that should be used when the disclosure is shown.
The image below shows the picker for the Display type property.
- Modal Disclosures
  The disclosure opened by the disclosure-button can be modal. This means that the user will not be able to tap anywhere off the disclosure to close the disclosure, but must tap a button on the disclosure itself in order to close the disclosure. To make a modal disclosure:
  Set the Auto-hide property to false.
  Set the Auto-hide disclosure property in the Common Settings section to auto
  Put a button on the disclosure to close the disclosure. The button's action should execute this JavaScript: this.hideDisclosure();
Edit ControlBar Item
The Edit ControlBar item display an edit control in the ControlBar as shown in the image below.
The property sheet for the Edit ControlBar item is shown below:
The properties of note are:
Property
Description
Item size
This property is optional for all ControlBar item types other than the edit type. Allows you to specify the size of the edit item. If the ControlBar is horizontal, size refers to the item width. If the ControlBar is vertical, size refers to the item height.
Update when
specifies when the data variable bound to the edit item should be updated. default - on every keystroke, done - when the edit control loose focus.
Data variable
name of the data variable that gets set to the value entered into the edit control. To set a value in the edit control (for example a default value), simply define the value of the data variable.
Sub-theme
allows you to select a sub-theme for the edit control. In the image above, the edit control is using the primary sub-theme which is defined for the Alpha style.
Watermark text
you can define a watermark that displays in the edit control when the edit control does not have any value.
In the above screenshot, which shows an edit control and a button that performs a search using the value the user typed into the edit control, the search action gets the value that the user entered into the search control using this syntax:
```
this.data.edit1
```
Button-dropdownMenu Item
Left: Expanding menu. Right: Cascading Menu.
The Button-dropdownMenu item displays a dropdown menu when the button is clicked. The menu can be displayed as a Cascading or Expanding menu. In a Cascading menu, sub-menus fly-out from the parent menu item to the left or right. In an Expanding menu, the menu expands vertically to display the sub-menu items below the parent-menu item.
The properties you can se in the menu builder include:
Property
Description
Menu type
either Cascading or Expanding
Method for defining menu
Can be Menu Builder, Static JSON String, or Xbasic Function. The Xbasic Function option allows you to write an Xbasic function to generate the menu choices.
For more information on configuring menu items, see Menu data genie . Note that some properties documented in the "Menu data genie", such as "Value", are not available for the ControlBar Button-dropdownMenu Item because they are not used.

Defining Actions

The Actions pane is where you define the ControlBar's actions. Actions are simply named snippets of Javascript. Once you have defined an action, you can assign the action to an event on a ControlBar item.

The image below shows the Actions pane, showing definitions for several actions.

Defining ControlBar Properties

The ControlBar builder allows you to set several properties as shown in the image below:

'Properties of interest include:

Property: Description
Edge: can be top, left, bottom or right. This is the edge of the screen that the ControlBar will be docked on. For 'left' and 'right' the ControlBar will be vertical.
Select active layout dynamically at run-time: allows you to define Javascript to determine which Layout should be shown. The Javascript is executed when the ControlBar is initially rendered, and each time it is refreshed (using the <controlBar>.refresh() method).

Defining ControlBar Layouts

The ControlBar Layout pane is where you design the visual appearance of the ControlBar. The Layout pane is shown in the image below.

A ControlBar can contain multiple layouts and you can dynamically select which Layout to use at run-time.

The ControlBar Layout pane also includes a preview of the Layout design. You can change the edge for the Layout so you can easily see how the Layout would render in either horizontal or vertical mode. You can also adjust the size of the Layout so you can easily see how (for example) the ControlBar would render on a Phone or a Tablet.

Each ControlBar Layout can have one or more 'Lines'. By default, each 'line' is divided into three sections: Before, Middle and After. You add ControlBar items to any of the sections on a Line. You can also specify a custom Line layout when you can define any HTML that you want. In the HTML you can use placeholder to refer to ControlBar items. See Custom Line Layout below for more detail.

An extremely powerful feature of ControlBar layouts is the ability to dynamically show and hide ControlBar lines. See Show/Hide ControlBar Lines below for more detail.

In the image below, the dialog used to edit a Layout Line is shown.

The dialog shows the three sections of the Line.

Click the Add button to add a new ControlBar item to the appropriate Line section. When you click the Add button, a dialog showing all of the defined ControlBar items is shown.

In addition, two special items are shown:

<separator>
<spacer>

The <separator> will place a subtle line between items before and after the separator. If the ControlBar is rendered horizontally, the separator is a vertical line. If the ControlBar is rendered vertically, the separator is a horizontal line.

The <spacer> will allow you to specify the amount of space (using CSS syntax, e.g. 50px). Depending on the ControlBar orientation, the <spacer> will introduce horizontal or vertical space.

Each Line in a ControlBar layout can be conditionally show/hidden by defining a Show expression for the Line. To do this, click the Line Properties button. If a Line has a defined show expression or class name, the line display will indicate so, as shown in the image below.

Custom Line Layout
To create a custom Line Layout, set the Line type to Custom when editing the Line. When you select the Custom option an HTML editor is shown where you can define the layout of the Line.
You can define any HTML that you want and you can use placeholders in the HTML to inject ControlBar items. For example, say you have defined ControlBar items called html1 and button1.
The HTML that you specify for the custom Layout could look like this:
```
<div>
<p>My custom layout: [html1] [button1]</p>
</div>
```
The Custom HTML is actually a template, so you can use client-side templating commands in the HTML. For example, you could reference the value in a data item (call, say, var1) as follows:
```
{var1}
```
The following example shows how you can use templating syntax in the HTML:
```
{*if var1 == 'alpha'}[button1]{*else}[button2]{*endif}
```
In this example, if the value of var1 is 'alpha' then button1 is shown, otherwise, button2 is shown.
Custom Lines are depicted in the builder as follows:
Show/Hide ControlBar Lines
You can set Line Properties for each Line in a ControlBar layout. To set properties, select the Line and then click the Line Properties button. This opens a dialog where you can set properties.
The Show expression property allows you dynamically show or hide the Line based on an expression that uses the ControlBar data.
For example, assume you have defined a Data item (on the Data tab) called showLine and set its initial value to true.
The Show expression for the Line could be defined as
```
showLine
```
When the ControlBar is initially rendered the Line is shown because the showLine variable is true and therefore the Show expression is true.
To hide the Line you simply set the value of the showLine variable to false.
For example:
```
var cbObj = {dialog.object}.getControl('CONTROLBAR_1');
cbObj.update('showLine',false);
```
By making the Show expression reference a watch variable, the Line can be shown or hidden dynamically, without any user intervention.

Defining ControlBar Disclosures

Disclosures are like pop-up windows that are displayed when a disclosure-button is clicked. You can either specify some explicit HTML to be shown as the disclosure, you can specify that a ControlBar Layout should be shown.

The Disclosure pane in the ControlBar builder (shown in the image below) is used to define Disclosures that display explicitly defined HTML.

When you want to display standard UX controls (such as input controls, Lists, buttons, ViewBoxes, etc.) in a disclosure, you define a new disclosure on the Disclosure pane and then, when defining the HTML for the disclosure, you can add the contents of a InjectibleContent container to the disclosure. See below for more details.

Using the a5-actions Attribute in Disclosure HTML
When you define the HTML for a disclosure you can use the a5-actions attribute to invoke actions. For example, assume you have defined an Action called action1 and that you have defined the following HTML for the disclosure:
```
<div a5-action="action1">
    Tap here to do some task
</div>
```
When the disclosure is displayed and the user taps on the div, the Javascript defined in action1 will be executed.
More on Injectible Content
In the two images below, the second button from the left has been defined as a disclosure button. The first image shows the disclosure closed.
The next image shows the disclosure open. The disclosure contains a standard List control.
Here is how this was defined.
First the List that you want to display is added to the UX and then wrapped in an Injectible Content container.
Next, the HTML editor for the disclosure is opened and the following text is inserted into the HTML (using the 'Insert content from an 'Injectible Container' hyperlink).
When using the Alpha style, the List may not render correctly (the rows that don't have focus are not visible). To solve this, we added the following to the List's in-line style: color: #000; background: #fff;
Creating Disclosure Forms
Disclosures can be used to display simple forms, without the need to use Injectible Content. (With Injectible Content, the forms displayed in disclosures can be arbitrarily complex). The advantage of defining forms that do not use Injectible Content is that the ControlBar has no external dependencies and the UX as a whole is lighter weight (i.e. has fewer controls defined in the UX builder).
An example of a simple form displayed in a Disclosure is shown below.

The HTML for the above form is defined in the Disclosure HTML property as follows:

<div style="padding:10px;">
    [[labelField1]]
    [[inputField1]]
    [[labelField2]]
    [[inputField2]]
    <br>
<div style="float:right; margin-top:10px; margin-bottom:10px;">
        [[buttonOK]]&nbsp;
        [[buttonCancel]]
    </div>
</div>

The HTML contains special placeholder for the labels, input fields and buttons shown in the dialog. For example

[[buttonOK]] is a placeholder for the OK button.

These placeholders are defined when you edit the Disclosure HTML and are stored in the Disclosure HTML in an HTML comment. For example:

<!--controls
[
    {
        "controlId": "buttonOK",
        "id": "buttonOK",
        "layout": "Text only",
        "html": "OK",
        "action": "DisclosureOK",
        "type": "button"
    },
    {
        "controlId": "buttonCancel",
        "id": "buttonCancel",
        "layout": "Text only",
        "html": "Cancel",
        "action": "DisclosureCancel",
        "type": "button"
    },
    {
        "controlId": "labelField1",
        "id": "labelField1",
        "text": "Field 1 Label",
        "type": "label"
    },
    {
        "controlId": "labelField2",
        "id": "labelField2",
        "text": "Field 2 Label",
        "type": "label"
    },
    {
        "controlId": "inputField1",
        "id": "inputField1",
        "variable": "field1",
        "style": "width: 100%",
        "watermark": "Field 1",
        "javascript": {
        },
        "type": "input"
    },
    {
        "controlId": "inputField2",
        "id": "inputField2",
        "variable": "field2",
        "style": "width: 100%",
        "watermark": "Field 2",
        "javascript": {
        },
        "type": "input"
    }
]
controls-->

The Disclosure HTML editor (shown in the image below) has a hyperlink (Disclosure Form Builder), that opens a genie which allows you to define the controls used in your form. When you close the genie, the HTML comment (that defines the form controls) is inserted into the HTML.
The Disclosure Form Builder dialog is shown in the image below. This dialog allows you to define the controls that the Disclosure form will display.
For example, in the image below a button with a control id of buttonOK is defined. To use this control in the form, the placeholder [[buttonOK]] is used.
You can type the placeholder into the HTML yourself, or use the Insert... hyperlink.

Messages

ControlBar disclosures are ideal for displaying message dialogs. For example, in the image below, three common types of messages are shown. These message dialogs are all implemented as Disclosures (using the custom ControlBar layouts).

A pre-defined library of Layouts, Actions, Items and CSS can be added to any ControlBar to make it easy to display the message dialogs shown in the image below.

This will add several Items, Actions, Layouts, methods and CSS class definitions to your ControlBar definition.

Then, to start display a message dialog define an Action and use the genie to generate the Javascript code to display a message dialog.

In the image below the Actions pane in the ControlBar builder is shown. Below the edit area, a hyperlink (Code genie...) is shown.

Select the Display a message option from the menu.

This will bring up a dialog where you can specify the type of message dialog you want to show. Define the message properties, then press OK. The genie will show the code you need to use to display the message dialog.

For example, the Javascript to display a basic message is:

this.showBasic('Message Title', 'Message body', 'OK', function(cbar) { });

Once you have added the Messaging Functions to your ControlBar definition, you can also display message dialogs from any Javascript code on the UX (i.e. you are not limited to Actions within the ControlBar).

The Javascript to display a message dialog can be generated using Action Javascript. The image below shows the Action Javascript dialog for the ControlBar Actions action.

In the example Javascript shown above, the Javascript defined in the ControlBar action to display a basic message is:

this.showBasic('Message Title', 'Message body', 'OK', function(cbar) { });

If you want to display the same basic message by clicking (say) a button (that is not part of the ControlBar) on the UX, the Javascript would be:

var cbObj = {dialog.object}.getControl('CONTROLBAR_NAME');

cbObj.showBasic('Message Title', 'Message body', 'OK', function(cbar) { });

Notice that instead of using this, a pointer to the ControlBar object is used.

Videos

Introduction to Basic Concepts

This video demonstrates basic concepts of the ControlBar control.

Watch Video

2016-09-14

Updating ControlBar Data - Dynamic Text

This video demonstrates how you can update the data in the ControlBar's data. This allows you to put dynamic text in the ControlBar. We also show how the ControlBar can be animated when it is refreshed.

Watch Video

2016-09-14

Using Watch Events to Update ControlBar Data

The ControlBar data can be updated automatically in response to certain events in the UX (such as the UX going dirty, a List going dirty, etc.) or by a change in the value of one or more controls.

In this video we show how you can configure watch events to automatically update ControlBar data.

Watch Video

2016-09-14

Adding a Button to a ControlBar

In this video we show how you can add a button to a ControlBar and then associate an action (i.e. some Javascript code) to run when the button is tapped.

Watch Video

Download Component

2016-09-14

Adding a Button-Toggle to a ControlBar

In this video we show how you can add a Button-Toggle to a ControlBar. Toggle buttons can either be two-state (switching between a true and a false state), or multi-state (each click advances to the next button state).

The video shows how the state of a Button-Toggle is used to control what action a button performs when clicked.

Watch Video

Download Component

2016-09-14

Adding a Button-List to a ControlBar

A common pattern in mobile apps is to have a button bar at the bottom of the screen with a series of buttons that allow you to select the active Panel that is shown on the device. Typically, these buttons are spread out so that they fill the width of the screen.

The button-list control is ideal for implementing this pattern.

In this video we show how a Button-List can be configured to fill the width of the screen and to select a Panel Card in a Panel Layout when one of the buttons in the Button-List is tapped.

Watch Video

Download Component

2016-09-14

Selecting the Active ControlBar Layout

A ControlBar can have multiple Layouts. In this video we show how you can dynamically select the Layout to show.

Watch Video

Download Component

2016-09-14

Showing a Disclosure

A disclosure can be some explicitly defined HTML, or it can be another Layout. In the video, we first show how a disclosure, defined as a ControlBar layout, is shown.

One of the more unusual disclosure types is Outside-After (and Outside-Before) which display the disclosure perpendicular to the parent Layout. In the second half of the video, we show how the disclosure is rendered when the Outside-After type is selected.

Watch Video

Download Component

2016-09-14

Showing a List in a Disclosure

You can display standard UX controls (such as Lists, Buttons, Input controls, etc.) in a disclosure. In this video we show how a list is displayed in a disclosure.

Watch Video

Download Component

2016-09-14

Setting the Selected Button in a Button List using Javascript

The selected button(s) in a ControlBar Button List can be set programmatically using Javascript. It is also possible to completely change the buttons shown in a Button List programmatically.

In this video we show how this is done.

Watch Video

Download Component

2016-09-21

Defining Javascript in a ControlBar - Understanding the 'This Object' Option. Using Javascript function in a template.

When you define Javascript functions in a ControlBar (and also a ViewBox and FormView control), you can specify where the Javascript should be stored. The options are: At the control level, at the UX level and 'This object'.

This video explains the options and discusses why the 'This object' option is best. It also describes how functions defined at the 'This object' level can be referenced in templates.

Watch Video

Download Component

2016-09-28

Dynamically Showing and Hiding Lines in a ControlBar Layout

A ControlBar layout can have multiple Lines. Each Line in a Layout can be dynamically shown or hidden.

This video shows how a show expression can be defined for a Line in a ControlBar Layout

Watch Video

Download Component

2016-09-28

Adding an Edit ControlBar Item to a ControlBar

A ControlBar typically contains text and buttons, but a common use case is to build a Search ControlBar that uses an edit control in the ControlBar.

In this video we show how the edit ControlBar item type can be used to build a Search feature.

Watch Video

Download Component

2016-10-08

Displaying a Modal Pop-up Form using a Disclosure

A common pattern in many applications (both Mobile and Desktop web) is to display pop-up modal forms to collect some information from the user. Displaying pop-up modal forms using the ControlBar is very easy and extremely powerful.

This video shows how a ControlBar 'disclosure' is used to display a pop-up modal form. The 'a5-action' attribute in the Disclosure HTML is used to invoke actions defined in the ControlBar's Action pane.

Watch Video

Download Component

2016-10-08

Defining Disclosure Forms using the Disclosure Form Builder

In the video 'Displaying a Modal Pop-up Form using a Disclosure' we show how a modal pop-up form can be displayed using a Disclosure. The definition of the HTML for the form is fairly tedious because it is completely hand coded.

In this video we show how the Disclosure Form Builder can be used to make it easier to define the form HTML.

Watch Video

Download Component

2016-10-30

Display Modal Message Dialogs using Disclosures

Modal messages (such as confirmations, progress, feedback) as commonly used when designing the user interface for an application. ControlBar disclosures make displaying these messages particularly easy.

In this video we show how the ControlBar can be configured to display three different types of message dialogs: basic information dialogs (one button), confirmation dialogs (two buttons) and wait dialogs (no buttons).

Watch Video

Download Component

2016-10-30

Adding List Navigation Buttons to a ControlBar

When you define a List control, you can specify that the List should be paginated. If you set the pagination method to 'Navigation Buttons' then you must define buttons to move to the next and previous page of records. In a mobile application that uses a ControlBar in a Panel header or footer, it is desirable to place these navigation buttons in the ControlBar.

In this video we show how you can quickly add List navigation buttons to a ControlBar by selecting the 'Pre-defined buttons' option when adding ControlBar items to your ControlBar definition.

Watch Video

2016-11-05

Tutorial - Building a Mobile Master-Detail Form using The List, FormView and ControlBar Controls

In this video tutorial we show how a mobile app can be built to implement a master-detail form using the FormView control. The app will allow users to edit data from the Customers and Orders table in the sample Northwind database. This is a classic master-detail form: Each customer has multiple orders. The UX component uses two Lists joined in a parent-child relationship. The parent List displays data from the Customer table and the child List display the related orders from the Orders table.

Each List has a Detail View, but in both cases, the Detail View is implemented using the FormView control.

Once the basic functionality of the app has been built, the app is 'mobilized' by wrapping the various sections of the component in PanelCards and a ControlBar is added to implement navigation between the various parts of the application.

Watch Video

Download Component

2016-11-10

Dropdown Menu

A common pattern when designing a ControlBar is to include a button to display a dropdown menu. Menus can either be cascading or expanding menus. In this video, we show how to add a dropdown menu to a ControlBar.

Watch Video

2019-11-05

Report an issue with this page