Interface: model

// The widget can create the model during widget initialization
this.model = apex.model.create( modelName, options, initialData, ... );

// Or it can be configured with the name of a model that already exists and get a reference to it
this.model = apex.model.get( modelName );

// In either case subscribe to model notifications
this.modelViewId = this.model.subscribe( {
    onChange: modelNotificationFunction,
} );

// During create or when the widget is refreshed it should render data from the model
// this.pageOffset starts at 0. When the user changes pages or additional page data is needed run this code again
// the model fetches more data from the server as needed.
var count = 0;
this.model.forEachInPage( this.pageOffset, pageSize, function( record, index, id ) {
    if ( record ) {
        // render the row record
        count += 1;
    }
    if ( count === pageSize || !record ) {
        // done rendering this page of records
    }
} );

// When settings change that affect the data such as changing the sort order or applying a filter
// the new sort order or filter information can be communicated to the server in the model fetchData or
// regionData option or it can be sent in a separate Ajax request.
this.model.clearData();

// Clearing the data will result in a refresh notification. The modelNotificationFunction should
this.pageOffset = 0;
// call the above forEachInPage code to fetch and render the new data.

// When the widget is destroyed it needs to release the model
this.model.unSubscribe( this.modelViewId );
this.model.release( modelName );

Sent when data has been added to the model from the server.

