Groupbox

The Groupbox control is used for grouping multiple controls. A Groupbox control can have its own layout and alignment, independent of its parent container or XForm. The Groupbox control is visible during runtime.

Groupbox controls can be data-bound or free-form controls. When data-bound, a Groupbox control is bound to a model from which it fetches data. If you do not specify any model, the model of the parent control is associated, by default. You can use a free-form Groupbox control to display any arbitrary data. A Groupbox control can have both an Element bar and a Navigation bar. This enables navigation between records, and provides the ability to insert and delete objects.

By default, the first available business object in the model is bound to the Groupbox control. The controls in the Groupbox, for which the reference attribute is defined, are bound to and display the values of the business object.

In order to improve the performance and reduce the loading time of a Web page containing a Groupbox control, you can set the control as an load-on-demand control. This means that for load-on-demand controls, all child controls in it are rendered as plain HTML when an application is loaded for the first time. However, as no data or API is available for the child controls, they are not ready for use. On expanding the control, the child controls are initialized and their APIs are available for use.

Properties, Events, and Methods of the Control

The Groupbox control has certain properties, events, and methods associated with it. They define the behavior of the control and can be set through the property page of the control or programmatically using the APIs.

Table 1. List of Properties

Table 2. List of Events

Design-time property	Runtime property	Description
ID		Sets the string that identifies the control on an XForm. If not specified, a unique ID is automatically generated.
Model		Sets the ID of the data model from which the data (specified using the Reference property) is displayed in the control. If model is not specified, it is inherited from the parent control's model.
Reference (xql)		Sets the location or expression for the XPath that contains the data (value) displayed in the control. The XPath refers to the child node or descendants of the immediate parent control's reference.
Parent		Specifies the data binding from the parent. The selected parent is used as the starting point for data references.
Class Name	className	Sets or retrieves the class name applied on the control.
Tooltip	title	Sets the tool tip that appears on a control when the mouse is moved over it. Programmatically, this property is set by specifying the title property of the control.
Resizable		Select to enable the resizing of control at run time. Note: It is not possible to resize the control beyond the XForm or its parent control. This functionality is disabled if the position of the control is set to free or the layout of the parent control or XForm is set to free.
Task Part		Creates a task part for the control. Selecting the check box, displays the Task Part pane.
Collapsible		Denotes whether the Groupbox control is collapsible. If checked, the Groupbox displays a toggle button on the right side of its title bar; clicking the toggle button collapses and expands the control. By default, it is unchecked.
Expand on Load		Denotes whether a collapsible Groupbox control will appear in the expanded mode when the XForm is loaded. This property is enabled only a Groupbox that is collapsible. By default, it is checked, and the Groupbox remains in the expanded mode when the XForm loads.
Load content when group is expanded		Sets the control as a load-on-demand control. This means that when a page is loaded for the first time at run time, the control is initialized (loaded with content) only when you expand it.
Control bar		Denotes whether a Groupbox control contains a control bar. When checked, a control bar appears on top of the Groupbox control. By default, it is unchecked.
Pagination bar		Denotes whether a Groupbox control contains a pagination bar. When checked, a pagination bar appears on top of the Groupbox control. By default, it is unchecked.
	businessObject	Retrieves the root node of the XML data associated with the control; the location of the data is specified by the Reference property.
	currentContext	Retrieves the immediate parent of the data that the control represents. This data is the child node of the business object.
	navigator	Retrieves an object through which the Control bar and Pagination bar button objects can be accessed at runtime.
	view	Retrieves the view object of the data model bound to the control.
	data	Retrieves the XML node of the data (value) that the control represents. The location (XPath) of this XML inside the business object is set through the Reference property.

Table 3. List of Methods

Event	Description
Data Bind	This event is activated before the data is bound to a control.
xform-oncollapse	This event is activated when you collapse a Groupbox control.
xforms-oninitialize	This event is fired after a load-on-demand control is selected and its content loaded. You can use this event to perform operations such as setting default values, and retrieving data from Web services and binding it to the child controls.
xform-onexpand	This event is activated when you expand a Groupbox control.

Method	Description
addListener()	This method registers the control to receive notifications for an event.
collapse()	This method collapses the Groupbox control such that only the header is visible. This method applies only if the Collapsible property is set totrue.
create()	This method is available for data-bound controls only. It creates an instance of the business object for the control.
disable()	This method disables the control on which it is invoked.
enable()	This method enables the control on which it is invoked.
expand ()	This method expands the Groupbox to display it. This method applies only if the Collapsible property is set totrue.
find()	This method displays the Find dialog box. This is equivalent to clicking in the navigation bar.
getBusinessObject()	This method retrieves data or business object.
getFirstDataset()	This method clears the current model's data and retrieves the first set of records from the application service.
getLabel()	This method returns the label object that is associated with the control.
getLastDataset()	This method clears the current model's data and retrieves the last set of records from the application service.
getNextDataset()	This methods sends a request to the application service for the next set of records, if available.
getPreviousDataset()	This methods sends a request to the application service for the previous set of records, if available.
hide()	This method hides controls and all associated child controls.
isEnabled()	This method retrieves the value that denotes whether the control is enabled or not.
isinitialized()	This method returns the initialization status of child controls in the control that is set to load on demand, that is for which the Load content when group is expanded option is selected in the property sheet. Possible return values are: true: the child controls are intitalized and ready for use. false: the child controls are not initialized and are not ready for use. Only the plain HTML of the child controls is available in the Web page and no APIs are available. Note: If you need to initialize a load-on-demand control before a user clicks it, you can use the expand() method to load it programmatically.
rebind(oBusinessObject)	This method is available for all controls bound to a model. This method refreshes the control with data from the business object that is passed as a parameter. If no parameter is passed, the business object of the model's activeTuple node is used and the control is refreshed.
refresh()	This method reverts the latest unsaved changes, and binds the control to the latest business object.
remove()	This method is available only for data-bound controls. It removes the instances marked for deletion.
removeListener()	This method unregisters the control to cease receiving notifications for its events.
setFocus()	This method causes an element to receive focus.
setLabel()	This method sets the text (that is passed as a parameter) to the label object of the control.
show()	This method makes the control and its children controls visible.

pp108 : Groupbox

Groupbox

Properties, Events, and Methods of the Control