...
Note |
---|
For all programming reference information, see the JSFoundSet API documention in the reference guide. |
...
A Servoy Form is typically bound to a single database table and the form will always contain a single Foundset object which is bound to the same table. Much of the action in the user interface, such as a user editing data fields, directly affects the form's foundset. Conversely, actions taken on the foundset, such as programmatically editing data, is immediately reflected in the form.
...
Note |
---|
See also the namedFoundset property of a form. |
One of the primary jobs of a Foundset is to load records from the table to which it is bound. A Foundset object is always based on an underlying SQL query, which may change often during the lifetime of the Foundset. However the query will always take the form of selecting the Primary Key column(s) from the table and will also also always include an Order By clause, which in its simplest form will sort the results based on the Primary Key column(s).
Code Block | |||||||
---|---|---|---|---|---|---|---|
| |||||||
SELECT customerid FROM customers ORDER BY customerid ASC |
After retrieving the results for Primary Key data, the Foundset will issue subsequent SQL queries to load the matching record data in smaller, optimized blocks. This query happens automatically in an on-demand fashion to satisfy the Foundset's scrollable interface.
Code Block | borderStyle | solid|||||
---|---|---|---|---|---|---|
| ||||||
SELECT * FROM customers WHERE customerid IN (?,?,?,?,?,?,?,?) ORDER BY customerid ASC |
...
Code Block |
---|
// Foundset size grows dynamically as the Foundset is traversed foundset.getSize(); // returns 200 foundset.setSelectedIndex(200); foundset.getSize(); // returns 400 because the foundset loaded the next 200 record pks |
...
Often, as part of some programming operation, it is necessary to iterate over part or all of a foundset. There are several approaches to iterating, each having their appropriate usage. In general, a Javascript for or while statement is used to control the flow of execution.
...
Perhaps the most intuitive approach is to programmatically change the foundset's selected index property.
...
See also the JSFoundset's setSelectedIndex method.
...
While setting the selected index of the foundset is sometimes necessary, it also contains some overhead and therefore is not always the most efficient way to iterate over a foundset. However, one can iterate in a similar manner, access a record object without changing the selected index of a foundset by using the getRecord method of the foundset.
...
See also the JSFoundset's getRecord method.
...
Sometimes the purpose of iterating over a foundset is to access all of the values for a particular data provider. The most efficient way to do this is to obtain an array of values for the foundset's data provider using the getFoundSetDataProviderAsArray method of the databaseManager API.
...
Gliffy Diagram | ||
---|---|---|
|
...
A Foundset may be automatically updated when the client receives a Data Broadcast Event . If the data change affected the table to which the foundset is bound, the foundset will be refreshed to reflect the change.
...
The Foundset Updater API is ideal to use for the following situations:
...
This essentially has the effect of issuing a SQL UPDATE statement using the WHERE clause that constrains the foundset. This presents a significant performance advantage over updating records individually. In the example below, a related foundset is updated, meaning all orders belonging to the selected customer will be affected.
Code Block |
---|
var fsUpdater = databaseManager.getFoundSetUpdater(customers_to_orders); fsUpdater.setColumn('status',101); fsUpdater.performUpdate(); |
...
The Foundset Updater API can also be used to update part of a foundset. Moreover, unlike the above example, this approach allows for different values for each record. In the example below, the first 4 records (starting from the selected index) are updated by specifying an array of values for each column that is affected.
...
Note |
---|
When using this approach, it matters what the selected index of the foundset is. The update will start with this record. |
...
The Foundset Updater API can also be used to update records individually, but still holds a performance advantage over iterating on a foundset, which has more overhead and can cause the foundset's cache size to increase unnecessarily. In the example below, each record in the foundset is updated with a unique value (A simple counter is incremented, which is arbitrary, but demonstrates that each record can be updated with a unique value.)
...