- Since:
- 5.1
Example
Models are typically used by advanced widgets to display, interact with, and edit data. The following is a high level sketch of how a widget might use a table shape model. Much of the work in interfacing with a model is handled by tableModelViewBase so deriving a widget from that base widget can save time and effort.
// 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 a 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 );
Properties:
Name | Type | Description | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "addData" | |||||||||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "clearChanges" | |||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "copy" | ||||||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "delete" | |||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "insert" | ||||||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "metaChange" | |||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "move" | ||||||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description |
---|---|---|
changeType |
string | "refresh" |
change |
object | Empty object |
Properties:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "refreshRecords" | ||||||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "revert" | ||||||||||||
change |
object |
Properties
|
Properties:
Name | Type | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
changeType |
string | "set" | ||||||||||||||||||
change |
object |
Properties
|
Parameters:
Name | Type | Description |
---|---|---|
pRequestData |
object | An empty or partially filled in object to which changes for this model will be added. |
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pParentRecord |
model.Record |
<optional> |
The parent record to add children to if the shape is tree, null if the shape is table. |
pAddAction |
string |
<optional> |
Specifies how/why the records are to be added. Standard values are "new", "move", or "copy". |
pRecordsToAdd |
Array.<model.Record> |
<optional> |
An array of the records to be added. Only used for tree shape models. |
Returns:
- Type
- boolean
Example
This example checks if adding is allowed before inserting a record.
if ( myModel.allowAdd() ) {
myModel.insertNewRecord();
}
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
Parameters:
Name | Type | Description |
---|---|---|
pRecord |
model.Record | The record to check if deleting is allowed. |
Returns:
- Type
- boolean
Example
This example checks if deleting is allowed before deleting a record.
if ( myModel.allowDelete( record ) ) {
myModel.deleteRecords( [record] );
}
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
Parameters:
Name | Type | Description |
---|---|---|
pRecord |
model.Record | The record to check if it can be dragged. |
Returns:
- Type
- boolean
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
Parameters:
Name | Type | Description |
---|---|---|
pRecord |
model.Record | The record to check if editing is allowed. |
Returns:
- Type
- boolean
Example
This example checks if editing is allowed before setting a value.
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecord |
model.Record | The record to check if it can be reverted. |
Returns:
- Type
- boolean
Example
This example checks if a record can be reverted before reverting it.
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pOperation |
string | One of the default checks ("canEdit", "canDelete", "canAdd", "canDrag") or a custom operation. | |
pRecord |
model.Record |
<optional> |
The record to check if action is allowed on it. |
pAddAction |
string |
<optional> |
Only used by allowAdd see model#allowAdd for details. |
pRecordsToAdd |
Array.<model.Record> |
<optional> |
Only used by allowAdd see model#allowAdd for details. |
Returns:
- Type
- boolean
child(pNode, pIndex) → {model.Node}
Return the child at pIndex of node pNode.
This method must only be used on tree shape models.
Parameters:
Name | Type | Description |
---|---|---|
pNode |
model.Node | The node who's ith child is to be returned. |
pIndex |
integer | The index of the child node. |
Returns:
- Type
- model.Node
Example
This example loops over the children of a parent node.
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.
Parameters:
Name | Type | Description |
---|---|---|
pNode |
model.Node | The node who's children are to be counted. |
Returns:
- Type
- integer
Example
This example loops over the children of a parent node.
var i, node;
for ( i = 0; i < model.childCount( parentNode ); i++ ) {
node = mode.child( parentNode, i );
// do something with node
}
Fires:
Example
This example clears all the changes of an interactive grid with static id "emp"
in response to a Cancel or Abort button being pressed by the user. Use in a Execute JavaScript Code dynamic action.
If not for the call to clearChanges
before refresh
the interactive grid would prompt the user to save changes.
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.
Fires:
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pRecords |
Array.<model.Record> | Array of records to copy. | |
pParentRecord |
model.Record |
<optional> |
Only used when the shape is tree. This is the parent node to insert the copies into. If null then insert to root. |
pAfterRecord |
model.Record |
<optional> |
The copied records are added after this record or if null at the beginning. |
Fires:
Returns:
- Type
- Array.<string>
Example
This examples copies the selected records to just after the last selected record.
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecords |
Array.<model.Record> | An array of records to delete. |
Fires:
Returns:
- Type
- number
Example
This example checks if deleting is allowed before deleting a record.
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecords |
Array.<model.Record> | array of records to determine drag operations for or null when dragging an external record into this model. |
Returns:
{ normal: "move", ctrl: "copy" }
or if pRecords
is null { normal: "add" }
- Type
- object
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pOffset |
integer |
<optional> |
Zero based offset of the data to fetch. Only applies to table shape models. This is rarely needed because table data is automatically fetched as needed when requested via the model#forEachInPage method. Omit this param when not needed. |
pCallback |
function |
<optional> |
A function to call when the request is complete. The callback is passed an Error argument only if there is an error. |
pNoProgress |
boolean |
<optional> |
Set to true to not show progress during the fetch. |
Fires:
Returns:
pOffset
is beyond the end of the data or master record is
inserted or deleted. If and only if a promise is returned, pCallback
will be called.
It receives no arguments when resolved and an Error
argument when rejected.
- Type
- promise
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.
Parameters:
Name | Type | Description |
---|---|---|
pCallback |
function | function that is called after each fetch completes. It receives an object with properties:
|
Example
This example fetches all the data before using model#forEach to loop over the records.
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. The top level
of nodes should not be lazy loaded.
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pNode |
model.Node | The node record to fetch children for. | |
pCallback |
function |
<optional> |
callback function that is called after nodes have been fetched or there is an error. |
Fires:
Returns:
- Type
- promise
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pRecords |
model.Record | Array of records to be fetched. | |
pCallback |
function |
<optional> |
A function to call when the request is complete. The callback is passed an Error argument only if there is an error. |
Fires:
Returns:
pCallback
is not called.
- Type
- promise
Example
This example fetches the selected records from interactive grid with static id "emp". There is often no need know when the Ajax request completes because the view is updated from model notifications.
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pCallback |
model.IteratorCallback | Function called for each record in the model collection. The function is given the current record, index, and id. | |
pThisArg |
* |
<optional> |
Value to use as this
when calling pCallback . |
Example
This example calculates the total of field SALARY for all the records that are currently in the model. Deleted and aggregate records are skipped.
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pOffset |
integer | Zero based index to begin iterating. | |
pCount |
integer | The number of records to call pCallback for. |
|
pCallback |
model.IteratorCallback | Function called for each record in the model collection. The function is given the current record, index, and id. | |
pThisArg |
* |
<optional> |
Value to use as this when calling
pCallback . |
Example
This example renders a pageSize
page of records
starting at offset currentPageOffset
.
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
}
} );
getChanges() → {Array.<model.RecordMetadata>}
Return an array of record metadata for all changed records. Do not make any changes to the data structure returned. See also model#isChanged.
Returns:
- Type
- Array.<model.RecordMetadata>
Example
This example logs a console message if the model has changed that includes the number of changes.
if ( model.isChanged() ) {
console.log("Model has " + model.getChanges().length + " changes.");
}
getErrors() → {Array.<model.RecordMetadata>}
Return an array of record metadata for all records with errors. Do not make any changes to the data structure returned.
Returns:
- Type
- Array.<model.RecordMetadata>
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.
Parameters:
Name | Type | Description |
---|---|---|
pFieldName |
string | The field name. |
Returns:
- Type
- string | number | undefined
Example
This example gets the field key for the model field named "COST" and uses it
in a loop over array of records selectedRecords
.
var i, cost,
costKey = model.getFieldKey("COST");
for ( i = 0; i < selectedRecords.length; i++ ) {
cost = selectedRecords[i][costKey];
// do something with cost
}
getFieldMetadata(pFieldName) → {model.FieldMeta}
Return metadata object for given field name. The field metadata is supplied when the model is created
in option property fields
.
Parameters:
Name | Type | Description |
---|---|---|
pFieldName |
string | The field name. |
Returns:
- Type
- model.FieldMeta
Get the value of the given model option. The model options are provided in the call to apex.model.create. See also model#setOption.
Parameters:
Name | Type | Description |
---|---|---|
pName |
string | Name of option to get. |
Returns:
- Type
- *
Examples
This example gets the onlyMarkForDelete
option.
var markForDelete = model.getOption( "onlyMarkForDelete" );
This example gets the hasTotalRecords
option.
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pRecordId |
string | Array.<string> |
<optional> |
The record id. |
Returns:
pRecordId
is found.
Examples
This example returns the record with identity "001002".
record = model.getRecord( "001002" );
This example has a table shape model with two identity fields. It returns the
record from a model with identity ["AXB9", "00003"]
.
record = model.getRecord( ["AXB9", "00003"] );
This example returns the record from a model with shape record.
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecord |
model.Record | The record to get the id from. |
Returns:
- Type
- string
Example
This example gets the identity of record someRecord
and uses it to get the record metadata.
var id = model.getRecordId( someRecord ),
meta = model.getRecordMetadata( id );
// use meta for something
getRecordMetadata(pRecordId) → {model.RecordMetadata}
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecordId |
string | Array.<string> | Value of the record's identity field or array of values of the record's identity fields or value returned by model#getRecordId. |
Returns:
pRecordId
.
- Type
- model.RecordMetadata
Example
This example checks if the record someRecord
is updated.
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecordId |
string | Array.<string> | Value of the record's identity field or array of values of the record's identity fields or value returned by model#getRecordId. |
pFieldName |
string | Name of record field to get. |
Returns:
- Type
- *
Example
This example gets the NAME field of the record with identity "00013".
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.
Returns:
- Type
- integer
getSelectedRecords() → {Array.<model.Record>}
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:
- Type
- Array.<model.Record>
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:
- Type
- number
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.
Returns:
- Type
- integer
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pRecord |
model.Record |
<optional> |
The record to return the value of the given column. Omit if model shape is record. |
pFieldName |
string | Name of record field to get. |
Returns:
- Type
- *
Examples
This example returns the NAME field of the given record.
var name = model.getValue( someRecord, "NAME" );
This example returns the NAME field from a record shape model.
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.
Parameters:
Name | Type | Description |
---|---|---|
pNode |
model.Node | The node to check if it has any children. |
Returns:
- Type
- boolean
Example
This example logs a message to the console if the node is a leaf (has no children).
if ( model.hasChildren( node ) === true ) {
console.log("node is a leaf");
}
Return true if the model has any errors.
Returns:
- Type
- Boolean
Example
This example logs a console message if the model has 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.
Parameters:
Name | Type | Description |
---|---|---|
pRecord |
model.Record | The record to return the index of. |
Returns:
- Type
- integer
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pParentRecord |
model.Record |
<optional> |
Parent tree node. Only for tree shape models, must be null otherwise. |
pAfterRecord |
model.Record |
<optional> |
Record after which to insert the new record. If not given the new record is inserted at the beginning. |
pNewRecord |
model.Record |
<optional> |
The new record to insert. If not given a new record is created using defaults. The identity, meta, children, and parent fields if any will be initialized. |
Fires:
Returns:
- Type
- string
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.
Returns:
- Type
- boolean
Example
This example logs a console message if the model has changed.
if ( model.isChanged() ) {
console.log("Model has changes.");
}
Parameters:
Name | Type | Description |
---|---|---|
pFieldName |
string | Name of record field. |
Returns:
- Type
- boolean
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pRecordId |
string | Value of the record's identity field or array of values of the record's identity fields or value returned by model#getRecordId. | |
pFieldName |
string |
<optional> |
Name of record field that has a metadata change if any. |
Fires:
modelId() → {model.ModelId}
Returns:
- Type
- model.ModelId
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pRecords |
Array.<model.Record> | Array of records to move. | |
pParentRecord |
model.Record |
<optional> |
Only used when the shape is tree. This is the parent node to insert the moved records into. If null then insert to root. |
pAfterRecord |
model.Record |
<optional> |
The moved records are added after this record or if null at the beginning. |
Fires:
Returns:
- Type
- Array.<string>
parent(pNode) → {model.Node}
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.
Parameters:
Name | Type | Description |
---|---|---|
pNode |
model.Node | The node to get the parent of. |
Returns:
- Type
- model.Node
recordAt(index) → {model.Record}
Return the record at the given index within the model collection. Only applies to table shape models.
Parameters:
Name | Type | Description |
---|---|---|
index |
integer | The index of the record to return. |
Returns:
- Type
- model.Record
Example
This example returns the fifth record in the collection assuming it exists.
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecords |
Array.<model.Record> | The records to revert. |
Fires:
Returns:
pRecords
if some of the records had no changes to revert.
- Type
- integer
Example
This example checks if a record can be reverted before reverting it.
if ( myModel.canRevertRecord( record ) ) {
myModel.revertRecords( [record] );
}
root() → {model.Node}
Return the root node of the tree. An error is thrown if the model shape is not tree.
Returns:
- Type
- model.Node
Example
This example gets the tree shape model root node.
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pCallback |
function |
<optional> |
A function to call when the save request is complete. callback( error, responseData ); The callback is passed an Error argument or array of server errors only if there is an error. Otherwise error is null. |
Returns:
- Type
- promise
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pData |
array | Model data to set. | |
pOffset |
integer |
<optional> |
Offset at which to add the data. |
Fires:
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
Parameters:
Name | Type | Description |
---|---|---|
pName |
string | Name of option to set. Not all options can be set. |
pValue |
* | Value to set the option to. |
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecordId |
string | Array.<string> | Value of the record's identity field or array of values of the record's identity fields or value returned by model#getRecordId. |
pFieldName |
string | Name of record field to set. |
pValue |
* | Value to set. |
Example
This example sets the NAME field of the record with identity "00013".
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.
Parameters:
Name | Type | Description |
---|---|---|
pRecordId |
The record id to set the selection state metadata. | |
pSelected |
boolean | The desired record selection state; true to select and false to unselect. |
Sets the validity and associated validation message of a record or record field.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pValidity |
string | one of "error", "warning", "valid". | |
pRecordId |
string | Value of the record's identity field or array of values of the record's identity fields or value returned by model#getRecordId. | |
pFieldName |
string |
<optional> |
Name of field that the validity state applies to or null if it applies to the whole record. |
pMessage |
string |
<optional> |
Error or warning message text or omit if valid |
Example
This examples calls a function, checkRecord
, that returns
an error message if the record is not valid and null if it is valid. It then sets the validity of the record.
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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pRecord |
model.Record |
<optional> |
The record that will have a field set to the given value. Omit if model shape is record. |
pFieldName |
string | Name of record field to set. | |
pValue |
* | the value to set |
Fires:
Returns:
- "SET": The value was set.
- "DUP": The value was not set because of duplicate identity. This can only happen when setting an identity field. Note: Even if the new value is unique on the client it may still result in an error when saving because the client in general does not have all the data that the server does.
- "NC": The value was not set because the new value is equal to the old value.
- null: The record is not in the model.
- Type
- string | null
Examples
This example sets the NAME field of the given record.
model.getValue( someRecord, "NAME", newName );
This example sets the identity field PART_NO of the given record. It checks for a duplicate value and gives a message if the new part number is already taken.
var result = model.getValue( someRecord, "PART_NO", newPartNo );
if ( result === "DUP" ) {
apex.message.alert( "The part number " + newPartNo + " is already taken." );
}
This example sets the NAME field from a record shape model.
model.getValue( "NAME", newName );
Subscribe to model change notifications by adding an observer.
Parameters:
Name | Type | Description |
---|---|---|
pObserver |
model.Observer | An observer object that includes a callback function to receive notifications. |
Returns:
viewId
property if there is one. One is generated if not given in
pObserver
- Type
- string
Examples
This simple example subscribes to a model to handle notifications.
var viewId = model.subscribe( {
onChange: function( changeType, change ) {
// respond to model changes
}
} );
This example is typical of what a widget that displays model data would do to subscribe.
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.
Parameters:
Name | Type | Attributes | Description | |||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pOptions |
Object | An object with properties that define how the model data is to be transformed.
All properties are optional except for template.
Properties
|
||||||||||||||||||||||||||||||||||||||||
pContext |
Object |
<optional> |
This is the output object to return with data arrays filled in based on the template rules. If pContext is not given an empty object is used as a starting point. All functions are called in the context of this object. Note: if the template rule(s) don't have a path then pContext can be an array. |
Returns:
pContext
if it was given.
- Type
- Object
Example
The following example generates groups and series data for a jet Bar chart from a model
created from:
select job, deptno, avg(sal) as avg_sal from emp group by job, deptno
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.
Parameters:
Name | Type | Description |
---|---|---|
pViewId |
string | The view id returned from model#subscribe. |
Example
This example unsubscribes from this model using the viewId
returned when subscribing.
model.unSubscribe(viewId);
Traverse the tree shape model. Methods of the pVisitor
object
are called as follows:
- First the visitor
node
method is called for thepNode
passed towalkTree
. - 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.
Parameters:
Name | Type | Attributes | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
pNode |
model.Node | The node to start with. This node is visited and then all of its children are. | |||||||||||||||||
pVisitor |
object |
Properties
|
|||||||||||||||||
pParentNode |
model.Node |
<optional> |
The parent node of pNode or null if
pNode is the root. If this argument is omitted or undefined and
the model has the identityField option defined the parent node
will be determined automatically. If this argument is omitted or undefined and
the model does not have the identityField option defined then
the parent parameter in each call to the visitor node method is null. |
Example
This example walks the tree shape model starting at the root logging information about the tree as it goes. Indentation shows the structure of the tree. The nodes in this model have a NAME field.
var indent = "";
model.walkTree( model.root(), {
node: function( node, parent } {
console.log( "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.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
pResult |
boolean | The result of the access checking so far. | |
pOperation |
string | One of the default checks ("canEdit", "canDelete", "canAdd", "canDrag") or a custom operation. | |
pRecord |
model.Record | The record to check if action is allowed on it. | |
pAddAction |
string |
<optional> |
Only used by allowAdd see model#allowAdd for details. |
pRecordsToAdd |
Array.<model.Record> |
<optional> |
Only used by allowAdd see model#allowAdd for details. |
Returns:
- Type
- boolean
Type:
- object
Properties:
Name | Type | Description |
---|---|---|
index |
string | Only used when records are arrays. This is the index into the array where the field value is stored. |
defaultValue |
* | This value is used when a new record is added or an existing record is duplicated and noCopy is true. The defaultValue has no effect for the identity, meta, children, and parent fields if defined. If there is no defaultValue empty string is used. |
parentField |
string | Only applies if the model has a parentModel. When a new record is added or an existing record is duplicated and noCopy is true the value of this field is taken from the parentField of the parentModel This is useful for foreign key fields but can be any field that gets a default from the parentModel. |
noCopy |
boolean | If true the field value is not copied when a record is copied/duplicated. |
readonly |
boolean | If true the field cannot be edited. |
volatile |
boolean | The field is generated by the server. It cannot be edited. It is not sent back to the server. This means that for records stored as arrays the volatile fields should be at the end or the server must account for the missing volatile fields when using other field's index. Volatile fields may depend on (are calculated from) other fields and the value may be considered stale if the record is edited. It is up to the view layers to make this determination. |
virtual |
boolean | A virtual field has no associated data. None of the other properties apply. The main purpose for including a virtual field is so that view layers and the model can share the same field metadata. This allows view layers to have fields that don't have corresponding data in the model. |
Parameters:
Name | Type | Description |
---|---|---|
pRecord |
model.record | The current record. |
pIndex |
number | The zero based index within the model collection of the current record. |
pId |
string | The identity of the current record if the model
identityField option is given. If there is no identity then this is
undefined for tree models and is the pIndex as a string for table models. |
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"]
Type:
- string | array
Examples
A model with no instance.
"MyModel"
A detail model with instance id "000109".
["MyDetailModel", "000109"]
Type:
- array | object
Information about an observer for subscribing to this model. See model#subscribe and model#unSubscribe.
Type:
- object
Properties:
Name | Type | Attributes | Description |
---|---|---|---|
viewId |
string |
<optional> |
A unique key that can be used to unsubscribe. A DOM element id makes a good unique key. |
onChange |
function | A function to receive change notifications. The signature is
function(changeType, change) changeType is a string describing the change such as "delete"change is an object with details about the change.See each notification for details. |
|
progressView |
jQuery |
<optional> |
jQuery object to center a progress spinner over while performing an asynchronous network operation such as model#fetch or model#save. |
progressOptions |
object |
<optional> |
Options object for apex.util.showSpinner. |
recordIsArray
.
Type:
- array | object
Properties:
Name | Type | Description |
---|---|---|
error |
boolean | true if the field has an error. |
warning |
boolean | true if the field has a warning. |
message |
string | Only present when error
or warning are true. Describes the error or warning condition. |
disabled |
boolean | true if the field is disabled. Disabled fields are written to the server as empty string. |
highlight |
string | A string that view layers can use to provide extra styling for the field. |
ck |
string | A checksum. If present and not null indicates the record field is readonly. |
url |
string | Use for cells that are links. This is the link target. The cell value is the link label. |
Properties:
Name | Type | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
deleted |
boolean | true if the record has been deleted otherwise false or undefined. | |||||||||
inserted |
boolean | true if the record is newly created and inserted/added to the collection otherwise false or undefined. | |||||||||
autoInserted |
boolean | true if the record was auto inserted (these records are not saved if not also updated) | |||||||||
updated |
boolean | true if the record has had any fields changed. | |||||||||
original |
model.Record | When updated is true this is the original record before any changes. | |||||||||
record |
model.Record | Reference to the record that this metadata is about. | |||||||||
parent |
model.Record | The parent record of this record. Only applies to tree shape models. | |||||||||
error |
boolean | true if the record as a whole has an error. | |||||||||
warning |
boolean | true if the record as a whole has a warning. | |||||||||
message |
string | Only present when error
or warning are true. Describes the error or warning condition. |
|||||||||
sel |
boolean | true if the record is selected and false otherwise. | |||||||||
highlight |
string | A string that view layers can use to provide extra styling for the record. | |||||||||
allowedOperations |
object |
Properties
|
|||||||||
canEdit |
boolean | Derived from allowedOperations.update |
|||||||||
canDelete |
boolean | Derived from allowedOperations.delete |
|||||||||
endControlBreak |
boolean | Used by views to implement control break UI. | |||||||||
agg |
* | For aggregate records this is truthy. | |||||||||
fields |
Object.<string, model.RecordFieldMetadata> | An object that maps from a field name to metadata about the field. |