Form

Overview

A form is an object that provides an UI and/or contains business logic; it's the basic user interface object in Servoy. The UI of a Form is built up of Form Parts, which in turn contain Elements (and layout containers in case of advanced layout).

Forms are also a unit of scope in Servoy, meaning that forms can have variables and methods attributed to them.

Properties Summarized

Type	Name	Summary
String	comment	Additional information, such as programmer notes about this form's purpose.
String	dataSource	The names of the database server and table that this form is linked to.
String	deprecated	Gets the deprecation info for this element.
Object	designTimeProperties	Property to get and add design-time properties for a component.
Number	encapsulation	The encapsulation mode of this persist.
Number	extendsForm	The selected parent (extended element) for the element (form).
Boolean	formComponent
Number	height	The height of the form in pixels.
String	initialSort	The default sort order only when the form loads.
String	name	The name of the form.
String	namedFoundSet	Property that tells the form to use a named foundset instead of the default foundset.
Number	navigator	The navigator (previously named "controller") that is used to control/navigate to the form.
Number	scrollbars	Scrollbar options for the vertical and horizontal scrollbars.
Number	selectionMode	Returns the value of the selectionMode property.
String	styleClass	The Cascading Style Sheet (CSS) class name applied to the form.
String	titleText	The text that displays in the title bar of the form window.
Boolean	transparent	When set, the form is transparent.
Boolean	useMinHeight	If true then the min-height css property will be set for this form so it has a default minimum height.
Boolean	useMinWidth	If true then the min-with css property will be set for this form so it has a default minimum width Can return null so that the default system value should be used.
Number	width	The width of the form in pixels.

Commands Summarized

Type	Name	Summary
void	onSort	The method that overrides the Servoy menu item Select > Sort.

Events Summarized

