controller

Properties Summarized

Type	Name	Summary
Boolean	enabled	Gets or sets the enabled state of a form; also known as "grayed-out".
Boolean	readOnly	Gets or sets the read-only state of a form; also known as "editable" Note: The field(s) in a form set as read-only can be selected and the field data can be copied to clipboard.
Number	view	Get/Set the current type of view of this form.

Methods Summarized

Type	Name	Summary
Boolean	find()	Set the foundset in find mode.
Boolean	focusField(fieldName, skipReadonly)	Sets focus to a field specified by its name.
Boolean	focusFirstField()	Sets focus to the first field of the form; based on tab order sequence.
Number	getDataProviderMaxLength(name)	Returns the maximum length allowed in the specified dataprovider.
Object	getDataProviderValue(dataProvider)	Gets a value based on the specified dataprovider name.
String	getDataSource()	Get the used datasource.
Boolean	getDesignMode()	Returns the state of this form designmode.
Object	getDesignProperties()	Get the design-time properties of the form.
Object	getDesignTimeProperty(key)	Get a design-time property of a form.
JSDataSet	getFormContext()	Gets the forms context where it resides, returns a dataset of its structure to the main controller.
Number	getFormWidth()	Gets the form width in pixels.
String	getName()	Get the name of this form.
Number	getPartHeight(partType)	Gets the part height in pixels.
Number	getPartYOffset(partType)	Returns the Y offset of a given part of the form.
Number	getSelectedIndex()	Gets the current record index of the current foundset.
Array	getTabSequence()	Get an array with the names of the components that are part of the tab sequence.
JSWindow	getWindow()	Returns the JSWindow that the form is shown in, or null if the form is not currently showing in a window.
Boolean	loadAllRecords()	Loads all accessible records from the datasource into the form foundset.
Boolean	loadRecords(foundset)	Loads a (related) foundset into the form.
Boolean	loadRecords(foundset)	Loads a (related) foundset into the form.
Boolean	recreateUI()	Recreates the forms UI components, to reflect the latest solution model.
Number	search()	Start the database search and use the results, returns the number of records, make sure you did "find" function first.
Number	search(clearLastResults)	Start the database search and use the results, returns the number of records, make sure you did "find" function first.
Number	search(clearLastResults, reduceSearch)	Start the database search and use the results, returns the number of records, make sure you did "find" function first.
void	setDataProviderValue(dataprovider, value)	Sets the value based on a specified dataprovider name.
void	setDesignMode(designMode)	Sets this form in designmode with param true, false will return to normal browse/edit mode.
void	setDesignMode(ondrag)	Sets this form in designmode with one or more callback methods.
void	setDesignMode(ondrag, ondrop)	Sets this form in designmode with one or more callback methods.
void	setDesignMode(ondrag, ondrop, onselect)	Sets this form in designmode with one or more callback methods.
void	setDesignMode(ondrag, ondrop, onselect, onresize)	Sets this form in designmode with one or more callback methods.
void	setDesignMode(ondrag, ondrop, onselect, onresize, ondblclick)	Sets this form in designmode with one or more callback methods.
void	setDesignMode(ondrag, ondrop, onselect, onresize, ondblclick, onrightclick)	Sets this form in designmode with one or more callback methods.
void	setSelectedIndex(index)	Sets the current record index of the current foundset.
void	setTabSequence(arrayOfElements)	Set the tab order sequence programatically, by passing the elements references in a javascript array.
void	show()	Shows the form (makes the form visible) This function does not affect the form foundset in any way.
void	show(window)	Shows the form (makes the form visible) This function does not affect the form foundset in any way.
void	show(window)	Shows the form (makes the form visible) This function does not affect the form foundset in any way.
void	showRecords(foundset)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(foundset, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(foundset, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(pkdataset)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(pkdataset, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(pkdataset, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(UUIDpk)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(UUIDpk, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(UUIDpk, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(singleNumber_pk)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(singleNumber_pk, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(singleNumber_pk, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query, argumentsArray)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query, argumentsArray, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query, argumentsArray, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.
void	showRecords(query, window)	Load data into the form and shows the form, is a shortcut for the functions 'loadRecords' and 'show'.

Properties Detailed

enabled

Gets or sets the enabled state of a form; also known as "grayed-out". Notes:

• A disabled element(s) cannot be selected by clicking the form.

• The disabled "grayed" color is dependent on the LAF set in the Servoy Smart Client Application Preferences.

Type Boolean

Sample

//gets the enabled state of the form
var state = controller.enabled;
//enables the form for input
controller.enabled = true;

readOnly

Gets or sets the read-only state of a form; also known as "editable"

Note: The field(s) in a form set as read-only can be selected and the field data can be copied to clipboard.

Type Boolean

Sample

//gets the read-only state of the form
var state = controller.readOnly;
//sets the read-only state of the form
controller.readOnly = true

view

Get/Set the current type of view of this form. Can be one of the JSForm.xxxx_VIEW constants. In NGClient only RECORD_VIEW is fully supported, the List and TableViews should be replaced by components.

Type Number

Sample

//gets the type of view for this form
var view = controller.view;
//sets the form to Record view
controller.view = JSForm.RECORD_VIEW;
//sets the form to List view
controller.view = JSForm.LIST_VIEW;

Methods Detailed

find()

Set the foundset in find mode. (Start a find request), use the "search" function to perform/exit the find.

Before going into find mode, all unsaved records will be saved in the database.
If this fails (due to validation failures or sql errors) or is not allowed (autosave off), the foundset will not go into find mode.
Make sure the operator and the data (value) are part of the string passed to dataprovider (included inside a pair of quotation marks).
Note: always make sure to check the result of the find() method.

When in find mode, columns can be assigned string expressions (including operators) that are evaluated as:
General:
      c1||c2    (condition1 or condition2)
      c|format  (apply format on condition like 'x|dd-MM-yyyy')
      !c        (not condition)
      #c        (modify condition, depends on column type)
      ^         (is null)
      ^=        (is null or empty)
      <x        (less than value x)
      >x        (greater than value x)
      <=x       (less than or equals value x)
      >=x       (greater than or equals value x)
      x...y     (between values x and y, including values)
      x         (equals value x)

 Number fields:
      =x       (equals value x)
      ^=       (is null or zero)

 Date fields:
      #c       (equals value x, entire day)
      now      (equals now, date and or time)
      //       (equals today)
      today    (equals today)

 Text fields:
      #c      (case insensitive condition)
      = x     (equals a space and 'x')
      ^=      (is null or empty)
      %x%     (contains 'x')
      %x_y%   (contains 'x' followed by any char and 'y')
      \%      (contains char '%')
      \_      (contains char '_')

Related columns can be assigned, they will result in related searches.
For example, "employees_to_department.location_id = headoffice" finds all employees in the specified location).

Searching on related aggregates is supported.
For example, "orders_to_details.total_amount = '>1000'" finds all orders with total order details amount more than 1000.

Arrays can be used for searching a number of values, this will result in an 'IN' condition that will be used in the search.
The values are not restricted to strings but can be any type that matches the column type.
For example, "record.department_id = [1, 33, 99]"

Multiple Find Records for Logical OR:
It's important to note that when in Find Mode, a foundset will initially contain one record object.
However, multiple record objects may be used to articulate search criteria.
This has the effect that the criteria described in each record are concatenated by a SQL OR.

Returns: Boolean true if the foundset is now in find mode, false otherwise.

Sample

if (foundset.find()) //find will fail if autosave is disabled and there are unsaved records
{
	columnTextDataProvider = 'a search value'
	// for numbers you have to make sure to format it correctly so that the decimal point is in your locales notation (. or ,)
	columnNumberDataProvider = '>' + utils.numberFormat(anumber, '####.00');
	columnDateDataProvider = '31-12-2010|dd-MM-yyyy'
	foundset.search()
}

// Multiple Find Records for Logical OR - example
// Find customers in the city of Berlin AND in the postal code 12209...
// OR customers in the city of San Francisco AND in the postal code 94117
if (foundset.find()) // Enter find mode    city = 'Berlin';
{
	city = 'Berlin';   // Assign a search criteria
	postalcode = '12209';
	foundset.newRecord();   // Create a new search record
	city = 'San Francisco';
 postalcode = '94117';
	foundset.search();      // Execute the query and load the records
}

focusField(fieldName, skipReadonly)

Sets focus to a field specified by its name. If the second parameter is set to true, then readonly fields will be skipped (the focus will be set to the first non-readonly field located after the field with the specified name; the tab sequence is respected when searching for the non-readonly field).

Parameters

• String fieldName the name of the field to be focussed

• Boolean skipReadonly indication to skip read only fields, if the named field happens to be read only

Returns: Boolean true if component was found and can be focused

Sample

var tabseq = controller.getTabSequence();
if (tabseq.length > 1) {
	// If there is more than one field in the tab sequence,
	// focus the second one and skip over readonly fields.
	controller.focusField(tabseq[1], true);
}
else {
	// If there is at most one field in the tab sequence, then focus
	// whatever field is first, and don't bother to skip over readonly fields.
	controller.focusField(null, false);
}

focusFirstField()

Sets focus to the first field of the form; based on tab order sequence.

Returns: Boolean true if component was found and can be focused

Sample

controller.focusFirstField();

getDataProviderMaxLength(name)

Returns the maximum length allowed in the specified dataprovider.

Parameters

• String name the dataprovider name

Returns: Number the length

Sample

controller.getDataProviderMaxLength('name');

getDataProviderValue(dataProvider)

Gets a value based on the specified dataprovider name.

Parameters

• String dataProvider the dataprovider name to retieve the value for

Returns: Object the dataprovider value (null if unknown dataprovider)

Sample

var val = controller.getDataProviderValue('contact_name');

getDataSource()

Get the used datasource.

Returns: String the datasource

Sample

var dataSource = controller.getDataSource();

getDesignMode()

Returns the state of this form designmode.

Returns: Boolean the design mode state (true/fase)

Sample

var success = controller.getDesignMode();

getDesignProperties()

Get the design-time properties of the form.

Returns: Object

Sample

var prop = fforms.orders.controller.getDesignProperties()

getDesignTimeProperty(key)

Get a design-time property of a form.

Parameters

• String key the property name

Returns: Object

Sample

var prop = forms.orders.controller.getDesignTimeProperty('myprop')

getFormContext()

Gets the forms context where it resides, returns a dataset of its structure to the main controller. Note1: can't be called in onload, because no context is yet available at this time. Note2: tabindex is 1 (left) or 2 (right) for a SplitPane and 0 based for the other tabpanels; tabindex1based is the same as tabindex but is 1 based.

Returns: JSDataSet the dataset with form context

Sample

//dataset columns: [containername(1),formname(2),tabpanel or beanname(3),tabname(4),tabindex(5),tabindex1based(6)]
//dataset rows: mainform(1) -> parent(2)  -> current form(3) (when 3 forms deep)
/** @type {JSDataSet} */
var dataset = controller.getFormContext();
if (dataset.getMaxRowIndex() > 1)
{
	// form is in a tabpanel
	var parentFormName = dataset.getValue(1,2)
}

getFormWidth()

Gets the form width in pixels.

Returns: Number the width in pixels

Sample

var width = controller.getFormWidth();

getName()

Get the name of this form.

Returns: String the name

Sample

var formName = controller.getName();

getPartHeight(partType)

Gets the part height in pixels.

Parameters

• Number partType The type of the part whose height will be returned.

Returns: Number the part height in pixels

Sample

var height = controller.getPartHeight(JSPart.BODY);

getPartYOffset(partType)

Returns the Y offset of a given part of the form.

Parameters

• Number partType The type of the part whose Y offset will be returned.

Returns: Number A number holding the Y offset of the specified form part.

Sample

var offset = controller.getPartYOffset(JSPart.BODY);

getSelectedIndex()

Gets the current record index of the current foundset.

Returns: Number the index

Sample

//gets the current record index in the current foundset
var current = controller.getSelectedIndex();
//sets the next record in the foundset, will be reflected in UI
controller.setSelectedIndex(current+1);

getTabSequence()

Get an array with the names of the components that are part of the tab sequence. The order of the names respects the order of the tab sequence. Components that are not named will not appear in the returned array, although they may be in the tab sequence.

Returns: Array array of names

Sample

var tabseq = controller.getTabSequence();
if (tabseq.length > 1) {
	// If there is more than one field in the tab sequence,
	// focus the second one and skip over readonly fields.
	controller.focusField(tabseq[1], true);
}
else {
	// If there is at most one field in the tab sequence, then focus
	// whatever field is first, and don't bother to skip over readonly fields.
	controller.focusField(null, false);
}

getWindow()

Returns the JSWindow that the form is shown in, or null if the form is not currently showing in a window.

Returns: JSWindow the JSWindow that the form is shown in, or null if the form is not currently showing in a window.

Sample

var currentWindow = controller.getWindow();
if (currentWindow != null) {
	currentWindow.title = 'We have a new title';
} else {
	currentWindow = application.createWindow("Window Name", JSWindow.DIALOG, null);
	currentWindow(650, 700, 450, 350);
	currentWindow = "Window Title";
	controller.show(currentWindow);
}

loadAllRecords()

Loads all accessible records from the datasource into the form foundset. When the form contains a related foundset it will be replaced by a default foundset on same datasource. Or when this form is not configured to have a seperate foundset it will also be related with the default shared foundset.

So this is different then foundset.loadAllRecords() because that will just load all the records based on its filters of that foundset instance. This controller.loadAllRecords() can result in a replacement of the current loaded foundset instance.

Notes: -the default foundset is always limited by filters, if databaseManager.addFoundSetFilterParam function is used. -typical use is loading the normal foundset again after form usage in a related tabpanel

Returns: Boolean true if successful

Sample

controller.loadAllRecords