JSDoc: Namespace: model

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:

Use apex.model.create to create a model.
Use apex.model.list to list all the existing models.
Use apex.model.get to return an existing model.
Use apex.model.release to release a model once you are done with it.

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.