Page History
...
Code Block | ||||
---|---|---|---|---|
| ||||
myFoundset: { foundsetId: 2, // an identifier that allows you to use this foundset via the 'foundsetRef' type; // when a 'foundsetRef' type sends a foundset from server to client (for example // as a return value of callServerSideApi) it will translate to this identifier // on client (so you can use it to find the actual foundset property in the model if // server side script put it in the model as well); internally when sending a // 'foundset' typed property to server through a 'foundsetRef' typed argument or prop, // it will use this foundsetId as well to find it on server and give a real Foundset serverSize: 44, // the size of the foundset on server (so not necessarily the total record count // in case of large DB tables) viewPort: { // this is the data you need to have loaded on client (just request what you need via provided // loadRecordsAsync or loadExtraRecordsAsync) startIndex: 15, size: 5, rows: [ { _svyRowId: 'someRowIdHASH1', name: "Bubu", type: 2 }, { _svyRowId: 'someRowIdHASH2', name: "Ranger", type: 1 }, { _svyRowId: 'someRowIdHASH3', name: "Yogy", type: 2 }, { _svyRowId: 'someRowIdHASH4', name: "Birdy", type: 3 }, { _svyRowId: 'someRowIdHASH5', name: "Wolfy", type: 4 } ] }, selectedRowIndexes: [16], // array of selected records in foundset; indexes can be out of current // viewPort as well sortColumns: 'orderid asc', // sort string of the foundset, the same as the one used in scripting for // foundset.sort and foundset.getCurrentSort multiSelect: false, // the multiselect mode of the server's foundset; if this is false, // selectedRowIndexes can only have one item in it hasMoreRows: false, // if the foundset is large and on server-side only part of it is loaded (so // there are records in the foundset beyond 'serverSize') this is set to true; // in this way you know you can load records even after 'serverSize' (requesting // viewport to load records at index serverSize-1 or greater will load more // records in the foundset) columnFormats: { name: (...), type: (...) }, // columnFormats is only present if you specify // "provideColumnFormats": true inside the .spec file for this foundset property; // it gives the default column formatting that Servoy would normally use for // each column of the viewport - which you can then also use in the // browser yourself /** * Request a change of viewport bounds from the server; the requested data will be loaded * asynchronously in 'viewPort' * * @param startIndex the index that you request the first record in "viewPort.rows" to have in * the real foundset (so the beginning of the viewPort). * @param size the number of records to load in viewPort. * * @return a $q promise that will get resolved when the requested records arrived browser- * side. As with any promise you can register success, error callbacks, finally, ... * See JSDoc of RequestInfoPromise.requestInfo and ChangeEvent.requestInfos * for more information about determining if a listener event was caused by this call. */ loadRecordsAsync(startIndex: number, size: number): RequestInfoPromise<any>; /** * Request more records for your viewPort; if the argument is positive more records will be * loaded at the end of the 'viewPort', when negative more records will be loaded at the beginning * of the 'viewPort' - asynchronously. * * @param negativeOrPositiveCount the number of records to extend the viewPort.rows with before or * after the currently loaded records. * @param dontNotifyYet if you set this to true, then the load request will not be sent to server * right away. So you can queue multiple loadLess/loadExtra before sending them * to server. If false/undefined it will send this (and any previously queued * request) to server. See also notifyChanged(). * * @return a $q promise that will get resolved when the requested records arrived browser- * side. As with any promise you can register success, error callbacks, finally, ... * That allows custom component to make sure that loadExtra/loadLess calls from * client do not stack on not yet updated viewports to result in wrong bounds. * See JSDoc of RequestInfoPromise.requestInfo and ChangeEvent.requestInfos * for more information about determining if a listener event was caused by this call. */ loadExtraRecordsAsync(negativeOrPositiveCount: number, dontNotifyYet: boolean): RequestInfoPromise<any>; /** * Request a shrink of the viewport; if the argument is positive the beginning of the viewport will * shrink, when it is negative then the end of the viewport will shrink - asynchronously. * * @param negativeOrPositiveCount the number of records to shrink the viewPort.rows by before or * after the currently loaded records. * @param dontNotifyYet if you set this to true, then the load request will not be sent to server * right away. So you can queue multiple loadLess/loadExtra before sending them * to server. If false/undefined it will send this (and any previously queued * request) to server. See also notifyChanged(). * * @return a $q promise that will get resolved when the requested records arrived browser * -side. As with any promise you can register success, error callbacks, finally, ... * That allows custom component to make sure that loadExtra/loadLess calls from * client do not stack on not yet updated viewports to result in wrong bounds. * See JSDoc of RequestInfoPromise.requestInfo and ChangeEvent.requestInfos * for more information about determining if a listener event was caused by this call. */ loadLessRecordsAsync(negativeOrPositiveCount: number, dontNotifyYet: boolean): RequestInfoPromise<any>; /** * If you queue multiple loadExtraRecordsAsync and loadLessRecordsAsync by using dontNotifyYet = true * then you can - in the end - send all these requests to server (if any are queued) by calling * this method. If no requests are queued, calling this method will have no effect. It returns nothing. */ notifyChanged: function(), /** * Sort the foundset by the dataproviders/columns identified by sortColumns. * * The name property of each sortColumn can be filled with the dataprovider name the foundset provides * or specifies. If the foundset is used with a component type (like in table-view) then the name is * the name of the component on who's first dataprovider property the sort should happen. If the * foundset is used with another foundset-linked property type (dataprovider/tagstring linked to * foundsets) then the name you should give in the sortColumn is that property's 'idForFoundset' value * (for example a record 'dataprovider' property linked to the foundset will be an array of values * representing the viewport, but it will also have a 'idForFoundset' prop. that can be used for * sorting in this call; this 'idForFoundset' was added in version 8.0.3). * * @param {JSONArray} sortColumns an array of JSONObjects { name : dataprovider_id, * direction : sortDirection }, where the sortDirection can be "asc" or "desc". * @return (added in Servoy 8.2.1) a $q promise that will get resolved when the new sort * will arrive browser-side. As with any promise you can register success, error * and finally callbacks. * See JSDoc of RequestInfoPromise.requestInfo and ChangeEvent.requestInfos * for more information about determining if a listener event was caused by this call. */ sort(sortColumns: Array<{ name: string, direction: ("asc" | "desc") }>): RequestInfoPromise<any>; /** * Request a selection change of the selected row indexes. Returns a promise that is resolved * when the client receives the updated selection from the server. If successful, the array * selectedRowIndexes will also be updated. If the server does not allow the selection change, * the reject function will get called with the 'old' selection as parameter. * * If requestSelectionUpdate is called a second time, before the first call is resolved, the * first call will be rejected and the caller will receive the string 'canceled' as the value * for the parameter serverRows. * E.g.: foundset.requestSelectionUpdate([2,3,4]).then(function(serverRows){},function(serverRows){}); * * @return a $q promise that will get resolved when the requested selection was updated server- * side. As with any promise you can register success, error callbacks, finally, ... * See JSDoc of RequestInfoPromise.requestInfo and ChangeEvent.requestInfos * for more information about determining if a listener event was caused by this call. */ requestSelectionUpdate(selectedRowIdxs: number[]): RequestInfoPromise<any>; /** * Sets the preferred viewPort options hint on the server for this foundset, so that the next * (initial or new) load will automatically return that many rows, even without any of the loadXYZ * methods above being called. * * You can use this when the component size is not known initially and the number of records the * component wants to load depends on that. As soon as the component knows how many it wants * initially it can call this method. * * These can also be specified initially using the .spec options "initialPreferredViewPortSize" and * "sendSelectionViewportInitially". But these can be altered at runtime via this method as well * because they are used/useful in other scenarios as well, not just initially: for example when a * related foundset changes parent record, when a search/find is performed and so on. * * @param preferredSize the preferred number or rows that the viewport should get automatically * from the server. * @param {boolean} sendViewportWithSelection if this is true, the auto-sent viewport will contain * the selected row (if any). * @param {boolean} centerViewportOnSelected if this is true, the selected row will be in the middle * of auto-sent viewport if possible. If it is false, then * the foundset property type will assume a 'paging' * strategy and will send the page that contains the * selected row (here the page size is assumed to be * preferredSize). */ setPreferredViewportSize: function(preferredSize, sendViewportWithSelection, centerViewportOnSelected), /** * It will send a data update for a cell (ros & column) in the foundset to the server. * Please make sure to adjust the viewport value as well not just call this method. * * This method is useful if you do not want to add angular watches on data (so calculated * pushToServer for the foundset property is set to just 'allow'). Then server will accept * Then server will accept* data changes from this property, but there are no automatic watches to detect the changes so the component must call * so the component must *call this method instead - when it wants to change the data in a cell. * * @param rowID the _svyRowId (so $foundsetTypeConstants.ROW_ID_COL_KEY) column of the client side row * @param columnID the name of the column to be updated on server (in that row). * @param newValue the new data in that cell * @param oldValue the old data that used to be in that cell */ updateViewportRecord(rowID: string, columnID: string, newValue: any, oldValue: any): void; /** * Add a change listener that is interested in knowing of any incoming changes (from server) * for this foundset property. See the "Adding a change listener" section below for more information. */ addChangeListener : function(listener), /** * Removes the given change listener from this foundset property. */ removeChangeListener: function(listener), /** * Receives a client side rowID (taken from myFoundsetProp.viewPort.rows[idx] * [$foundsetTypeConstants.ROW_ID_COL_KEY]) and gives a Record reference, an object * which can be resolved server side to the exact Record via the 'record' property type; * for example if you call a handler or a $scope.svyServoyapi.callServerSideApi(...) and want * to give it a Record as parameter and you have the rowID and foundset in your code, * you can use this method. E.g: $scope.svyServoyapi.callServerSideApi("doSomethingWithRecord", * [$scope.model.myFoundsetProp.getRecordRefByRowID(clickedRowId)]); * * NOTE: if in your component you know the whole row (so myFoundsetProp.viewPort.rows[idx]) * already - not just the rowID - that you want to send you can just give that directly to the * handler/serverSideApi; you do not need to use this method in that case. E.g: * // if you have the index inside the viewport * $scope.svyServoyapi.callServerSideApi("doSomethingWithRecord", * [$scope.model.myFoundsetProp.viewPort.rows[clickedRowIdx]]); * // or if you have the row directly * $scope.svyServoyapi.callServerSideApi("doSomethingWithRecord", [clickedRow]); * * This method has been added in Servoy 8.3. */ getRecordRefByRowID: function(rowId) } // where the return value for some of the client side foundset methods is: /** * Besides working like a normal IPromise that you can use to get notified when some action is done * (success/error/finally), chain etc., this promise also * contains field "requestInfo" which can be set * by the user and could later be reported in some listener events back to the user (in case this same action * *action is going to trigger those listeners as well). * * @since 2021.09 */ interface RequestInfoPromise<T> extends angular.IPromise<T> { /** * You can assign any value to it. The value that you assign - if any - will be given back in the * event object of any listener that will be triggered * as a result of the promise's action. So in * case the same action, when done, will trigger both the "then" of the Promise and a separate listener, * *listener, that separate listener will contain this "requestInfo" value. * * This is useful for some components that want to know if some change (reported by the listener) * happened due to an action that the component * requested or due to changes in the outside world. * (eg: FoundsetPropertyValue.loadRecordsAsync(...) returns RequestInfoPromise and * ChangeEvent.requestInfos array can return that RequestInfoPromise.requestInfo on the event that * was triggered by that loadRecordsAsync) */ requestInfo?: any; } |
...
Code Block | ||||
---|---|---|---|---|
| ||||
// ChangeEvent { // If this change event is caused by one or more calls (by the component) on the IFoundset obj // (like loadRecordsAsync requestSelectionUpdate and so on), // and the caller then assigned a value to // the returned RequestInfoPromise's "requestInfo" field, then that value will be present in this array. // // This is useful for some components that want to know if some change (reported in this ChangeEvent) // happened due to an action that the component // requested or due to changes in the outside world. (eg: // IFoundset.loadRecordsAsync(...) returns RequestInfoPromise and ChangeEvent.requestInfos array can // ChangeEvent.requestInfos array can// contain that RequestInfoPromise.requestInfo on the event that was triggered by that loadRecordsAsync) // // @since 2021.09 $foundsetTypeConstants.NOTIFY_REQUEST_INFOS: any[], // If a a full value update was received from server, this key is set; if newValue is non-null: // - prior to Servoy version 2021.06: newValue is a new reference, but it will automatically get // the old value's listeners registered to itself // - starting with Servoy 2021.06: the old value's reference will be reused (so the reference of // the foundset property doesn't change, just it's contents are updated) and oldValue given // below is actually a shallow-copy of the old value's properties/keys; this can help // in some component implementations $foundsetTypeConstants.NOTIFY_FULL_VALUE_CHANGED: { oldValue : ..., newValue : ... }, // the following keys appear if each of these got updated from server; the names of those // constants suggest what it was that changed; oldValue and newValue are the values for what changed // (e.g. new server size and old server size) so not the whole foundset property new/old value $foundsetTypeConstants.NOTIFY_SERVER_SIZE_CHANGED: { oldValue : ..., newValue : ... }, $foundsetTypeConstants.NOTIFY_HAS_MORE_ROWS_CHANGED: { oldValue : ..., newValue : ... }, $foundsetTypeConstants.NOTIFY_MULTI_SELECT_CHANGED: { oldValue : ..., newValue : ... }, $foundsetTypeConstants.NOTIFY_COLUMN_FORMATS_CHANGED: { oldValue : ..., newValue : ... }, $foundsetTypeConstants.NOTIFY_SORT_COLUMNS_CHANGED: { oldValue : ..., newValue : ... }, $foundsetTypeConstants.NOTIFY_SELECTED_ROW_INDEXES_CHANGED: { oldValue : ..., newValue : ... }, $foundsetTypeConstants.NOTIFY_VIEW_PORT_START_INDEX_CHANGED: { oldValue : ..., newValue : ... }, $foundsetTypeConstants.NOTIFY_VIEW_PORT_SIZE_CHANGED: { oldValue : ..., newValue : ... }, $foundsetTypeConstants.NOTIFY_VIEW_PORT_ROWS_COMPLETELY_CHANGED: { oldValue : ..., newValue : ... }, // if we received add/remove/change operations on a set of rows from the viewport, this key // will be set; as seen below, it contains "updates" which is an array that holds a sequence of // granular update operations to the viewport; the array will hold one or more granular add, remove // or update operations; // // BEFORE Servoy 8.4: all the "startIndex" and "endIndex" values below are relative to the viewport's // state after all previous updates in the array were already processed (so they are NOT relative to // the initial or final state of the viewport data!). Updates can come in a random order so there is // NO guarantee related to each change/insert/delete indexes pointing to the correct new data in the // final current viewport state // // STARTING WITH Servoy 8.4: all the "startIndex" and "endIndex" values below are relative to the // viewport's state after all previous updates in the array were already processed. But due to some // pre-processing that happens server-side (it merges and sorts these ops), the indexes of update // operations THAT POINT TO DATA (so ROWS_INSERTED and ROWS_CHANGED operations) are relative also to // the viewport's final/current state, so after ALL updates in the array were already processed // (so these indexes are correct both related to the intermediate state of the viewport data // and to the final state of viewport data). // This means that it is now easier to apply UI changes to the component as these granular updates // GUARANTEE that if you apply them in sequence (one by one) to the component's UI (delete, insert and // change included) you can safely use the indexes in there to get new data from the present state // of the viewport. // // indexes are 0 based $foundsetTypeConstants.NOTIFY_VIEW_PORT_ROW_UPDATES_RECEIVED: { // DEPRECATED in Servoy 8.4: granular updates are much easier to apply now; see comment above // Added in 8.3.2; sometimes knowing the old // viewport size helps calculate incomming granular updates easier $foundsetTypeConstants.NOTIFY_VIEW_PORT_ROW_UPDATES_OLD_VIEWPORTSIZE: ..., // starting with 8.3.2 you can use instead of 'updates' below the new constant; // $foundsetTypeConstants.NOTIFY_VIEW_PORT_ROW_UPDATES // before 8.3.2 just use 'updates'; updates : [ { type : $foundsetTypeConstants.ROWS_CHANGED, startIndex : ..., endIndex : ... }, { // NOTE: insert signifies an insert into the client viewport, not necessarily // an insert in the foundset itself; for example calling "loadExtraRecordsAsync" // can result in an insert notification + bigger viewport size notification, // with removedFromVPEnd = 0 type : $foundsetTypeConstants.ROWS_INSERTED, startIndex : ..., endIndex : ..., // DEPRECATED starting with Servoy 8.4; it would always be 0 here // as server-side code will add a separate delete operation instead - if necessary // BEFORE 8.4: when an INSERT happened but viewport size remained the same, it was // possible for some of the rows that were previously at the end of the viewport // to slide out of it; "removedFromVPEnd" gives the number of such rows that were // removed from the end of the viewport due to this insert operation; removedFromVPEnd : ... }, { // NOTE: delete signifies a delete from the client viewport, not necessarily // a delete in the foundset itself; for example calling "loadLessRecordsAsync" can // result in a delete notification + smaller viewport size notification, // with appendedToVPEnd = 0 type : $foundsetTypeConstants.ROWS_DELETED, startIndex : ..., endIndex : ..., // DEPRECATED starting with Servoy 8.4; it would always be 0 here // as server-side code will add a separate insert operation instead - if necessary // BEFORE 8.4: when a DELETE happened inside the viewport but there were more rows // available in the foundset after current viewport, it was possible for some of those // rows to slide into the viewport; "appendedToVPEnd " gives the number of such rows // that were appended to the end of the viewport due to this delete operation appendedToVPEnd : ... } ] } } |
...
Overview
Content Tools
Activity