Foundset property type

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
     * data changes from this property, but there are no automatic watches to detect the changes
     * 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 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, 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;

}

var l = function(changes) {
    // check to see what actually changed and update what is needed in browser
};
$scope.model.myFoundset.addChangeListener(l);

// 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
    // 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 : ... },

    // (ADDED in Servoy 2022.03)
    // This key is in the change event if the foundset spec property is configured "foundsetDefinitionListener": true, 
    // see "Defining initial load options for a foundset property" on this page. for more info
    $foundsetTypeConstants.NOTIFY_FOUNDSET_DEFINITION_CHANGE:  boolean,

    // 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 : ...
            }
        ]
    }

}

"myFoundset": { "type": "foundset", "dynamicDataproviders": true }

myFoundset: {
    (...)
    viewPort: {
        startIndex: 15,
        size: 2,
        rows: [ { _svyRowId: 'someRowIdHASH1', dp0: (...), dp1: (...), dp2: (...) },
                { _svyRowId: 'someRowIdHASH2', dp0: (...), dp1: (...), dp2: (...) } ],
        (...)
    },
    (...)
}

"myFoundset": { "type": "foundset", "dataproviders": ["firstName", "lastName"] }

myFoundset: {
    (...)
    viewPort: {
        startIndex: 15,
        size: 2,
        rows: [ { _svyRowId: 'someRowIdHASH1', firstName: (...), lastName: (...) },
                { _svyRowId: 'someRowIdHASH2', firstName: (...), lastName: (...) } ],
        (...)
    },
    (...)
}

"myFoundset": { "type": "foundset", "dataproviders": ["image", "age"], "provideColumnFormats": true }

myFoundset: {
    (...)
    viewPort: {
        startIndex: 15,
        size: 2,
        rows: [ { _svyRowId: 'someRowIdHASH1', image: (...), age: (...) },
                { _svyRowId: 'someRowIdHASH2', image: (...), age: (...) } ],
        (...)
    },
    columnFormats: {
        image: {
            placeHolder: null,
            maxLength: 2147483647,
            isNumberValidator: false,
            edit: null,
            isMask: false,
            display: null,
            type: "MEDIA",
            allowedCharacters: null
        },

        age: {
            placeHolder: null,
            percent: "%",
            isNumberValidator: false,
            edit: null,
            isMask: false,
            display: "#,#00.###",
            type: "NUMBER",
            allowedCharacters: null
        }
    }
}

"myFoundset": { "type": "foundset", "dataproviders": ["image", "age"],
                                    "initialPreferredViewPortSize": 130,
                                    "sendSelectionViewportInitially": true,
									"foundsetDefinitionListener": true
 }

"myFoundset": "foundset",
"childElement" : { "type" : "component", "forFoundset": "myFoundset" }

"myFoundset": "foundset",
"childElements" : { "type" : "component[]", "elementConfig" : {"forFoundset": "myFoundset"} }

"myFoundset": "foundset",
"myconfiguration": "MyConfig", // or:
"myconfigurations": "MyConfig[]"
(...)
"types": {
    "MyConfig": { 
        "mydataprovider" : { "type" : "dataprovider", "forFoundset": "myFoundset"}
        "mytagstring" : { "type" : "tagstring", "forFoundset": "myFoundset"}
    }
}

elements.myFoundsetBasedBean.myFoundset

// elements.myFoundsetBasedBean.myFoundset.foundset gives access to the
// underlying Servoy foundset used by this property
application.output(elements.myFoundsetBasedBean.myFoundset.foundset.getSelectedIndex())
elements.myFoundsetBasedBean.myFoundset.foundset.loadRecords(someQBSelect)

// elements.myFoundsetBasedBean.myFoundset.dataproviders gives access to the
// configured dataproviders of the Servoy foundset property; probably most useful
// in combination with dynamicDataproviders: "true"
elements.myFoundsetBasedBean.myFoundset.dataproviders = {
	dp1: "userNickname",
	dp2: "userReviewRating",
	dp3: "numberOfPurchasedItems"
}
if (!elements.myFoundsetBasedBean.myFoundset.dataproviders.rating)
	elements.myFoundsetBasedBean.myFoundset.dataproviders.rating = "userReviewRating";

