Form

Overview

A form is an object that provides a 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. Forms are also a unit of scope in Servoy, meaning that forms can have variables and methods attributed to them.

Property Summary

Type	Name	Summary
String	comment	Additional information, such as programmer notes about the form's purpose.
String	dataSource	The names of the database server and table that this form is linked to.
String	deprecated	Gets the deprecate 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).
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	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.
Number	view	The default form view mode.
Number	width	The width of the form in pixels.

Events Summary

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 clicks into a column on the form.
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 argument must 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 Details

comment

This is a field for additional information, such as programmer notes about the 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. It is selectable from all available tables and has this format: "server-name.table-name".

Type String

Sample

example_data.order_details

deprecated

Gets the deprecate info for this element

Type String the deprecate info for this element or null if it is not deprecated

Sample

"not used anymore, replaced with 'ordersdetails_new' form"

designTimeProperties

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

Type Object map of the design-time properties

Sample

{formDisplayName:"Order Details"}

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 - not available in scripting from any other context except the form itself. Available in designer for the same module.

• Module Scope - available in both scripting and designer but only in the same module.

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

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

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

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

• Hide Containers (checked by default) - form's containers not available from any other context except 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 String the parent

Sample

"orders"

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. Format: "column_name asc" / "column_name desc"

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"

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

Sample

"false" or "true"

view

The default form view mode.

The view can be changed using a method at runtime. The following views are available:

• Record view

• List view

• Record view (locked)

• List view (locked)

• Table View (locked)

NOTE: Only Table View (locked) uses asynchronized related data loading. This feature defers all related foundset data loading to the background - enhancing the visual display of a related foundset.

Type Number

Sample

"Record View"

width

The width of the form in pixels.

Type Number

Sample

640

Event Details

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

• event: JSEvent - the event that triggered the action

Returns: Boolean

Supported Clients: NGClient, Sample

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) {
	// TODO Auto-generated method stub
	//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

• oldValue: Object - old value

• newValue: Object - new value

• event: JSEvent - the event that triggered the action

Returns: Boolean

Supported Clients: SmartClient, WebClient, NGClient

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) {
	// TODO Auto-generated method stub
    	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;
	return true;
}

onElementFocusGained(event)

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

Parameters

• event: JSEvent - the event that triggered the action

Returns: Boolean

Supported Clients: SmartClient, WebClient, NGClient

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) {
	// TODO Auto-generated method stub;
	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

• event: JSEvent - the event that triggered the action

Returns: Boolean

Supported Clients: SmartClient, WebClient, NGClient

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) {
	// TODO Auto-generated method stub
	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

• event: JSEvent - the event that triggered the action

Supported Clients: SmartClient, WebClient, NGClient, MobileClient

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) {
	// TODO Auto-generated method stub
	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: 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: 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

• event: JSEvent - the event that triggered the action

Supported Clients: SmartClient, WebClient, NGClient, MobileClient

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 clicks into a column on the form. NOTE: There is a small "e" displayed in the lower left side of the Servoy Client screen in the status area at the bottom of the window when the record is being edited.

Parameters

• event: JSEvent - the event that triggered the action

Returns: Boolean

Supported Clients: SmartClient, WebClient, NGClient

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 the method returns false (for example as part of a validation), the user cannot leave the record, for example in a table view a user cannot move to another record when the callback returns false.

Parameters

• record: JSRecord - the record being saved

• event: JSEvent - the event that triggered the action

Returns: Boolean

Supported Clients: SmartClient, WebClient, NGClient

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) {
	// TODO Auto-generated method stub
	var elementName = event.getElementName();
	elements[elementName].removeStyleClass(‘grayBorder’);
	return true;
}

onRecordSelection(event)

The method that is triggered each time a record is selected. If a form is in List view or Special table view - when the user clicks on it. In Record view - after the user navigates to another record using the slider or clicks up or down for next/previous record. NOTE: Data and Servoy tag values are returned when the onRecordSelection method is executed. NOTE: this will also fire if the selection goes to -1 because the foundset is cleared. So foundset.getSelectedRecord() can return null.

Parameters

• event: JSEvent - the event that triggered the action

Supported Clients: SmartClient, WebClient, NGClient, MobileClient

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) {
	// TODO Auto-generated method stub
	scopes.globals.selected_user_name = foundset.getSelectedRecord().user_name;
}

onResize(event)

The method that gets triggered when resize occurs.

Parameters

• event: JSEvent - the event that triggered the action

Supported Clients: SmartClient, WebClient, NGClient

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) {
	// TODO Auto-generated method stub
	//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 argument must be passed to the method if this is the first time the form is displayed.

NOTE: 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: 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

• firstShow Boolean - form is shown first time after load

• event: JSEvent - the event that triggered the action

Supported Clients: SmartClient, WebClient, NGClient, MobileClient

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) {
	// TODO Auto-generated method stub
	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. Do take care 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

• event: JSEvent - the event that triggered the action

Supported Clients: SmartClient, WebClient, NGClient

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) {
	// TODO Auto-generated method stub;
	//Unloads the datasource (only do this when no form is using it anymore
    databaseManager.removeDataSource(uri);
}