JSFoundSet
Property Summary
Type | Name | Summary |
---|---|---|
Get all dataproviders of the foundset.. | ||
Get or set the multiSelect flag of the foundset.. |
Methods Summary
Type | Name | Summary |
---|---|---|
Add a filter parameter that is permanent per user session to limit a specified foundset of records.. | ||
Add a filter parameter that is permanent per user session to limit a specified foundset of records.. | ||
Add a filter parameter that is permanent per user session to limit a specified foundset of records.. | ||
Add a filter parameter that is permanent per user session to limit a specified foundset of records.. | ||
void | Clear the foundset.. | |
Create a new record on top of the foundset and change selection to it.. | ||
Create a new record in the foundset.. | ||
Create a new record in the foundset.. | ||
Create a new record in the foundset and change selection to it at specified index.. | ||
Create a new record in the foundset.. | ||
Delete all records in foundset, resulting in empty foundset.. | ||
Delete currently selected record(s).. | ||
Delete record from foundset.. | ||
Delete record with the given index.. | ||
Dispose a foundset from memory when foundset is no longer needed.. | ||
Get a duplicate of the foundset.. | ||
Duplicate current record, change selection to new record, place on top.. | ||
Duplicate selected record, change selection to new record.. | ||
Duplicate selected record.. | ||
Duplicate record at index in the foundset, change selection to new record, place on top.. | ||
Duplicate record at index in the foundset, change selection to new record.. | ||
Duplicate record at index in the foundset.. | ||
Duplicate record at index in the foundset, change selection to new record.. | ||
Duplicate record at index in the foundset.. | ||
Set the foundset in find mode.. | ||
Iterates over the records of a foundset taking into account inserts and deletes that may happen at the same time.. | ||
Iterates over the records of a foundset taking into account inserts and deletes that may happen at the same time.. | ||
Get the current sort columns.. | ||
Get a value based on a dataprovider name.. | ||
Get the datasource used.. | ||
Get the list of previously defined foundset filters.. | ||
Get a previously defined foundset filter, using its given name.. | ||
Get foundset name.. | ||
Returns a JSDataSet with the PKs omitted on this foundset If no PKs have been omitted, an empty JSDataSet will be returned. | ||
Gets the parent records when called on a related foundset.. | ||
Get the query that the foundset is currently using (as a clone; modifying this QBSelect will not automatically change the foundset).. | ||
Get the query that the foundset is currently using (as a clone; modifying this QBSelect will not automatically change the foundset).. | ||
Get the record object at the given index.. | ||
Get the loaded record based on its the primary key values This will only return a record that is already loaded in this foundset, this will not try to load anything from the database.. | ||
Get the record index.. | ||
Gets the relation name (null if not a related foundset).. | ||
Returns the internal SQL of the JSFoundset.. | ||
Returns the internal SQL of the JSFoundset.. | ||
Returns the parameters for the internal SQL of the QBSelect.. | ||
Returns the parameters for the internal SQL of the QBSelect.. | ||
Get the current record index of the foundset.. | ||
Get the indexes of the selected records.. | ||
Get the selected record.. | ||
Get the selected records.. | ||
Get the number of records in this foundset.. | ||
Check wether the foundset has any conditions from a previous find action.. | ||
void | Invert the foundset against all rows of the current table.. | |
Returns a boolean if this foundset is in a cleared state (has the clear condition that is added by a clear() call). | ||
Check if the foundset was disposed.. | ||
Check if this foundset is in find mode.. | ||
Loads all accessible records from the datasource into the foundset.. | ||
Loads the records that are currently omitted as a foundset.. | ||
Reloads all last (related) records again, if, for example, after search in tabpanel.. | ||
Copies foundset data from another foundset.. | ||
Loads a primary key dataset, will remove related sort.. | ||
Loads records into form foundset based on a query builder object (also known as 'Form by query').. | ||
Loads a single record by primary key, will remove related sort.. | ||
Loads a single record by primary key, will remove related sort.. | ||
Loads records into form foundset based on a query (also known as 'Form by query').. | ||
Loads records into form foundset based on a query (also known as 'Form by query').. | ||
Create a new record on top of the foundset and change selection to it.. | ||
Create a new record in the foundset and change selection to it.. | ||
Create a new record in the foundset.. | ||
Create a new record in the foundset and change selection to it.. | ||
Create a new record in the foundset.. | ||
Omit selected record(s) (add it to omit records list), to be shown with loadOmittedRecords.. | ||
Omit record under the given index (add it to omit records list), to be shown with loadOmittedRecords.. | ||
void | Reloads all last records again with the filters applied.. | |
void | Perform a relookup for the currently selected records Lookups are defined in the dataprovider (columns) auto-enter setting and are normally performed over a relation upon record creation.. | |
void | Perform a relookup for the record under the given index Lookups are defined in the dataprovider (columns) auto-enter setting and are normally performed over a relation upon record creation.. | |
Remove a named foundset filter.. | ||
Start the database search and use the results, returns the number of records, make sure you did "find" function first.. | ||
Start the database search and use the results, returns the number of records, make sure you did "find" function first.. | ||
Start the database search and use the results, returns the number of records, make sure you did "find" function first.. | ||
Select the record based on pk data.. | ||
void | Set a value based on a dataprovider name.. | |
void | Set the current record index.. | |
void | Set the selected records indexes.. | |
void | Sorts the foundset based on the given sort string.. | |
void | Sorts the foundset based on the given sort string.. | |
void | Sorts the foundset based on the given record comparator function.. | |
Create a new unrelated foundset that is a copy of the current foundset.. |
Properties Details
alldataproviders
Get all dataproviders of the foundset.
Returns Array
Sample
multiSelect
Get or set the multiSelect flag of the foundset.
Returns Boolean
Sample
Methods Details
addFoundSetFilterParam(query)
Add a filter parameter that is permanent per user session to limit a specified foundset of records.
Filters on tables touched in the query will not be applied to the query filter. For example, when a table filter exists on the order_details table, a query filter with a join from orders to order_details will be applied to the foundset, but the filter condition on the orders_details table will not be included.
Use clear(), reloadWithFilters(), loadRecords() or loadAllRecords() to make the filter effective. Multiple filters can be added to the same dataprovider, they will all be applied.
Parameters QBSelect query condition to filter on.
Returns Boolean true if adding the filter succeeded, false otherwise.
Sample
addFoundSetFilterParam(query, name)
Add a filter parameter that is permanent per user session to limit a specified foundset of records.
Filters on tables touched in the query will not be applied to the query filter. For example, when a table filter exists on the order_details table, a query filter with a join from orders to order_details will be applied to the foundset, but the filter condition on the orders_details table will not be included.
Use clear(), reloadWithFilters(), loadRecords() or loadAllRecords() to make the filter effective. The filter is removed again using removeFoundSetFilterParam(name).
The table of the query has to be the same as the foundset table.
Parameters QBSelect query condition to filter on. Object name String name, used to remove the filter again.
Returns Boolean true if adding the filter succeeded, false otherwise.
Sample
addFoundSetFilterParam(dataprovider, operator, value)
Add a filter parameter that is permanent per user session to limit a specified foundset of records. Use clear(), reloadWithFilters(), loadRecords() or loadAllRecords() to make the filter effective. Multiple filters can be added to the same dataprovider, they will all be applied.
Parameters String dataprovider String column to filter on. String operator String operator: =, <, >, >=, <=, !=, (NOT) LIKE, (NOT) IN, (NOT) BETWEEN and IS (NOT) NULL optionally augmented with modifiers "#" (ignore case) or "^||" (or-is-null), prefix with "sql:" to allow the value to be interpreted as a custom query. Object value Object filter value (for in array and between an array with 2 elements)
Returns Boolean true if adding the filter succeeded, false otherwise.
Sample
addFoundSetFilterParam(dataprovider, operator, value, name)
Add a filter parameter that is permanent per user session to limit a specified foundset of records. Use clear(), reloadWithFilters(), loadRecords() or loadAllRecords() to make the filter effective. The filter is removed again using removeFoundSetFilterParam(name).
Parameters String dataprovider String column to filter on. String operator String operator: =, <, >, >=, <=, !=, (NOT) LIKE, (NOT) IN, (NOT) BETWEEN and IS (NOT) NULL optionally augmented with modifiers "#" (ignore case) or "^||" (or-is-null), prefix with "sql:" to allow the value to be interpreted as a custom query. Object value Object filter value (for in array and between an array with 2 elements) String name String name, used to remove the filter again.
Returns Boolean true if adding the filter succeeded, false otherwise.
Sample
clear()
Clear the foundset.
This will set a special condition in the query that makes the query not return any results.
But if new Records are added to this foundset, then those records become the query pk set. So it will then behave the same as loadRecord(pkset) of a pkset of those new records.
You can query for this state in the isCleared() call so you can call loadRecords() to remove that cleared state if needed.
Returns void
Sample
createRecord()
Create a new record on top of the foundset and change selection to it. Returns the new record or null if record was not created.
Returns JSRecord IJSRecord the new record
Sample
createRecord(onTop)
Create a new record in the foundset. Returns the new record or null if the record can't be made.
Parameters Boolean onTop when true the new record is added as the topmost record.
Returns JSRecord IJSRecord of new record.
Sample
createRecord(onTop, changeSelection)
Create a new record in the foundset. Returns the new record or null if the record can't be made.
Parameters Boolean onTop when true the new record is added as the topmost record; when false the record is added to the end, if all records are loaded, otherwise it will be added to the top Boolean changeSelection when true the selection is changed to the new record.
Returns JSRecord IJSRecord of new record.
Sample
createRecord(index)
Create a new record in the foundset and change selection to it at specified index. Returns the new record or null if the record can't be made.
Parameters Number index the new record is added at specified index (1-based).
Returns JSRecord IJSRecord of new record.
Sample
createRecord(index, changeSelection)
Create a new record in the foundset. Returns the new record or null if the record can't be made.
Parameters Number index the new record is added at specified index (1-based). Boolean changeSelection when true the selection is changed to the new record.
Returns JSRecord IJSRecord of new record.
Sample
deleteAllRecords()
Delete all records in foundset, resulting in empty foundset.
Returns Boolean boolean true if all records could be deleted.
Sample
deleteRecord()
Delete currently selected record(s). If the foundset is in multiselect mode, all selected records are deleted.
Returns Boolean boolean true if all records could be deleted.
Sample
deleteRecord(record)
Delete record from foundset.
Parameters JSRecord record The record to delete from the foundset.
Returns Boolean boolean true if record could be deleted.
Sample
deleteRecord(index)
Delete record with the given index.
Parameters Number index The index of the record to delete.
Returns Boolean boolean true if record could be deleted.
Sample
dispose()
Dispose a foundset from memory when foundset is no longer needed. Should be used to destroy separate foundsets (is an optimization for memory management). A related foundset or a foundset which is linked to visible forms/components cannot be disposed. Returns whether foundset was disposed or not.
Returns Boolean boolean foundset was disposed
Sample
duplicateFoundSet()
Get a duplicate of the foundset. This is a full copy of the foundset (cached pks,records, relation, filters, search criteria, omitted records, selection).
Returns JSFoundSet foundset duplicate.
Sample
duplicateRecord()
Duplicate current record, change selection to new record, place on top.
Returns Number 0 if record was not created or the record index if it was created.
Sample
duplicateRecord(onTop)
Duplicate selected record, change selection to new record.
Parameters Boolean onTop when true the new record is added as the topmost record.
Returns Number 0 if record was not created or the record index if it was created.
Sample
duplicateRecord(onTop, changeSelection)
Duplicate selected record.
Parameters Boolean onTop when true the new record is added as the topmost record. Boolean changeSelection when true the selection is changed to the duplicated record.
Returns Number 0 if record was not created or the record index if it was created.
Sample
duplicateRecord(index)
Duplicate record at index in the foundset, change selection to new record, place on top.
Parameters Number index The index of the record to duplicate; defaults to currently selected index. Ignored if first given parameter is a boolean value.
Returns Number 0 if record was not created or the record index if it was created.
Sample
duplicateRecord(index, onTop)
Duplicate record at index in the foundset, change selection to new record.
Parameters Number index The index of the record to duplicate; defaults to currently selected index. Ignored if first given parameter is a boolean value. Boolean onTop when true the new record is added as the topmost record.
Returns Number 0 if record was not created or the record index if it was created.
Sample
duplicateRecord(index, onTop, changeSelection)
Duplicate record at index in the foundset.
Parameters Number index The index of the record to duplicate; defaults to currently selected index. Ignored if first given parameter is a boolean value. Boolean onTop when true the new record is added as the topmost record. Boolean changeSelection when true the selection is changed to the duplicated record.
Returns Number 0 if record was not created or the record index if it was created.
Sample
duplicateRecord(index, location)
Duplicate record at index in the foundset, change selection to new record.
Parameters Number index The index of the record to duplicate; defaults to currently selected index. Ignored if first given parameter is a boolean value. Number location the new record is added at specified index
Returns Number 0 if record was not created or the record index if it was created.
Sample
duplicateRecord(index, location, changeSelection)
Duplicate record at index in the foundset.
Parameters Number index The index of the record to duplicate; defaults to currently selected index. Ignored if first given parameter is a boolean value. Number location the new record is added at specified index Boolean changeSelection when true the selection is changed to the duplicated record.
Returns Number 0 if record was not created or the record index if it was created.
Sample
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
forEach(callback)
Iterates over the records of a foundset taking into account inserts and deletes that may happen at the same time. It will dynamically load all records in the foundset (using Servoy lazy loading mechanism). If callback function returns a non null value the traversal will be stopped and that value is returned. If no value is returned all records of the foundset will be traversed. Foundset modifications( like sort, omit...) cannot be performed in the callback function. If foundset is modified an exception will be thrown. This exception will also happen if a refresh happens because of a rollback call for records on this datasource when iterating. When an exception is thrown from the callback function, the iteration over the foundset will be stopped.
Parameters Function callback The callback function to be called for each loaded record in the foundset. Can receive three parameters: the record to be processed, the index of the record in the foundset, and the foundset that is traversed.
Returns Object Object the return value of the callback
Sample
forEach(callback, thisObject)
Iterates over the records of a foundset taking into account inserts and deletes that may happen at the same time. It will dynamically load all records in the foundset (using Servoy lazy loading mechanism). If callback function returns a non null value the traversal will be stopped and that value is returned. If no value is returned all records of the foundset will be traversed. Foundset modifications( like sort, omit...) cannot be performed in the callback function. If foundset is modified an exception will be thrown. This exception will also happen if a refresh happens because of a rollback call for records on this datasource when iterating. When an exception is thrown from the callback function, the iteration over the foundset will be stopped.
Parameters Function callback The callback function to be called for each loaded record in the foundset. Can receive three parameters: the record to be processed, the index of the record in the foundset, and the foundset that is traversed. Object thisObject What the this object should be in the callback function (default it is the foundset)
Returns Object Object the return value of the callback
Sample
getCurrentSort()
Get the current sort columns.
Returns String String sort columns
Sample
getDataProviderValue(dataProviderID)
Get a value based on a dataprovider name.
Parameters String dataProviderID data provider name
Returns Object Object value
Sample
getDataSource()
Get the datasource used. The datasource is an url that describes the data source.
Returns String String data source.
Sample
getFoundSetFilterParams()
Get the list of previously defined foundset filters.
For column-based table filters, a row of 5 fields per filter are returned. The "columns" of a row from this array are: tablename, dataprovider, operator, value, filtername
For query-based filters, a row of 2 fields per filter are returned. The "columns" of a row from this array are: query, filtername
Returns Array Array of filter definitions.
Sample
getFoundSetFilterParams(filterName)
Get a previously defined foundset filter, using its given name. The result is an array of: [ tableName, dataprovider, operator, value, name ]
Parameters String filterName name of the filter to retrieve.
Returns Array Array of filter definitions.
Sample
getName()
Get foundset name. If foundset is not named foundset or related foundset will return null.
Returns String name.
Sample
getOmittedPKs()
Returns a JSDataSet with the PKs omitted on this foundset If no PKs have been omitted, an empty JSDataSet will be returned
Returns JSDataSet a JSDataSet
Sample
getParentRecords()
Gets the parent records when called on a related foundset. (empty array if not a related foundset) Depending on the cardinality of the relation, this method returns either 1 or more records. This can be useful when creating a new record in an empty related foundset and some data from the parent record(s) is needed.
Be aware that if datasources.xxx.getFoundset() is called multiple times on the same datasource it creates multiple foundset instances then the related foundset can have multiple references to the same parent record but in different foundsets. (different instances of the record for the same row in the database) In that case, this method will return the record from the first foundset.
Returns Array an array of records
Sample
getQuery()
Get the query that the foundset is currently using (as a clone; modifying this QBSelect will not automatically change the foundset). When the foundset is in find mode, the find conditions are included in the resulting query. So the query that would be used when just calling search() (or search(true,true)) is returned. Note that foundset filters are optionally included and table filters are not included in the query.
Returns QBSelect query.
Sample
getQuery(includeFilters)
Get the query that the foundset is currently using (as a clone; modifying this QBSelect will not automatically change the foundset). When the foundset is in find mode, the find conditions are included in the resulting query. So the query that would be used when just calling search() (or search(true,true)) is returned. Note that foundset filters are optionally included and table filters are not included in the query.
Parameters Boolean includeFilters include the foundset filters, default true.
Returns QBSelect query.
Sample
getRecord(index)
Get the record object at the given index. Argument "index" is 1 based (so first record is 1).
Parameters Number index record index (1 based).
Returns JSRecord Record record.
Sample
getRecordByPk(pk)
Get the loaded record based on its the primary key values
This will only return a record that is already loaded in this foundset, this will not try to load anything from the database.
Parameters Array pk pk values as array
Returns JSRecord Record record.
Sample
getRecordIndex(record)
Get the record index. Will return -1 if the record can't be found.
Parameters JSRecord record Record
Returns Number int index.
Sample
getRelationName()
Gets the relation name (null if not a related foundset).
Returns String String relation name when related.
Sample
getSQL()
Returns the internal SQL of the JSFoundset. Optionally, the foundset and table filter params can be excluded in the sql (includeFilters=false).
Returns String String representing the sql of the JSFoundset.
Sample
getSQL(includeFilters)
Returns the internal SQL of the JSFoundset. Optionally, the foundset and table filter params can be excluded in the sql (includeFilters=false).
Parameters Boolean includeFilters include the foundset and table filters [default true].
Returns String String representing the sql of the JSFoundset.
Sample
getSQLParameters()
Returns the parameters for the internal SQL of the QBSelect. Table filters are on by default.
Returns Array An Array with the sql parameter values.
Sample
getSQLParameters(includeFilters)
Returns the parameters for the internal SQL of the QBSelect. Table filters are on by default.
Parameters Boolean includeFilters include the foundset and table filters [default true].
Returns Array An Array with the sql parameter values.
Sample
getSelectedIndex()
Get the current record index of the foundset.
Returns Number int current index (1-based)
Sample
getSelectedIndexes()
Get the indexes of the selected records. When the founset is in multiSelect mode (see property multiSelect), a selection can consist of more than one index.
Returns Array Array current indexes (1-based)
Sample
getSelectedRecord()
Get the selected record.
Returns JSRecord Record record.
Sample
getSelectedRecords()
Get the selected records. When the founset is in multiSelect mode (see property multiSelect), selection can be a more than 1 record.
Returns Array Array current records.
Sample
getSize()
Get the number of records in this foundset. This is the number of records loaded, note that when looping over a foundset, size() may increase as more records are loaded.
Returns Number int current size.
Sample
hasConditions()
Check wether the foundset has any conditions from a previous find action.
Returns Boolean wether the foundset has find-conditions
Sample
invertRecords()
Invert the foundset against all rows of the current table. All records that are not in the foundset will become the current foundset.
Returns void
Sample
isCleared()
Returns a boolean if this foundset is in a cleared state (has the clear condition that is added by a clear() call)
Returns Boolean boolean true if this foundset is cleared
Sample
isDisposed()
Check if the foundset was disposed.
When the foundset.dispose() method was called successfully, a foundset can no longer be used.
Returns Boolean
Sample
isInFind()
Check if this foundset is in find mode.
Returns Boolean boolean is in find mode.
Sample
loadAllRecords()
Loads all accessible records from the datasource into the foundset. Filters on the foundset are applied.
Before loading the records, 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), records will not be loaded,
Returns Boolean true if records are loaded, false otherwise.
Sample
loadOmittedRecords()
Loads the records that are currently omitted as a foundset.
Before loading the omitted records, 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), omitted records will not be loaded,
Returns Boolean true if records are loaded, false otherwise.
Sample
loadRecords()
Reloads all last (related) records again, if, for example, after search in tabpanel. When in find mode, this will reload the records from before the find() call.
Returns Boolean true if successful
Sample
loadRecords(foundset)
Copies foundset data from another foundset. This will alter the foundset state to the state of the foundset that is given. If you really just want to use the given foundset on the form itself, then you need to use controller.loadRecords(foundset) that will change the instance of the foundset that is used for this form. Not just update an existing forms foundset.
If you copy over a relation into this foundset, then this foundset will not be a related foundset, it will not automatically update its state of records are updated or added that belong to that relation. It will only be a snapshot of that related foundsets state.
Foundset filter params are copied over from the original/source foundset and are merged with the existing filters on this foundset. So if the original foundset had filters and the given foundset has filters then the resulting foundset will have all the filters of both, If you don't want this and you really want only the state of the given foundset, use controller.loadRecords(fs) instead of foundset.loadRecords(fs)
Parameters JSFoundSet foundset The foundset to load records from
Returns Boolean true if successful
Sample
loadRecords(dataset)
Loads a primary key dataset, will remove related sort. Tries to preserve selection based on primary key, otherwise first record is selected.
Parameters JSDataSet dataset pkdataset
Returns Boolean true if successful
Sample
loadRecords(querybuilder)
Loads records into form foundset based on a query builder object (also known as 'Form by query'). When the foundset is in find mode, the find states are discarded, the foundset will go out of find mode and the foundset will be loaded using the query. If the foundset is related, the relation-condition will be added to the query. Tries to preserve selection based on primary key, otherwise first record is selected.
The query of the QBSelect that is given is added as a "search" condition to the existing base query of the foundset. This does mean that loadAllRecords() will revert this, because that will clear the search condition and go back to the base query of the foundset. Some hold true for clear() that will remove the search condition and because of that the given query will also be removed.
If you want to create more a "view" on your database that will always be kept by this foundset, so loadAllRecords() (with our withou first calliing clear()) will always revert back to this set of data (and you can also search inside this data with find/search or adding another query on top of it. Then have a look at datasources.db.server.table.getFoundset(query) because that will generate a foundset with the given query as the base query.
Parameters QBSelect querybuilder the query builder
Returns Boolean true if successful
Sample
loadRecords(uuidpk)
Loads a single record by primary key, will remove related sort.
NOTE: This function will return true if the foundset was altered/changed. It is up to the developer to check for the presence of actual data using getSize().
Parameters UUID uuidpk single-column pk value
Returns Boolean true if successful
Sample
loadRecords(numberpk)
Loads a single record by primary key, will remove related sort.
NOTE: This function will return true if the foundset was altered/changed. It is up to the developer to check for the presence of actual data using getSize().
Parameters Number numberpk single-column pk value
Returns Boolean true if successful
Sample
loadRecords(queryString)
Loads records into form foundset based on a query (also known as 'Form by query'). The query must be a valid sql select. If the foundset is related this function is not allowed. Tries to preserve selection based on primary key, otherwise first record is selected.
see foundset.loadRecords(QBSelect).
When possible, the foundset will be loaded with the given query. This is not always possible because the foundset needs to manipulate the query when adding conditions and joins. In that case the query will be wrapped: select pk from tab where pk = (queryString) The result is the same, except for the ordering in the queryString which will be ignored.
The query will be wrapped when one of the following is true:
you have no order-by clause
you have no from keyword
your query is not fully qualified on the main table
you have a group-by, having, join or union keyword
Parameters String queryString select statement
Returns Boolean true if successful
Sample
loadRecords(queryString, argumentsArray)
Loads records into form foundset based on a query (also known as 'Form by query'). The query must be a valid sql select. If the foundset is related this function is not allowed. Tries to preserve selection based on primary key, otherwise first record is selected.
see foundset.loadRecords(QBSelect).
When possible, the foundset will be loaded with the given query. This is not always possible because the foundset needs to manipulate the query when adding conditions and joins. In that case the query will be wrapped: select pk from tab where pk = (queryString) The result is the same, except for the ordering in the queryString which will be ignored.
The query will be wrapped when one of the following is true:
you have no order-by clause
you have no from keyword
your query is not fully qualified on the main table
you have a group-by, having, join or union keyword
Parameters String queryString select statement Array argumentsArray arguments to query
Returns Boolean true if successful
Sample
newRecord()
Create a new record on top of the foundset and change selection to it. Returns -1 if the record can't be made.
Returns Number int index of new record.
Sample
newRecord(onTop)
Create a new record in the foundset and change selection to it. Returns -1 if the record can't be made.
Parameters Boolean onTop when true the new record is added as the topmost record.
Returns Number int index of new record.
Sample
newRecord(onTop, changeSelection)
Create a new record in the foundset. Returns -1 if the record can't be made.
Parameters Boolean onTop when true the new record is added as the topmost record; when false the record is added to the end, if all records are loaded, otherwise it will be added to the top Boolean changeSelection when true the selection is changed to the new record.
Returns Number int index of new record.
Sample
newRecord(index)
Create a new record in the foundset and change selection to it. Returns -1 if the record can't be made.
Parameters Number index the new record is added at specified index.
Returns Number int index of new record.
Sample
newRecord(index, changeSelection)
Create a new record in the foundset. Returns -1 if the record can't be made.
Parameters Number index the new record is added at specified index. Boolean changeSelection when true the selection is changed to the new record.
Returns Number int index of new record.
Sample
omitRecord()
Omit selected record(s) (add it to omit records list), to be shown with loadOmittedRecords. T his operation returns false only when foundset is in bad state (table not accessible or not having a valid selected record) or the record is in an edit state and can't be saved (autosave is false).
Note: The omitted records list is discarded when these functions are executed: loadAllRecords, loadRecords(dataset), loadRecords(sqlstring), invertRecords()
Returns Boolean boolean true if all selected record(s) could be omitted.
Sample
omitRecord(index)
Omit record under the given index (add it to omit records list), to be shown with loadOmittedRecords. If index is null it behaves just like omitRecord(). This operation returns false when index is invalid (should be between 1 and foundset size) or foundset is in bad state (its table not accessible) or the record is in an edit state and can't be saved (autosave is false). Any retrievable record can be ommitted.
Note: The omitted records list is discarded when these functions are executed: loadAllRecords, loadRecords(dataset), loadRecords(sqlstring), invertRecords()
Parameters Number index The index of the record to omit, starting with 1 .
Returns Boolean boolean true if all records could be omitted.
Sample
reloadWithFilters()
Reloads all last records again with the filters applied.
Returns void
Sample
relookup()
Perform a relookup for the currently selected records Lookups are defined in the dataprovider (columns) auto-enter setting and are normally performed over a relation upon record creation.
Returns void
Sample
relookup(index)
Perform a relookup for the record under the given index Lookups are defined in the dataprovider (columns) auto-enter setting and are normally performed over a relation upon record creation.
Parameters Number index record index (1-based)
Returns void
Sample
removeFoundSetFilterParam(name)
Remove a named foundset filter. Use clear(), reloadWithFilters(), loadRecords() or loadAllRecords() to make the filter effective.
Parameters String name String filter name.
Returns Boolean true if removing the filter succeeded, false otherwise.
Sample
search()
Start the database search and use the results, returns the number of records, make sure you did "find" function first. Clear results from previous searches.
Note: Omitted records are automatically excluded when performing a search - meaning that the foundset result by default will not include omitted records.
Returns Number the recordCount
Sample
search(clearLastResults)
Start the database search and use the results, returns the number of records, make sure you did "find" function first. Reduce results from previous searches.
Note: Omitted records are automatically excluded when performing a search - meaning that the foundset result by default will not include omitted records.
Parameters Boolean clearLastResults boolean, clear previous search, default true
Returns Number the recordCount
Sample
search(clearLastResults, reduceSearch)
Start the database search and use the results, returns the number of records, make sure you did "find" function first.
Note: Omitted records are automatically excluded when performing a search - meaning that the foundset result by default will not include omitted records.
Parameters Boolean clearLastResults boolean, clear previous search, default true Boolean reduceSearch boolean, reduce (true) or extend (false) previous search results, default true
Returns Number the recordCount
Sample
selectRecord(pkid1, pkid2, pkidn)
Select the record based on pk data. Note that if the foundset has not loaded the record with the pk, selectrecord will fail.
In case of a table with a composite key, the pk sequence must match the alphabetical ordering of the pk column names.
Parameters Object pkid1 primary key Object pkid2 second primary key (in case of composite primary key) Object pkidn nth primary key
Returns Boolean true if succeeded.
Sample
setDataProviderValue(dataProviderID, value)
Set a value based on a dataprovider name.
Parameters String dataProviderID data provider name Object value value to set
Returns void
Sample
setSelectedIndex(index)
Set the current record index.
Parameters Number index index to set (1-based)
Returns void
Sample
setSelectedIndexes(indexes)
Set the selected records indexes.
Parameters Array indexes An array with indexes to set.
Returns void
Sample
sort(sortString)
Sorts the foundset based on the given sort string. Tries to preserve selection based on primary key. If first record is selected or cannot select old record it will select first record after sort. TIP: You can use the Copy button in the developer Select Sorting Fields dialog to get the needed syntax string for the desired sort fields/order.
Parameters String sortString the specified columns (and sort order)
Returns void
Sample
sort(sortString, defer)
Sorts the foundset based on the given sort string. Tries to preserve selection based on primary key. If first record is selected or cannot select old record it will select first record after sort. TIP: You can use the Copy button in the developer Select Sorting Fields dialog to get the needed syntax string for the desired sort fields/order.
Parameters String sortString the specified columns (and sort order) Boolean defer when true, the "sortString" will be just stored, without performing a query on the database (the actual sorting will be deferred until the next data loading action).
Returns void
Sample
sort(recordComparisonFunction)
Sorts the foundset based on the given record comparator function. Tries to preserve selection based on primary key. If first record is selected or cannot select old record it will select first record after sort. The comparator function is called to compare two records, that are passed as arguments, and it will return -1/0/1 if the first record is less/equal/greater then the second record.
The function based sorting does not work with printing. It is just a temporary in-memory sort.
NOTE: starting with 7.2 release this function doesn't save the data anymore
Parameters Function recordComparisonFunction record comparator function
Returns void
Sample
unrelate()
Create a new unrelated foundset that is a copy of the current foundset. If the current foundset is not related, no copy will made.
Returns JSFoundSet FoundSet unrelated foundset.
Sample
Last updated