// elements.myFoundsetBasedBean.myFoundset is the foundset typed property
var myNewFoundset = ...; // some Servoy foundset
elements.myFoundsetBasedBean.myFoundset = {
            foundset: myNewFoundset,
            dataproviders: {
                dp1 : "customerName",
                dp2 : "city"
            },
            sendSelectionViewportInitially: false,
            initialPreferredViewPortSize: 15
};

// elements.myFoundsetBasedBean.myFoundset is the foundset typed property
var myNewFoundset = ...; // some Servoy foundset
elements.myFoundsetBasedBean.myFoundset = myNewFoundset; // this will create a new foundset type property value
// that only sends the rowId (no other columns as dataproviders were not specified) and uses defaults for sendSelectionViewportInitially and initialPreferredViewPortSize

function getChildFoundSet(rowObjFromFoundsetsViewport, parentLevelGroupColumnIndex,
                                                  newLevelGroupColumnIndex) {
    // 'rowObjFromFoundsetsViewport' comes from the foundset (that contributed the expanded row)
    //     property type's viewport so equivalent to something like
    //     $scope.model.foundsetProps[i].viewPort.rows[expandedRowIndex]
    // 'parentLevelGroupColumnIndex' and 'newLevelGroupColumnIndex' are indexes in
    //     an array property that holds the grouping column dataproviders
    // if 'newLevelGroupColumnIndex' is undefined, then we are requesting tree leafs (not groups)
    //     and then the server-side query is a bit different

    // foundset query needed for leaf level: Select pk from orders where Country = ? and City = ? and ...
    // foundset query needed for intermediate grouped level; ie. when you want to expand a country group
    //     to next level that is grouped by city: SELECT DISTINCT MIN(pk) FROM Customers Where Country = 
    //     "Mexico" GROUP BY City;
                    
    // as you can see below I try to send abstract things to the server (the client shouldn't really know
    // real datasource names, real column/dataprovider names and so on (those can be determined on server)
    // so both client and server code should be done so that these kinds of information never reach the
    // client in the first place - only as abstract ids or indexes/names of component properties)
                    
    // so server needs to be given the expanded row (it can get the foundset of the Record from that) and
    // the groupColumn (index of the column) of the child level if that one is an grouped intermediate level
    // otherwise, if it is going to request leafs it should set undefined for "newLevelGroupColumnIndex"

    // NOTE: if we could get it nicely from the parent foundset's query there would be no use sending the
    // expanded node's group column because that is already available on the server from that foundset's
    // query (group by clause)

    var childFoundsetPromise;

    if (newLevelGroupColumnIndex) {
        childFoundsetPromise = $scope.svyServoyapi.callServerSideApi("getGroupedChildFoundsetId",
                      [rowObjFromFoundsetsViewport, parentLevelGroupColumnIndex, newLevelGroupColumnIndex]);
    } else {
        childFoundsetPromise = $scope.svyServoyapi.callServerSideApi("getLeafChildFoundsetId",
                      [rowObjFromFoundsetsViewport, parentLevelGroupColumnIndex]);
	}

    childFoundsetPromise.then(function(childFoundsetId) {
        var childFoundset = getFoundSetByFoundsetId(childFoundsetId);
        mergeData(..., childFoundset);
    }, function() {
        // some error happened
        (...)
    });
}
(...)
function getFoundSetByFoundsetId(foundsetId) {
    if ($scope.model.childFoundsets)
        for (var i = 0; i < $scope.model.childFoundsets.length; i++) {
            if ($scope.model.childFoundsets[i].foundsetId == foundsetId)
                return $scope.model.childFoundsets[i];
		 
    return null;
}

$scope.getGroupedChildFoundsetId = function(parentRecord, parentLevelGroupColumnIndex,
                                            newLevelGroupColumnIndex) {

        var parentFoundset = parentRecord.foundset;
        var childQuery = parentFoundset.getQuery();
		
        if (parentLevelGroupColumnIndex == undefined) {
            // this is the first grouping operation; alter initial query to get all first level groups
            (...)
            return;
        } else {
			// this is an intemediate group expand; alter query of parent level for the child level
			childQuery.groupBy.clear();
            childQuery.groupBy.add(childQuery
                      .columns[$scope.model.columns[newLevelGroupColumnIndex].dataprovider]);
            var parentGroupColumnName = $scope.model.columns[parentLevelGroupColumnIndex].dataprovider;
            childQuery.where.add(childQuery.columns[parentGroupColumnName]
                      .eq(parentRecord[parentGroupColumnName]));
        }
		
        var childFoundset = parentFoundset.duplicateFoundSet();
		childFoundset.loadRecords(childQuery);
		
		var dps = {};
		for (var idx = 0; idx < $scope.model.columns.length; idx++) {
			dps["dp" + idx] = $scope.model.columns[idx].dataprovider;
		}
		
		$scope.model.childFoundsets.push({
			foundset: childFoundset,
			dataproviders: dps,
			sendSelectionViewportInitially: false,
			initialPreferredViewPortSize: 15
		}); // send it to client as a foundset property in the array of foundsets
		
		return childFoundset; // return the foudnsetId that points to this foundset (return type
                              // 'foundsetRed' will make a foundsetID from the childFoundset)
	};

	"serverscript": "mycomppck/mycompname/mycomp_server.js",
(...)
	"model": 
	{
        "columns": { "type": "columnDef[]", "droppable": true },
        "childFoundsets": { "type": "foundset[]", "default": [] }
(...)
	"types": 
	{
        "columnDef": {
            "dataprovider": { "type": "dataprovider", "forFoundset": "myFoundset" }
            (...)
        }
	},
	"internalApi" : {
		"getGroupedChildFoundsetId" : {
			"returns" : "foundsetRef",
			"parameters" : 
			[ { "name" : "parentRecord", "type" : "record" },
              { "name": "parentLevelGroupColumnIndex", "type": "int" },
              { "name": "newLevelGroupColumnIndex", "type": "int" } ]
		},
(...)

/**
 * NOTE: Starting with Servoy 8.4 you no longer need to use this method; see @deprecated
 * comment.
 * 
 * The purpose of this method is to aggregate after-the-fact granular updates with indexes
 * that are relevant only when applying updates 1-by-1 into indexes that are
 * related to the new/final state of the viewport. It only calculates new indexes
 * for updates of type $foundsetTypeConstants.ROWS_CHANGED. (taking into account
 * any insert/delete along the way)
 * 
 * @param viewportRowUpdates what a foundset/component property type (viewport) change listener
 * would receive in changeEvent[$foundsetTypeConstants.NOTIFY_VIEW_PORT_ROW_UPDATES_RECEIVED]
 * [$foundsetTypeConstants.NOTIFY_VIEW_PORT_ROW_UPDATES]
 * 
 * @param oldViewportSize what a foundset/component property type (viewport) change listener
 * would receive in changeEvent[$foundsetTypeConstants.NOTIFY_VIEW_PORT_ROW_UPDATES_RECEIVED]
 * [$foundsetTypeConstants.NOTIFY_VIEW_PORT_ROW_UPDATES_OLD_VIEWPORTSIZE]
 * 
 * @deprecated starting with 8.4 this is no longer needed as foundset/component/foundsetlinked
 * property change listeners guarantee that the rows in inserts and updates have their indexes
 * relative to the already changed viewport (data in the viewport at those indexes at the
 * moment these listeners trigger does match correctly). So basically calling this method would
 * not alter any update operations - they would remain the same.
 * 
 * @returns an array of $foundsetTypeConstants.ROWS_CHANGED updates with their indexes corrected
 * to reflect the indexes in the final state of the viewport (after all updates were applied).
 */
coalesceGranularRowChanges: function(viewportRowUpdates, oldViewportSize);