Type	Name	Summary
Boolean	onBeforeHide(event)	This method is triggered when the form wants to hide; this will be called before onHide, and should be used to return if this form can be hidden or not.
Boolean	onElementDataChange(oldValue, newValue, event)	Method that is executed when the data in one of the form's component is successfully changed and the onDataChange callback from the component does not exist or exists and returned true.
Boolean	onElementFocusGained(event)	The method that is triggered when focus is gained by a component inside the form.
Boolean	onElementFocusLost(event)	The method that gets triggered when focus is lost by a component inside the form.
void	onHide(event)	This method is triggered when the form gets hidden.
void	onLoad(event)	The method that is triggered when a form is loaded/reloaded from the repository; used to alter elements, set globals, hide toolbars, etc; onShow method can also be assigned.
Boolean	onRecordEditStart(event)	The method that is triggered when a user starts editing a record (for example by clicking into a cell of a table, or editing a field who's data-provider is from that record).
Boolean	onRecordEditStop(record, event)	The method that is triggered when a record is being saved.
void	onRecordSelection(event)	The method that is triggered each time a record is selected.
void	onResize(event)	The method that gets triggered when resize occurs.
void	onShow(firstShow, event)	The method that is triggered EVERY TIME the form is displayed; an true argument will be passed to the method if this is the first time the form is displayed.
void	onUnLoad(event)	The method that is triggered when a form is unloaded from the repository.

Properties Detailed

comment

Additional information, such as programmer notes about this form's purpose.

Type String

Sample

"shows table with order details"

dataSource

The names of the database server and table that this form is linked to.

Type String

Sample

example_data.order_details

deprecated

Gets the deprecation info for this element.

Type String the deprecation info for this object or null if it is not deprecated

Sample

"not used anymore, replaced with ..."

designTimeProperties

Property to get and add design-time properties for a component.

Type Object map of the design-time properties

encapsulation

The encapsulation mode of this persist. The following can be used/checked:

• Public (not a separate option - if none of the below options are selected)

• Hide in scripting; Module Scope - it will not be available in scripting from any other context except the form itself. Available in designer for the same module

• Module Scope - it will be available in both scripting and designer, but only in the same module

• Hide Dataproviders (checked by default) - the form's dataproviders will not be available from any other context except from the form itself

• Hide Foundset (checked by default) - the form's foundset will not be available from any other context except from the form itself

• Hide Controller - the form's controller will not be available from any other context except from the form itself

• Hide Elements (checked by default) - the form's elements will not be available from any other context except from the form itself

• Hide Containers (checked by default) - the form's containers will not be available from any other context except from the form itself.

Type Number the encapsulation mode/level of the persist.

Sample

"Hide Dataproviders, Hide Foundset, Hide Elements, Hide Containers"

extendsForm

The selected parent (extended element) for the element (form).

Type Number the parent

Sample

"ordersForm"

formComponent

Type Boolean

height

The height of the form in pixels.

Type Number

initialSort

The default sort order only when the form loads. This is applied each time an internal SQL query is being executed (find, find-all, open form); and is only executed when no other manual sort has been performed on the foundset.

Type String

Sample

"shipname asc,orderid desc"

name

The name of the form.

Type String

Sample

"orderDetails"

namedFoundSet

Property that tells the form to use a named foundset instead of the default foundset. When "separate" as special value is specified the form will always create a copy of assigned foundset and therefor become separated from other foundsets. When "empty" it will initially load an empty foundset. When a global relation name it will load the a related foundset.

Type String

Sample

"", or "separate" or "empty"

navigator

The navigator (previously named "controller") that is used to control/navigate to the form. The navigator is shown at the left or at the right side of the form, depending on the page orientation.

The following options are available:

-none- - no navigator is assigned. DEFAULT - the Servoy default navigator is assigned. IGNORE - the navigator last assigned to a previous form. Custom - a custom navigator based on a selected form.

Type Number

scrollbars

Scrollbar options for the vertical and horizontal scrollbars. Each of the vertical and horizontal scrollbars can be configured to display all the time, to display only when needed or to never display.

Type Number

Sample

horizontal : "when needed"
vertical : "always"

selectionMode

Returns the value of the selectionMode property.

Type Number one of IForm#SELECTION_MODE_DEFAULT, IForm#SELECTION_MODE_SINGLE and IForm#SELECTION_MODE_MULTI.

Sample

"" or "SINGLE" or "MULTI"

styleClass

The Cascading Style Sheet (CSS) class name applied to the form.

Type String

Sample

"content-panel"

titleText

The text that displays in the title bar of the form window. NOTE: Data tags and Servoy tags can be used as part of the title text.

Type String

Sample

"Order Details"

transparent

When set, the form is transparent.

Type Boolean

useMinHeight

If true then the min-height css property will be set for this form so it has a default minimum height.

Can return null so that the default system value should be used.

Type Boolean true if it should use the min-height in the browser

useMinWidth

If true then the min-with css property will be set for this form so it has a default minimum width

Can return null so that the default system value should be used.

Type Boolean true if it should use the min-width in the browser

width

The width of the form in pixels.

Type Number

Events Detailed

onBeforeHide(event)

This method is triggered when the form wants to hide; this will be called before onHide, and should be used to return if this form can be hidden or not. Before the form is really going to hide, this form and all the forms that this form is also showing in its ui hierarchy must allow the hide (return true in onBeforeHide - if present).

For example, when using onBeforeHide with showFormInDialog, the form will not close by clicking the dialog close box (X) if the main form in the dialog or any of the other visible forms in tabpanels/containers are nested in the main are returning false.

If the hide operation is allowed for all the forms that are in the affected visible hierarchy, then the onHide handler/method will get called on them as well afterwards.

So this handler (on each form) can be used to validate input in the main form and/or any nested visible forms - that are getting ready to hide.

Parameters

• JSEvent event the event that triggered the action

Returns: Boolean

Sample

/*
 * Check if this form can be hidden, return false if this is not allowed.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @return {Boolean}
 *
 * @properties={typeid:24,uuid:"E37CE276-2B94-47EC-96DA-D631BC344D52"}
 */
function onBeforeHide(event) {
    //reset form variables:
    dialogTitle = '';
    dialogMessage = '';
    dialogDate = '';
    return true;
}

onElementDataChange(oldValue, newValue, event)

Method that is executed when the data in one of the form's component is successfully changed and the onDataChange callback from the component does not exist or exists and returned true.

Parameters

• ${dataproviderType} oldValue old value

• ${dataproviderType} newValue new value

• JSEvent event the event that triggered the action

Returns: Boolean

Sample

/*
 * Handle changed data, return false if the value should not be accepted. In NGClient you can return also a (i18n) string, instead of false, which will be shown as a tooltip.
 *
 * @param oldValue old value
 * @param newValue new value
 * @param {JSEvent} event the event that triggered the action
 *
 * @return {Boolean}
 *
 * @properties={typeid:24,uuid:"06284668-8CBA-4F90-8C31-D304D486DB5C"}
 */
function onElementDataChange(oldValue, newValue, event) {
    var errors = [];
    var validName = new RegExp(/^[A-Za-z0-9-]*$/gm).test(newName);
    if(!validName) {
        errors.push('invalid');
    }
    if(!newName.length) {
        errors.push('empty');
    }

    return errors.length == 0;
}

onElementFocusGained(event)

The method that is triggered when focus is gained by a component inside the form.

Parameters

• JSEvent event the event that triggered the action

Returns: Boolean

Sample

/*
 * Handle focus gained event of an element on the form. Return false when the focus gained event of the element itself shouldn't be triggered.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @return {Boolean}
 *
 * @properties={typeid:24,uuid:"7E89E3D4-EF0F-4111-8107-D491884E4114"}
 */
function onElementFocusGained(event) {
    var elementName = event.getElementName();
    elements[elementName].addStyleClass('backgroundGreen');
    return true;
}

onElementFocusLost(event)

The method that gets triggered when focus is lost by a component inside the form.

Parameters

• JSEvent event the event that triggered the action

Returns: Boolean

Sample

/*
 * Handle focus lost event of an element on the form. Return false when the focus lost event of the element itself shouldn't be triggered.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @return {Boolean}
 *
 * @properties={typeid:24,uuid:"9E5C79CE-4A3A-4DD9-AD48-E9EB0A71BD97"}
 */
function onElementFocusLost(event) {
    var elementName = event.getElementName();
    elements[elementName].removeStyleClass('backgroundGreen');
    return true;
}

onHide(event)

This method is triggered when the form gets hidden.

Return value is DEPRECATED: false return value should no longer be used. In the past, if the onHide method returned false, the form hide could be prevented from happening in some cases (for example, when using onHide with showFormInDialog, the form will not close by clicking the dialog close box (X)). But that lead to unexpected situations when the form being hidden had visible nested children it it (tab panels, splits etc.) because only the current form would decide if hide could be denied, and all other forms, even if they returned false in their on-hide, would not be able to block the hide if this form allowed it. So those nested forms might think that they are still visible even though they are not.

Please use the new onBeforeHide method/handler instead if you want to prevent forms from hiding.

Parameters

• JSEvent event the event that triggered the action

Returns: void

Sample

/*
 * Handle form's hide.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @properties={typeid:24,uuid:"2D7F156A-E2D8-4DE8-82C9-A9419AA9EB88"}
 */
function onHide(event) {
    databaseManager.revertEditedRecords();
}

onLoad(event)

The method that is triggered when a form is loaded/reloaded from the repository; used to alter elements, set globals, hide toolbars, etc; onShow method can also be assigned.

NOTE 1: onShow should be used to access current foundset dataproviders; onLoad cannot be used because the foundset data is not loaded until after the form is loaded. Also calls to loadRecords() should be done in the onShow method and not in the onLoad method. If you call loadRecords() in the onShow method, you may want to set the namedFoundSet property of the form to 'empty' to prevent the first default form query.

NOTE 2: the onLoad event bubbles down, meaning that the onLoad is first fired on the parent then on a tab in a tabpanel (and in tab of that tab panels if you are 3 deep)

Parameters

• JSEvent event the event that triggered the action

Returns: void

Sample

/*
 * Callback method when form is (re)loaded.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @properties={typeid:24,uuid:"106353C5-73F9-4FEB-8391-6F3B46EB7521"}
 */
function onLoad(event) {
    // TODO Auto-generated method stub
    elements.fc_orderslist.putClientProperty(APP_UI_PROPERTY.LISTFORMCOMPONENT_PAGING_MODE, true);
}

onRecordEditStart(event)

The method that is triggered when a user starts editing a record (for example by clicking into a cell of a table, or editing a field who's data-provider is from that record).

Parameters

• JSEvent event the event that triggered the action

Returns: Boolean

Sample

/*
 * Callback method form when editing is started.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @return {Boolean}
 *
 * @properties={typeid:24,uuid:"061C702A-CE14-4B9A-9393-7BA3D24988A1"}
 */
function onRecordEditStart(event) {
    // TODO Auto-generated method stub
    var elementName = event.getElementName();
    elements[elementName].addStyleClass(‘grayBorder’);
    return true;
}

onRecordEditStop(record, event)

The method that is triggered when a record is being saved. A record is saved when a user clicks out of it (for example on an empty part of the layout or to another form).

When this event handler returns false (for example as part of a validation), the user cannot leave the record (change selected record).

Parameters

• JSRecord record record being saved

• JSEvent event the event that triggered the action

Returns: Boolean

Sample

/*
 * Callback method form when editing is stopped, return false if the record fails to validate then the user cannot leave the record.
 *
 * @param {JSRecord<db:/example_data/orders>} record record being saved
 * @param {JSEvent} event the event that triggered the action
 *
 * @return {Boolean}
 *
 * @properties={typeid:24,uuid:"A63A8831-0D38-4526-ADB5-31B519BE97A9"}
 */
function onRecordEditStop(record, event) {
    var elementName = event.getElementName();
    elements[elementName].removeStyleClass('grayBorder');
    return true;
}

onRecordSelection(event)

The method that is triggered each time a record is selected.

NOTE 1: Data and Servoy tag values are returned when the onRecordSelection method is executed. NOTE 2: this will also fire if the selection goes to -1 because the foundset is cleared. So foundset.getSelectedRecord() can return null.

Parameters

• JSEvent event the event that triggered the action

Returns: void

Sample

/*
 * Handle record selected.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @properties={typeid:24,uuid:"5D614C43-89B3-41D5-941B-0C83CA4D3039"}
 */
function onRecordSelection(event) {
    scopes.globals.selected_user_name = foundset.getSelectedRecord().user_name;
}

onResize(event)

The method that gets triggered when resize occurs.

Parameters

• JSEvent event the event that triggered the action

Returns: void

Sample

/*
 * Callback method when form is resized.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @properties={typeid:24,uuid:"57CF650F-0481-42DA-A0C4-13AA2001D877"}
 */
function onResize(event) {
    //setting the dividerLocation of a splitpane at the onResize of the form
    var w = controller.getFormWidth();
    elements.split.dividerLocation = w / 2;
}

onShow(firstShow, event)

The method that is triggered EVERY TIME the form is displayed; an true argument will be passed to the method if this is the first time the form is displayed.

NOTE 1: onShow can be used to access current foundset dataproviders; onLoad cannot be used because the foundset data is not loaded until after the form is loaded. NOTE 2: the onShow event bubbles down, meaning that the onShow event of a form displayed in a tabPanel is fired after the onShow event of the parent.

Parameters

• Boolean firstShow form is shown first time after load

• JSEvent event the event that triggered the action

Returns: void

Sample

/*
 * Callback method for when form is shown.
 *
 * @param {Boolean} firstShow form is shown first time after load
 * @param {JSEvent} event the event that triggered the action
 *
 * @properties={typeid:24,uuid:"A8C02494-8CA0-4D89-A332-F308E117D259"}
 */
function onShow(firstShow, event) {
    elements.error.visible = false;
}

onUnLoad(event)

The method that is triggered when a form is unloaded from the repository.

NOTE: Forms can be prevented from being removed from memory by referencing the form object in a global variable or inside an array inside a global variable. But do take care when using this technique. Forms take up memory and if too many forms are in memory and cannot be unloaded, there is a possibility of running out of memory.

Parameters

• JSEvent event the event that triggered the action

Returns: void

Sample

/*
 * Callback method when form is destroyed.
 *
 * @param {JSEvent} event the event that triggered the action
 *
 * @properties={typeid:24,uuid:"11CEDAE7-ED62-4444-9C02-5E5D7FAC0EA4"}
 */
function onUnload(event) {
    // Unloads the datasource (only do this when no form is using it anymore)
    databaseManager.removeDataSource(uri);
}

---