Sent when the model has been saved (or model#clearChanges called) after all metadata related to changes has been cleared.

Sent when one or more records are copied.

Sent when one or more records are deleted.

Sent when a record is inserted into the model.

Sent when metadata has changed. The record field values have not changed but the record or field metadata has changed. Typically this is the result of validation errors. If external code changes the metadata it must call model#metadataChanged (which sends this notification) to let other views know about the change.

Sent when one or more records are moved.

Sent when the model has been given new data or there is a change in data on the server that the model should now go get. In either case the previous data in the model is gone/changed so any views showing the model data should re-render their views.

Sent when specific records in the model have changed. This happens when the model is saved if the server returns updated records or when model#fetchRecords is called. Both the record field values and metadata may have changed. The view layer should render the new record including taking into consideration any metadata and replace the existing view of the record.

Sent when record changes are reverted.

Sent when a field value of a record is changed.

Rarely needed. Only useful if making your own call to the server. See model#save, apex.model.addChangesToSaveRequest, and apex.model.save.

Determine if any record or one or more specific records can be added to the table collection or, for trees, the parent record's children collection.

For any record or one or more specific records to be addable:

• the shape must not be record and
• if the shape is a tree the parent record is required and must have a children collection
• the model must have the editable option set to true and
• if the shape is tree the type of the parent record must allow add or
• if the shape is table or the parent record has no type or doesn't specify if it allows add the default type must allow add
• and if the model specifies an additional check callback function it must allow or deny the add
• then, for tree shape only, if adding is allowed and pRecordsToAdd is given then check if the type of each record to add is a valid child type for the parent using validChildren type property.

if ( myModel.allowAdd() ) {
    myModel.insertNewRecord();
}

Determine if the given record can be deleted.

For a record to be deletable:

• the shape must not be record and
• if the shape is a tree the record must not be the root record
• the model must have the editable option set to true and
• the type of the record must allow delete or
• if the record has no type or doesn't specify if it can be deleted the default type must allow delete
• and if the model specifies an additional check callback function it must allow or deny the delete

if ( myModel.allowDelete( record ) ) {
    myModel.deleteRecords( [record] );
}

Determine if an record can be dragged. Note this is just a check to see if the dragging can start. What is allowed on drop (move, copy etc.) is a separate check.

For a record to be draggable:

• the shape must not be record and
• the model must have the editable option set to true and
• the type of the record must allow drag or
• if the record has no type or doesn't specify if it can be dragged the default type must allow drag
• and if the model specifies an additional check callback function it must allow or deny the drag

Determine if the given record can be edited.

For a record to be editable:

• the model must have the editable option set to true and
• the type of the record must allow edit or
• if the record has no type or doesn't specify if it can be edited the default type must allow edit
• and if the model specifies an additional check callback function it must allow or deny the edit

if ( myModel.allowEdit( record ) ) {
    myModel.setValue( record, "NAME", newName );
}

Return true if the record exists in the model and has a change that can be reverted (is updated or is deleted). See also model#revertRecords.

if ( myModel.canRevertRecord( record ) ) {
    myModel.revertRecords( [record] );
}

Low level operation permission checking. Better to use model#allowEdit, model#allowDelete, model#allowAdd, model#allowDrag. The purpose is to determine what kinds of edits are allowed.

If the model is not editable (editable option is false) then no operations are allowed. Also no operations are allowed on deleted records or aggregate records.

Operation checking is based on the type of the record (as determined by the type field) and the type information given to the model in the types option. Type names are strings. The special type name "default" is used to provide a default when records don't have a type or the type of the record doesn't specify a value for the operation. Note: The model types option is not currently documented and may change in the future.

Operations are strings. The standard operation permissions are "canAdd", "canDelete", "canEdit", "canDrag". You can define your own as well.

First the record itself is checked to see if it allows the operation by checking if the record metadata contains the specified permission. Next the type of the record is checked to see if it allows the operation. If the record has no type or the operations for that type didn't specify a value for the operation then the default type is checked to see if it allows the operation. The value of an operation is true or false or a function that returns true or false. The function is called in the context of this model with arguments pRecord, pAddAction, pRecordsToAdd. If the model options includes a check function then it is called with the result so far and all the same arguments as this check function. See model.CheckCallback.

Return the child at pIndex of node pNode.

This method must only be used on tree shape models.

var i, node;
for ( i = 0; i < model.childCount( parentNode ); i++ ) {
    node = mode.child( parentNode, i );
    // do something with node
}

Returns the number of children that node pNode has, or null if the answer is not yet known. A node that has its children lazy loaded may not know how many children it has until they are loaded.

This method must only be used on tree shape models.

var i, node;
for ( i = 0; i < model.childCount( parentNode ); i++ ) {
    node = mode.child( parentNode, i );
    // do something with node
}

This marks the model as not having any changes. All change indications will be removed. If any record deletes are pending they will be removed by this method. This does not revert or undo the changes but rather removes all metadata that is tracking changes. This happens implicitly after the model is saved (See model#save). Use this method if changes are persisted in some other way or the changes should be discarded before refreshing the model.

var ig$ = apex.region( "emp" ).widget(),
    view = ig$.interactiveGrid( "getCurrentView" );
if ( view.supports.edit ) {
    // leave edit mode so that the column items will be reinitialized
    ig$.interactiveGrid( "getActions" ).set( "edit", false );
    view.model.clearChanges();
}
apex.region("emp").refresh();

Remove all data from the model.

myModel.clearData();

Unselect all the selected records. See also model#setSelectionState.

This method should only be used by view widgets to persist the view selection state in metadata property sel. Note there is no notification about this metadata change. Listen to the view for selection change events. Also use the view to change the selection.

Copies the given records and inserts the copies into the collection (table or parent node's children) or, for tree shape only, to a new parent node.

var keys = model.copyRecords( selectedRecords, null, selectedRecords[ selectedRecords.length - 1 ] );

Delete one or more records from a table or tree.

If the onlyMarkForDelete option is true the records are just marked for delete. Records marked for delete will be included in data returned by model#forEach, model#forEachInPage, model#walkTree, etc. and can be found by model#getRecord. They will be deleted once the model#clearChanges method is called explicitly or implicitly after data has been saved successfully.

If the onlyMarkForDelete option is false the records are deleted right away and are no longer part of the model. In either case the deleted records are on the change list so the delete can be persisted.

If pRecords contains records that cannot be found in the collection or finds records that can't be deleted they are ignored and a debug warning is given.

if ( myModel.allowDelete( record ) ) {
    myModel.deleteRecords( [record] );
}

Determine what drag operations are allowed for a set of records. Not all views support dragging. Dragging is a view operation. The model provides this method simply to allow type based configuration of available drag operations. Note: The model types option is not currently documented and may change in the future.

Retrieve model data from the server. Data is requested starting at the given offset (or 0 if offset is not given). Data is fetched in model option pageSize chunks. Can use either the callback argument or the returned promise to determine when the request is complete.

Fetch all the data from the server into the model. This repeatedly calls model#fetch until the server reports there is no more data. This is only for table shape models. Data is fetched in model option pageSize chunks.

Use with caution. Loading too much data onto the client can take a long time and cause the browser to become unresponsive.

model.fetchAll( function( status ) {
    if ( status.done } {
        model.forEach( function( record, index, id ) {
            // do something with each record
        }
    }
} );

Fetch child nodes for node pNode. This method is only used for trees that lazy load data from the sever as needed. If pNode is not given or null the whole tree is loaded from the server.

This is an asynchronous operation. When it completes the pCallback function is called with a status argument. Where status is:

• > 0 (or true) if 1 or more children were fetched.
• 0 if the node has 0 children.
• Error if there was an error fetching the children.

Can use either the callback argument or the returned promise to determine when the request is complete.

Fetches fresh data from the server for the given records. The existing records in the model are replaced with the new returned record from the server. The model must have a identityField option defined for this to work. Can use either the callback argument or the returned promise to determine when the request is complete.

var model = apex.region( "emp" ).call( "getCurrentView" );
model.fetchRecords( apex.region( "emp" ).call( "getSelectedRecords" );

Iterate over the model collection. Calls pCallback for each record in the model. Similar to Array.prototype.forEach. The model shape must be table or tree. This will never fetch new data. This includes aggregate records if any. For shape tree see also model#walkTree.

The callback receives the record, the zero based index of the record, and the identity (recordId) of the record.

var total = 0;
model.forEach( function( record, index, id ) {
    var salary = parseFloat( model.getValue( record, "SALARY" ) ),
        meta = model.getRecordMetadata( id );

    if ( !isNaN( salary ) && !meta.deleted && !meta.agg ) {
        total += salary;
    }
} );
// do something with total

Iterate over a range (page) of the model collection. This is only valid for table shape models. Calls pCallback for pCount records in the collection starting at pOffset. If the model doesn't yet contain the requested records they will be fetched from the server by calling model#fetch. If the collection has fewer records than requested or if there is an error fetching data from the server then pCallback is called with a null record.

The callback receives the record, the zero based index of the record, and the identity (recordId) of the record.

var count = 0,
    pageOffset = currentPageOffset;
model.forEachInPage( pageOffset, pageSize, function( record, index, id ) {
    if ( record ) {
        // render the record
        count += 1;
    }
    if ( count === pageSize || !record ) {
        // done rendering this page of records
    }
} );

Return an array of record metadata for all changed records. Do not make any changes to the data structure returned. See also model#isChanged.

if ( model.isChanged() ) {
    console.log("Model has " + model.getChanges().length + " changes.");
}

Return an array of record metadata for all records with errors. Do not make any changes to the data structure returned.

Return the index/key to use for the given field name when accessing that field of a record. Use the value returned from this method to access a record field without using model#getValue. This will work regardless of if the records are stored as objects or arrays.

var i, cost,
    costKey = model.getFieldKey("COST");
for ( i = 0; i < selectedRecords.length; i++ ) {
    cost = selectedRecords[i][costKey];
    // do something with cost
}

Return metadata object for given field name. The field metadata is supplied when the model is created in option property fields.

Get the value of the given model option. The model options are provided in the call to apex.model.create. See also model#setOption.

var markForDelete = model.getOption( "onlyMarkForDelete" );

var hasTotalRecords = model.getOption( "hasTotalRecords" );

Return the record for a given record id. This only considers records that are currently fetched into the model. The server may have a record with the given record id but if it hasn't yet been fetched into the model, it will not be found with this method.

For table or tree shape models that define an identityField option, call with the value of the record's identity field or if the records have multiple identity fields call with an array of ids or a string representation of the combined identity fields as returned by model#getRecordId.

For table shape models that don't define an identityField option call with the index of the record. This is the same as model#recordAt.

For record shape models call with no record id to get the one and only model record.

record = model.getRecord( "001002" );

record = model.getRecord( ["AXB9", "00003"] );

record = model.getRecord();

Given a record return the unique identifier (id) for the record. The id is used in calls to model#getRecordMetadata and model#getRecord. If the model has multiple identity fields this returns a string representation of the combined fields.

var id = model.getRecordId( someRecord ),
    meta = model.getRecordMetadata( id );
// use meta for something

Return the metadata object for the record given by the record id. This only applies to models that define an identity field with option identityField.

Upper layers can store information related to the record here. The metadata should be related to the record itself and not the view of it.

var id = model.getRecordId( someRecord ),
    meta = model.getRecordMetadata( id );
if ( meta.updated ) {
    // do something related to the updated record
}

Get the value of a record field given the record id. This is only useful when the model shape is table or tree. If there are many field values to get or set use model#getRecord followed by model#getValue or model#setValue. See also model#setRecordValue.

var name = model.getRecordValue( "00013", "NAME" );

Return the number of currently selected records. This only applies if a view is storing selection state in the model. See also model#setSelectionState.

This is used by views that store view selection state in the model to return the selection count.

Return an array of the selected records. This only applies if a view is storing selection state in the model. See also model#setSelectionState.

This is used by views that store view selection state in the model to return the selection.

Returns the total number of records from the server's perspective or -1 if unknown.

For table shape models the server provides the total but for editable grids the number of inserted records is added and the number of deleted records subtracted. This is so the number reflects what is likely to be on the server after changes are saved.

For tree shape models this is not supported; returns -1.

For record shape models the number is always 1.

Note: Aggregate records are never included.

Returns the total number of records in the model collection or -1 if unknown.

For table shape models the total number of records may not be known or it may be an estimate. If the pagination type is "none" then the total records is known and it is the same as what is in the collection. If the pagination type is "progressive" and the model has paged to the end (all pages have been received and the server has said there is no more) then the total records is known and it is the same as what is in the collection (which could be different from what is actually on the server). If the server has told the model how many records it has then that is returned. This is an estimate of what the client model may eventually hold. This value may change as new pages are fetched. If the server has not told the model how many records it has then the total is unknown.

For tree shape models the total number of records is not often needed. It is also not readily available so the nodes must be counted. The total doesn't include nodes that have not yet been fetched and never returns -1 (unknown) even if there are nodes that haven't been fetched.

For record shape the number is always 1.

Note: Includes records that are marked for delete in the count. Also includes aggregate records if any in the count.

Get the value of a record field given the record itself or omit the record when the model shape is record. See also model#setValue.

var name = model.getValue( someRecord, "NAME" );

var name = model.getValue( "NAME" );

Returns true if the node pNode has children, false if it does not, and null if not yet known. A node that has its children lazy loaded may not know if it has any children until they are loaded.

if ( model.hasChildren( node ) === true ) {
    console.log("node is a leaf");
}

Return true if the model has any errors.

if ( model.hasErrors() ) {
    console.log("Model has errors.");
}

Return the index of the record within the collection. The collection may include aggregate records. Useful because model#forEachInPage method takes a starting index/offset.

Only applies to table and tree shape models. Throws an error if the model shape is record. For tree shape models returns the index of the node among its siblings.

Inserts a new record into the collection. Only applies to tree and table shape models. For tree shape models the record is inserted under the given parent node. The model must allow adding new records. See model#allowAdd.

Determine if the model has been changed in any way. See also model#getChanges.

Note: Auto inserted records don't count as changes unless they are also updated but they are returned by model#getChanges.

if ( model.isChanged() ) {
    console.log("Model has changes.");
}

Return true if the record is disabled and false otherwise. The record disabled state is determined by the record model.RecordMetadata disabled property. If the disabled property is not defined or is null return a default of false.

Return true if the given field name is an identity field and false otherwise.

Call this method if any properties of the metadata returned by model#getRecordMetadata are changed external to this module. Most record or field metadata should not be changed externally. However it may be useful and reasonable to externally change metadata that comes from the records initially such as canEdit or custom metadata properties. The result of calling this method is sending a model#event:metaChange notification.

Return the model id for this model.

Moves the given records to a new position in the collection (table or parentRecord's children) or, for tree shape only, to a new parent node.

For tree shape models if there is a parentIdentityField the moved records will have the parent identity field set to the identity of the new parent record.

Return the parent node of the given node. Only supported for tree shape models that have an identityField option defined.

This method must only be used on tree shape models.

Return the record at the given index within the model collection. Only applies to table shape models.

var record = model.recordAt(5);

Revert one or more records to the way they were when first added to the model or last saved. This undoes any changes made to the records. See also model#canRevertRecord.

if ( myModel.canRevertRecord( record ) ) {
    myModel.revertRecords( [record] );
}

Return the root node of the tree. An error is thrown if the model shape is not tree.

var rootNode = model.root();

Save all changed model data to the server. The current changes are copied to the save request except that volatile fields are not included (they are omitted/deleted i.e. not null or undefined) and the metadata has the op property added with value "d" if the record was deleted, "i" if the record was inserted, and "u" if the record was updated. If the record has no metadata field defined then one is added. For array records it is the last element, for object records it is property _meta.

It is possible to continue making changes to the model while a save is in progress. Can use either the callback argument or the returned promise to determine when the request is complete.

See also apex.model.save.

Give the model data. This is used in cases where the model doesn't get data from the server or at least not using the built in mechanisms.

Set the disabled property of the model#getRecordMetadata for the record given by pRecordId. This is a convenience method that looks up the record metadata, sets the disabled property, and calls the model#metadataChanged method if the value changed.

Set the hidden property of the model#getRecordMetadata for the record given by pRecordId. This is a convenience method that looks up the record metadata, sets the hidden property, and calls the model#metadataChanged method if the value changed.

Set the value of the given model option. The model options are provided in the call to apex.model.create. See also model#getOption.

The options that can be set are:

• genIdPrefix
• pageItemsToSubmit
• fetchData
• saveData
• regionData
• parentRecordId
• editable
• pageSize
• requestOptions
• callServer
• visibilityFilter
• visibilityFilterContext

Set the value of a record field given the record id. This is only useful when the model shape is table or tree. If there are many field values to get or set use model#getRecord followed by model#getValue or model#setValue. See also model#getRecordValue.

model.setRecordValue( "00013", "NAME", newName );

Select or unselect the given record.

This method should only be used by view widgets to persist the view selection state in metadata property sel. Note there is no notification about this metadata change. Listen to the view for selection change events. Also use the view to change the selection.

Sets the validity and associated validation message of a record or record field.

var invalidReasonMessage = checkRecord( recordId );
if ( invalidReasonMessage ) {
    model.setValidity( "error", recordId, null, invalidReasonMessage );
} else {
    this.model.setValidity( "valid", recordId );
}

Set the value of a record field given the record itself or omit the record when the model shape is record. See also model#getValue.

An error is thrown if the record does not allow editing or the field does not allow being set.

model.setValue( someRecord, "NAME", newName );

var result = model.setValue( someRecord, "PART_NO", newPartNo );
if ( result === "DUP" ) {
    apex.message.alert( "The part number " + newPartNo + " is already taken." );
}

model.setValue( "NAME", newName );

Subscribe to model change notifications by adding an observer.

var viewId = model.subscribe( {
    onChange: function( changeType, change ) {
        // respond to model changes
    }
} );

var viewId = model.subscribe( {
    viewId: this.element[0].id
    onChange: function(changeType, change) {
        // respond to model changes
    },
    progressView: this.element
} );

Transform a copy of the table shape model data into another data structure according to the provided template rules. The transformed output data structure is returned.

 {
     a: {
         b: [<items go here>]
     }
 }
 

 {
     a: [
         {
             b: [<items for records with enabled = yes go here>]
         },
         {
             b: [<items for records with enabled = no go here>]
         }
     ]
 }
 

var data = mymodel.transform( {
             template: [ {
                     path: "groups",
                     uniqueIndexField: "DEPTNO",
                     item: { name: "DEPTNO" }
                 }, {
                     path: "series",
                     uniqueIndexField: "JOB",
                     item: { name: "JOB" }
                 }, {
                     path: "series/[JOB]/items",
                     item: { label: "'AVG_SAL'",
                             value: "AVG_SAL",
                             name: "DEPTNO"
                         }
                 } ]
             });

Unsubscribe to model change notifications.

model.unSubscribe(viewId);

Update the visibility of all records currently in the model by calling the visibilityFilter function and setting the record hidden metadata property for each record. Useful for client side filtering of views of table or tree shaped models. This method does nothing if the visibilityFilter or visibilityFilterContext options are not set.

Client side filtering works best for reasonable sized reports and when the model has all the data to filter on. Not all view layer components will make use of the hidden property. For those that do it may only work if the view has rendered all the data.

See also model#setHiddenState and the visibilityFilter and visibilityFilterContext options of apex.model.create.

var filterItem = apex.item("P1_FILTER"),
    lastFilterString = null,
    filterContext = {
        matchString: ""
    };

function myFilter( model, record, context ) {
    var match = false;
    // match record against context.matchString and return true if there is a match
    return match;
};

function checkFilter() {
    var value = filterItem.getValue();

    if ( value !== lastFilterString ) {
        // only filter if the value has changed and don't do it too often
        debounceFilterCards( value );
        lastFilterString = value;
    }
};

function filterCards( filterString ) {
    var model = apex.region( "people" ).call( "getModel" );
    filterContext.matchString = filterString.toUpperCase(); // toUpperCase typical for case independent compare
    model.updateVisibility( filterContext );
};
var debounceFilterCards = apex.util.debounce( filterCards, 200 );

// these options could instead be set in region JavaScript Initialization Code
var model = apex.region( "people" ).call( "getModel" );
    model.setOption( "visibilityFilter", myFilter );
    model.setOption( "visibilityFilterContext", filterContext );

filterItem.element.on( "input", function() {
    checkFilter();
} );
checkFilter();

Traverse the tree shape model. Methods of the pVisitor object are called as follows:

• First the visitor node method is called for the pNode passed to walkTree.
• If the node has children the remaining steps are done.
• The visitor beginChildren method is called.
• For each child node walkTree is called performing these steps recursively.
• The visitor endChildren method is called.

var indent = "";
model.walkTree( model.root(), {
    node: function( node, parent ) {
        console.log( indent + "Node: " + model.getValue( node, "NAME" ) );
    },
    beginChildren: function( node ) {
        indent += "    ";
    },
    endChildren: function( node ) {
        indent = indent.substring(4);
    }
}, null );

A callback function to do additional access checking. See the check option property of apex.model.create and the model#check method.

The field metadata describes the field and affects how the model uses the field. It may contain additional properties especially if the metadata is shared with view layers.

This callback is used by the model#forEach and model#forEachInPage methods.

A model is uniquely identified by a string name and optional string instance id. The instance id is used to support multiple detail models in a master detail arrangement. The instance id is the identity value of the record in the master model for which the detail model pertains. The form for a model id is "name" or a tuple array ["name","instance"]

"MyModel"

["MyDetailModel", "000109"]

A model node is a synonym for model.Record that is more naturally used when the model has a tree shape.

Information about an observer for subscribing to this model. See model#subscribe and model#unSubscribe.

A model record is either an array or an object depending on the model option recordIsArray.

Metadata related to a specific record field.

Metadata properties that the model creates and uses.