JSDoc: Namespace: model

The apex.model namespace contains methods used to manage client side Application Express data models. These models store data for display by UI components. They correspond to the view-model in the Model-View-ViewModel (MVVM) pattern. 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 associated with the model will manage its life cycle.

Models typically act as an intermediary between data persisted on the server and one or more views on the client. The regionId option associates the model with an APEX region for the purpose of fetching and saving data. Models can be created without a regionId. These are known as local models and they cannot fetch data from or save data to the server.

There are also methods such as apex.model.save, apex.model.anyChanges, and apex.model.anyErrors that operate on multiple models.

Master Detail

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 provided 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 apex.model.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 in the check for changes.
`pModelId`	model.ModelId	<optional>	Model identifier as given in call to apex.model.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

Example

This example displays an alert message if any (non-local) models on the page have unsaved changes.

if ( apex.model.anyChanges() ) {
    apex.message.alert("Save Changes");
}

(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 in check for errors.
`pModelId`	model.ModelId	<optional>	Model identifier as given in call to apex.model.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

Example

This example displays an alert message if any (non-local) models on the page have errors.

if ( apex.model.anyErrors() ) {
    apex.message.alert("Fix Errors");
}

(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.
`requestOptions`	object	The properties of this object are included in the options object of apex.server.plugin for any ajax requests made by the model.
`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. This option currently has no effect and is reserved for future use.
`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.
`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.
`metaField`	string	The name of meta field. The meta field stores metadata about the record and possibly record fields The default is null.
`check`	model.CheckCallback	A function that is called to do additional permission checking.
`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) 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.
`makeLoadingIndicator`	function	function(jQuery[] progressViews, Object[] progressOptions) This is a function that receives an array of progress views and a corresponding array of progress options and returns a function suitable for the apex.server.plugin `loadingIndicator` option. It can also return null to disable showing any loading indicator. If not specified the default is to show the standard APEX progress spinner centered over any visible view(s) of the model. A view informs the model about its existence by subscribing to the model and passing in the `progressView` and optional `progressOptions` options. See also the model#subscribe method and model.Observer.

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 the 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

Example

This example creates a very simple local table shape model called "people" that stores name and age. The records are arrays and the model is given some initial data. The model is editable and the ID field is the record identity.

var fields = {
        ID: {
            index: 0
        },
        NAME: {
            index: 1
        },
        AGE: {
            index: 2
        }
    },
    data = [
        ["00010", "Mark", "32"],
        ["00091", "Mary", "27"],
        ...
    ];
apex.model.create("people", {
    shape: "table",
    recordIsArray: true,
    fields: fields,
    identityField: "ID",
    editable: true,
    paginationType: "none"
}, data, data.length );

(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 apex.model.create or just a model name.

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 apex.model.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 apex.model.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 apex.model.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) 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 apex.model.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

Example

This example saves all the models on the page that have changes.

apex.model.save();

(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.