The apex.model namespace contains methods used to manage client side APEX data models. These models
store data for display by UI components. See model for details.
This namespace contains functions to manage the lifecycle of a model:
Models are reference counted so for every call to get or create you must call release. Failure to do so can
result in unused models taking up memory. Typically the APEX region plug-in associated with the model will manage
its life cycle.
There are also methods such as apex.model.save, apex.model.anyChanges, and apex.model.anyErrors
that operate on multiple models.
Models can be arranged in a master detail configuration. This is done by providing the parentModel and parentRecordId
options when creating the detail models. A single master model can have multiple kinds of detail models. For example
projects can have tasks and members as details. Each kind of detail model has one or more model instances; each related
to a record in the master model. Detail instance models share the same name and field configuration but each
has a distinct instance id and different data. A model is uniquely identified by a model.ModelId, which in the case
of a detail model contains the detail name and instance id. Detail models are cached so that data doesn't have to be
fetched from the server unnecessarily. The view layer typically shows a view of the detail instance model that is
associated with the current record of the master view. As the current record of the master changes the view layer
changes the detail model instance the detail view is showing. The view layer will get a cached instance model if
there is one and if not will create the instance model. The maximum number of detail instances to cache is controlled
with the apex.model.getMaxCachedModels and apex.model.setMaxCachedModels functions. It is the least
recently used model that is kicked out of the cache. Models that have changes are not destroyed unless
apex.model.destroy is called.
A detail model can be a master to its own set of sub-detail models. This relationship can be nested to any depth.
- Since:
Functions
(static) addChangesToSaveRequest(pRequestData, pModelIdopt, pIncludeRelatedopt) → {function}
Low level function to add changes for any of the specified models to a request.
Changes are added to the provide request data. This doesn't actually send the request to the server.
In most cases
apex.model.save should be used rather than this function.
Parameters:
Name |
Type |
Attributes |
Description |
pRequestData |
object
|
|
An initial request object that will have all changes for the specified models added to it. |
pModelId |
model.ModelId
|
<optional>
|
Model identifier as given in call to create or just a model name.
See apex.model.list for how this parameter is used to select which models to operate on. |
pIncludeRelated |
boolean
|
<optional>
|
If true then any dependents of any selected models are included if they have changes. |
Returns:
A function that must be called with the promise returned from the save request.
-
Type
-
function
(static) anyChanges(pIncludeLocalopt, pModelIdopt, pIncludeRelatedopt) → {boolean}
Returns true if any of the specified models have changes.
Parameters:
Name |
Type |
Attributes |
Description |
pIncludeLocal |
boolean
|
<optional>
|
If true models that don't have a regionId will be included. |
pModelId |
model.ModelId
|
<optional>
|
Model identifier as given in call to create or just a model name.
See apex.model.list for how this parameter is used to select which models to operate on. |
pIncludeRelated |
boolean
|
<optional>
|
If true then any dependents of any selected models are included in check |
Returns:
true if any of the specified models have changed.
-
Type
-
boolean
(static) anyErrors(pIncludeLocalopt, pModelIdopt, pIncludeRelatedopt) → {boolean}
Returns true if any of the specified models have errors.
Parameters:
Name |
Type |
Attributes |
Description |
pIncludeLocal |
boolean
|
<optional>
|
If true models that don't have a regionId will be included. |
pModelId |
model.ModelId
|
<optional>
|
Model identifier as given in call to create or just a model name.
See apex.model.list for how this parameter is used to select which models to operate on. |
pIncludeRelated |
boolean
|
<optional>
|
If true then any dependents of any selected models are included in check. |
Returns:
true if any of the specified models have errors.
-
Type
-
boolean
(static) create(pModelId, pOptions, pDataopt, pTotalopt, pMoreDataopt, pDataOverflowopt) → {model}
Create a model with the given identity, options and optionally initial data.
When you are done with the model you must call apex.model.release. Or if you are sure no one else is using it
you can call apex.model.destroy.
Parameters:
Name |
Type |
Attributes |
Description |
pModelId |
model.ModelId
|
|
Model identifier. Must be unique for the page. Creating a model with an identifier
that already exists will overwrite the existing model. |
pOptions |
object
|
|
Model options. All properties are optional unless specified otherwise.
Properties
Name |
Type |
Description |
shape |
string
|
The shape of data the model holds. One of "table", "tree", or "record". The default is "table". |
recordIsArray |
boolean
|
If true record fields are stored in an array otherwise the record is an object.
If recordIsArray is true then the field metadata must include the index property. The default is false. |
hasTotalRecords |
boolean
|
Only applies if shape is "table". If true the sever will always provide the total
number of records. The default is false unless paginationType is "none". |
genIdPrefix |
string
|
A string prefix to use when generating ids for inserted records. The default is "t". |
fields |
Object.<string, model.FieldMeta>
|
This required option defines the fields of each record.
Each property is the name of a field. The value is a model.FieldMeta object with metadata about the field that
the model uses. |
regionId |
string
|
Primary region ID that this model is associated with for the purpose of exchanging
data with the APEX server. If there is no regionId then the model cannot use standard requests to fetch or save
data and therefore is just a local model. The default is null. |
ajaxIdentifier |
string
|
The Ajax Identifier used to identify the Ajax call to fetch or save data.
The default is null. |
pageItemsToSubmit: |
Array.<string>
|
An array of page item names to submit when fetching and saving data.
The default is null. |
regionData |
object
|
Additional data to send at the region level for all requests. The default is an empty object. |
fetchData |
object
|
Additional data to send in fetch requests. The default is an empty object. |
saveData |
object
|
Additional data to send in save requests. The default is an empty object. |
version: |
number
|
string
|
This is the version (could be a hash) of the model definition. The value
is opaque to the model. It is sent in all requests; fetch, save etc. If the server detects that the version is
different than it expects then it returns an error. This is to ensure that the client and server agree on the
general model and field definitions. The default is 1. TODO not yet used by server or views |
parentModel |
model.ModelId
|
Model identifier of parent (master) model or null if there is no parent.
The default is null. |
parentRecordId |
string
|
Only applies if parentModel is given. The record id of the record in the
parent model that this model is associated with. Typically this model's ModelId instance and the parentRecordId
are the same. The default is null. |
editable |
boolean
|
If true the model is editable and false otherwise. The default is false. |
onlyMarkForDelete |
boolean
|
If false deleted records are removed from the collection.
If true then deleted records are marked as deleted but remain in the collection. The default is true. |
identityField |
string
|
Array.<string>
|
Name of identity field or an array of identity field names if the
records have a multi valued primary key. Required if editable is true. It is a best practice to specify the
identityField even if the model is not editable as it can be useful for pagination, selection, and fetching
additional data. The default is null. |
typeField |
string
|
Name of type field. The type field associates a record with type information
provided in the type option. The default is null. See the type option for more information. |
childrenField |
string
|
This only applies for tree shape models. The name of the field that
contains an array of node children. The default is null. |
parentIdentityField |
string
|
This only applies for tree shape models. The name of parent node
identity field. The default is null. |
sequenceField |
string
|
This only applies to models that support reordering.
The name of the sequence field. The sequence field value should be a floating point number (or string representation of a number).
This value will be updated when adding, copying, or moving records. The default is null. TODO finish implementing |
metaField |
string
|
The name of meta field. The meta field stores metadata about the record and
possibly record fields The default is null. |
sequenceStep |
number
|
Only used if sequenceField is given. This is the preferred distance between sequence values
of adjacent records. The default is 10. |
saveSelection |
boolean
|
If true all selected records will be saved as well as any changed records.
The selection state metadata property "sel": true will be included on any selected record. The default is false. |
check |
model.CheckCallback
|
A function that is called to do additional permission checking. |
sortCompare |
function
|
A function to compare two records for the purpose of ordering.
The function signature is the same as the array sort method argument. This should not be used when the server
does the sorting. This is most useful for tree shape models so that newly added records/nodes are
put in the right order. TODO |
paginationType |
string
|
One of "none", "one", "progressive".
- none: no paging. the server has given all the data it has (it may be capped but you can't get more) TODO
- one: the model contains just one page at a time. when it asks the server for a new page it
replaces the previous one.
- progressive: the model will keep adding to its collection as it gets additional pages from
the server
This only applies to table shape models. The default is "none". |
pageSize |
integer
|
This is the number of table rows (records) to fetch from the server.
This only applies to table shape models. The default is 100. |
preFetch |
boolean
|
If true additional data will start to be fetched before all of the existing data
has been read by forEachInPage. The default is false. todo not yet implemented |
|
pData |
array
|
object
|
<optional>
|
Initial data to add to the model. For table shape data it is an array of
model.Record. For tree shape models it is a model.Node for the root. For record shape data it
is a single model.Record. If null or not given there is no initial data. |
pTotal |
integer
|
<optional>
|
Total number of records in servers collection. Only applies for table shape models. |
pMoreData |
boolean
|
<optional>
|
If true there is more data available on the server for this model. If false
pData contains all the data. If omitted or null determine if there is more data based on pData and pTotal.
If pTotal is not given assume there is more data on server.
Only applies for table shape models and only if paginationType is not "none". |
pDataOverflow |
boolean
|
<optional>
|
If true there is more than the maximum allowed records for this model.
Only applies for table shape models. |
Returns:
-
Type
-
model
(static) destroy(pModelId)
Destroy and remove a model by its identifier. This bypasses reference counting and caching. This method should
not be used unless you are sure that no one else is using the model.
If pModelId is a string model name and there are one or more instances they will all be destroyed.
Parameters:
Name |
Type |
Description |
pModelId |
model.ModelId
|
Model identifier as given in call to create. |
Example
Destroy the model with model id MyModel.
apex.model.destroy("MyModel");
(static) get(pModelId) → {model}
Get a model by its model identifier.
Parameters:
Name |
Type |
Description |
pModelId |
model.ModelId
|
Model identifier as given in call to create. |
Returns:
The model identified by pModelId.
-
Type
-
model
Example
Get access to a model with model id MyModel and release it when done.
var myModel = apex.model.get("MyModel");
// ... do something with myModel
apex.model.release("MyModel"); // release it when done
(static) getMaxCachedModels() → {integer}
Get the max number of cached detail instance models.
Returns:
Max cached detail instance models.
-
Type
-
integer
(static) list(pIncludeLocalopt, pModelIdopt, pIncludeRelatedopt) → {Array.<model.ModelId>}
Returns an array of all the currently defined model identifiers in no particular order.
If pModelId is null or not provided all models are listed.
If pModelId contains just a model name then just that model if any and all instances with the same model
name if any are returned.
If pModelId contains a model and an instance then just that model instance is included.
Specifying pModelId is most useful when pIncludeRelated is true.
Parameters:
Name |
Type |
Attributes |
Description |
pIncludeLocal |
boolean
|
<optional>
|
If true models that don't have a regionId will be included. |
pModelId |
model.ModelId
|
<optional>
|
Model identifier as given in call to create or just a model name. |
pIncludeRelated |
boolean
|
<optional>
|
If true then any dependents of any listed models are included. |
Returns:
Array of model identifiers
-
Type
-
Array.<model.ModelId>
(static) release(pModelId)
Release a model if it is not being used but may be used again in the future. This allows the model
to be destroyed if needed to conserve memory.
Models are reference counted. For every call to get or create a call to release with the same model id is
required. When the reference count is zero the model is destroyed unless it is changed or if it has a
parent model, in which case it is cached.
Parameters:
Name |
Type |
Description |
pModelId |
model.ModelId
|
Model identifier as given in call to create. |
Example
Get access to a model with model id MyModel and release it when done.
var myModel = apex.model.get("MyModel");
// ... do something with myModel
apex.model.release("MyModel"); // release it when done
(static) renameInstance(pOldId, pNewInstance)
todo xxx
Parameters:
Name |
Type |
Description |
pOldId |
|
|
pNewInstance |
|
|
(static) save(pRequestDataopt, pOptionsopt, pModelIdopt, pIncludeRelatedopt) → {promise}
Save any of the specified models that have changes. This consolidates all the model data to save into a single
request.
Parameters:
Name |
Type |
Attributes |
Description |
pRequestData |
object
|
<optional>
|
An initial request object that will have all changes for the specified models added to it. |
pOptions |
object
|
<optional>
|
Options to pass on to apex.server.plugin API. |
pModelId |
model.ModelId
|
<optional>
|
Model identifier as given in call to create or just a model name. |
pIncludeRelated |
boolean
|
<optional>
|
If true then any dependents of any selected models are included in check. |
Returns:
The promise from
apex.server.plugin if a save request is sent or null if there are no
changed models to save.
-
Type
-
promise
(static) setMaxCachedModels(n)
Set the max number of cached unreferenced, unchanged detail instance models that will be kept.
Parameters:
Name |
Type |
Description |
n |
integer
|
Number of unreferenced, unchanged detail instance models that will be kept. |