Final Class: Model

Oracle® JavaScript Extension Toolkit (JET)
16.1.0
F92237-01

Since:
  • 1.0
Module:
  • ojmodel

QuickNav

Fields

Methods

Type Definitions

Description

Object representing name/value pairs for a data service record


Usage

Signature:

final class Model

Typescript Import Format
//To import this class, use the format below.
import {Model} from "ojs/ojmodel";

For additional information visit:


Final classes in JET

Classes in JET are generally final and do not support subclassing. At the moment, final is not enforced. However, this will likely change in an upcoming JET release.


Constructor

new Model(attributes, options)

Parameters:
Name Type Argument Description
attributes Object <optional>
 Initial set of attribute/value pairs with which to seed this Model object
options Object <optional>
 collection: collection for this model

Mixes In

Fields

EventType :string

Properties:
Name Type Default Description
ADD string add Triggered when a model is added to a collection

The event passes these arguments to the handler:

    model: the model being added to the collection
    collection: the collection to which the model has been added
    options: any options passed in to the add call that triggered the event

ALL string all Triggered for any of the above events

The event passes the name of the actual event and then any arguments normally passed to that event following the name

ALLADDED string alladded Triggered by a collection during an add call once all models passed in have been added

The event passes these arguments to the handler:

    collection: the collection to which the models have been added
    models: the array of models that have been added
    options: any options passed in to the add call

ALLREMOVED string allremoved Triggered by a collection during a remove call once all models passed in have been removed and destroyed

The event passes these arguments to the handler:

    collection: the collection from which the models have been removed
    models: the array of models that have been removed
    options: any options passed in to the remove call

CHANGE string change Triggered when a model's attributes are changed. This can be the result of a clear call on a model; a property set call on a model; an unset call on a model; or the changing of properties due to the merging of models (in an add, for example)

The event passes these arguments to the handler:

    model: the model on which the change occurred
    value: for property-specific change events, the new value of the property being changed
    options: any options passed in to the call that triggered the change event. This is the second argument passed for overall change events, and the third parameter (after value) for property-specific change events.

DESTROY string destroy Triggered when a model is deleted from the data service (and thus from its Collection), due to a model destroy call

The event passes these arguments to the handler:

    model: the model being deleted
    collection: the deleted model's collection, if any

ERROR string error Triggered when a model has failed to update on the data service

The event passes these arguments to the handler:
collection or model: the collection or model that made the call that resulted in the error
xhr: the xhr argument for the failing request, if any
options: any options passed in to the call that triggered the failing request, plus the status and error as textStatus and errorThrown

INVALID string invalid Triggered on an error with data source interactions

The event passes these arguments to the handler:

    model: the model (or collection) on which the error operation happened
    xhr: the xhr involved, if relevant
    options: any options passed in to the call that triggered the invalid event

READY string ready Triggered when all pending promises from Collection API calls have been resolved

The event passes these arguments to the handler:

    collection: the collection on which the promises have been resolved

REFRESH string refresh Triggered when a collection is refreshed (see Collection.refresh)

The event passes these arguments to the handler:

    collection: the collection being refreshed
    options: any options passed in to the refresh call

REMOVE string remove Triggered when a model is removed from a collection

The event passes these arguments to the handler:

    model: the model being removed from the collection
    collection: the collection from which the model was removed
    options: index: the index of the model being removed

REQUEST string request Triggered when a model or collection has sent a request to the data service

The event passes these arguments to the handler:

    collection or model: the collection or model triggering the request
    xhr: the xhr argument for the request
    options: any options passed as part of the request

RESET string reset Triggered when a collection is reset (see Collection.reset)

The event passes these arguments to the handler:

    collection: the collection being reset
    options: any options passed in to the reset call

SORT string sort Triggered when a collection is sorted. If the second argument to the callback is set (options) and 'add' is true, it means this sort event was triggered as a result of an add

The event passes these arguments to the handler:

    collection: the collection being sorted
    options: add: true if this sort event was triggered as the result of an add call, undefined or false if not

SYNC string sync Triggered when a model or collection has been updated from the data service

The event passes these arguments to the handler:

    collection or model: the collection or model that triggered the update
    response: the response object from the data service
    options: any options passed in to the call that triggered the update

attributes :Object

Attribute/value pairs in the model.
Since:
  • 1.0.0

customURL :(function(string, Model, Object): (string|Object|null)|null)

A callback to allow users to completely customize the data service URLs The callback should accept these parameters:

operation (string): one of "create", "read", "update", "patch", or "delete", indicating the type of operation for which to return the URL
model (Object): the Model object requesting the URL
options (Object): one or more of the following properties:

    recordID: id of the record involved, if relevant
customURL callbacks should return either: null, in which case the default will be used; a url string, which will be used with the standard HTTP method for the type of operation, or an Object with with any other attributes that should be passed to the ajax call.
This object must at minimum include the URL, and other attributes as follows:
    url: giving the custom URL string
    type: (optional) a string indicating the type of HTTP method to use (GET, POST, DELETE, etc.)
    (other): (optional) any other ajax attributes to pass in the ajax call

Since:
  • 1.0.0

defaults :Object

The set of attribute/value pairs that serve as default values when new Model objects are created.
Since:
  • 1.0.0

id :string|null

The model's unique ID. This can be set by the application or retrieved from the data service. This ID will be appended to the URL for single-record data operations (update, delete).
Since:
  • 1.0.0

idAttribute :string|null

The name of the model property to be used as the unique ID. See id. This defaults to a value of "id".
Since:
  • 1.0.0

omitLanguageHeader :boolean

If true, do not insert the JET locale-based Accept-Language header. If false, let the Ajax system set the header.
Since:
  • 5.0.0

parse :function(Object):Object

Optional callback to parse responses from the server. It is called with the server's response with a model's data and should return a response (possibly modified) for processing
Since:
  • 1.0.0

parseSave :function(Object):Object

Callback function when writing a model to the server
Since:
  • 1.0.0

urlRoot :string|null

The base url on the data service used to perform CRUD operations on models. If not defined, the model will look to its collection. One or the other must be defined before CRUD operations can succeed.
Since:
  • 1.0.0

validate :(function(Object, Object): (string|Object|null)|null)

A callback to allow optional custom validation of model attributes during save, set, etc. The callback should accept these parameters:

attributes (Object): the attributes to validation
options (Object): the options passed in to the model call making the validation check
The validate callback should return nothing if the attributes are valid, or an error string or object if the validation fails

Since:
  • 2.3.0

validationError :string|Object|null

The last value returned from a validate callback
Since:
  • 2.3.0

Methods

(static) extend(properties, classProperties) : {any}

Create a new, specific type of model object to represent single records from a JSON data set.
This:
Parameters:
Name Type Argument Description
properties {parse?: (data: any)=> any, parseSave?: (data: any)=> any, urlRoot?: string, initialize?: (models: Array<Model>, options: object)=> void, validate?: null | object | string | ((attributes: object, options?: Model)=> number), [propName: string]: any} <optional>
 Properties for the new Model class.
defaults: an Object containing starting attribute/value pairs for some or all of the model's potential attributes
parse: a user callback function to allow parsing of JSON record objects as they are returned from the data service
parseSave: a user callback function to allow conversion of models back into a format appropriate for the data service on save calls
urlRoot: the URL to use to get records from the data service in the abscence of a collection (when an id is appended)
initialize: a user callback function to be called when this model is created
validate: a user callback function that will be called before a save to the data service occurs. The callback is passed the current set of attributes and save options.
classProperties Object <optional>
 properties that attach to the whole class
Since:
  • 1.0.0
Returns:

new Model object

Type
any

changedAttributes(attributes) : {Object|boolean}

Return the set of attributes and values that have changed since the last set. Note that a Model.fetch() uses set to store the returned attribute data. If attribute/value pairs are passed in, check those to see if they're different than the model. Return false if there were no changes
Parameters:
Name Type Argument Description
attributes Object <optional>
 One or more attribute/value pairs to check against the model for changes
Since:
  • 1.0.0
Returns:

the set of all attribute value pairs that have changed since last set, if no attributes passed in; the set of all attribute value pairs that are different than those listed in the attributes parameter, if present. False if no changes

Type
Object | boolean

clear(options) : {Model|boolean}

Clears all attributes from the model
Events:

    change:attr: fired for each attribute cleared, passing the model, name of the changed property, and options
    change:all: fired after all attributes have been cleaered, passing the model and options

Parameters:
Name Type Argument Description
options Object <optional>
Properties:
Name Type Argument Description
silent boolean <optional>
 if true, do not fire events
validate boolean <optional>
 if true, validate the unsetting of all properties
Since:
  • 1.0.0
Returns:

the model, or false if validation on clear fails

Type
Model | boolean

clone : {Model}

Return a copy of the model with identical attributes and settings
Since:
  • 1.0.0
Returns:

copy of the model

Type
Model

destroy(options) : {boolean}

Delete the record represented by this model object from the data service. If the server responds with virtual mode response properties (such as totalResults), these will be picked up at the end of the delete by the model's collection. Note that by default, the delete isn't sent with an HTTP data type so the object returning these properties needs to be a string version of the JSON object.
Events:

    destroy: fired when the model is destroyed, either before or after the server call, depending on the setting of wait. The model and model's collection are passed in
    request: fired right as the call is made to request the server delete the model. Passes the model, xhr ajax object, and options.
    sync: fired after the server succeeds in destroying the model. Passes the model, the raw response data, and options.

Parameters:
Name Type Argument Description
options {success?: (model: Model, response: any, options: object)=> void, error?: (model: Model, xhr: any, options: object)=> void, wait?: boolean, [propName: string]: any} <optional>
 Options for the destroy operation:
wait: if true, wait until the server is done to fire the destroy event. Otherewise, fire immediately and regardless of success or failure
success: callback function called if the server call succeeds, passing the model, response data, and options
error: callback function on failure of the server call, firing an error event and passing the model, xhr, status, and error values.
Since:
  • 1.0.0
Returns:
Type
boolean

fetch(options) : {Object}

Loads the Model object from the data service URL. Performs a data "read."
Events:

    request: fired when the request to fetch is going to the server, passing the model, xhr object, and options
    sync: fired when the model is fetched from the data service, passing the model and the raw response
    error: fired if there is an error during the fetch, passing the model, xhr ajax object, and options

Parameters:
Name Type Argument Description
options {success?: (model: Model, response: any, options: object)=> void, error?: (model: Model, error: any, options: object, xhr: any, status: any)=> void, [propName: string]: any} <optional>
 Options to control fetch

success: a user callback called when the fetch has completed successfully. This makes the fetch an asynchronous process. The callback is called passing the Model object, raw response, and the fetch options argument.

error: a user callback function called if the fetch fails. The callback is called passing the model object, error, options, xhr, and status.
Since:
  • 1.0.0
Returns:

xhr ajax object, by default. If sync has been replaced, this would be the value returned by the custom implementation.

Type
Object

get(property) : {any}

Returns the value of a property from the model.
Parameters:
Name Type Description
property string Property to get from model
Since:
  • 1.0.0
Returns:

value of property

Type
any

has(property) : {boolean}

Determines if the Model has a certain property set, vs. undefined.
Parameters:
Name Type Description
property string Property to check for
Returns:

true if the model contains the given property, false if undefined.

Type
boolean

hasChanged(attribute) : {boolean}

Return true if the Model object has had any changes made to its values, or if any changes have been made to the optional attribute passed in.
Parameters:
Name Type Argument Description
attribute string <optional>
 attribute to check for changes
Since:
  • 1.0.0
Returns:

true if the Model object has had any changes since retrieval or last update at all (if no attributes parameter); true if the Model object has had changes to the passed-in attribute since retrieval or last update (if attribute parameter present).

Type
boolean

invert : {Object}

Return an array of value/attribute pairs found in the model
Since:
  • 1.0.0
Returns:

returns the model's value/attribute pairs as an array

Type
Object

isNew : {boolean}

Determines if this model object has been assigned an id value yet. This indicates whether or not the model's data has been saved to or fetched from the data service at any point.
Since:
  • 1.0.0
Returns:

true if the Model object has not had its id set yet, false if not.

Type
boolean

isValid : {boolean}

Check to see if the model is valid by running the validate callback, if it is set
Since:
  • 1.0.0
Returns:

true if validate passes or if no validate callback

Type
boolean

keys : {Array.<Object>}

Return all of the model's attributes as an array
Since:
  • 1.0.0
Returns:

array of all the model's attributes

Type
Array.<Object>

listenTo(otherObj, eventType, callback) : {undefined}

Add an event handler for an event type to a second model or collection object ("otherObj"), but track it on the called object.
Parameters:
Name Type Description
otherObj Model | Collection Model or collection object on which to add this event handler.
eventType string Types of event handlers to add (may be a single event type or a space-delimited set of event types).
callback (context: Object, data?: any, data2?: any)=> void User's event handler callback function (called with the model or collection object and event specific values as parameters--the context will be the model or collection unless specified by context, below).
Since:
  • 1.0.0
Returns:
Type
undefined

listenToOnce(otherObj, eventType, callback) : {undefined}

Add an event handler for an event type to a second model or collection object ("otherObj"), but track it on the called object. Only fire once.
Parameters:
Name Type Description
otherObj Model | Collection Model or collection object on which to add this event handler.
eventType string Types of event handlers to add (may be a single event type or a space-delimited set of event types).
callback (context: Object, data?: any, data2?: any)=> void User's event handler callback function (called with the model or collection object and event specific values as parameters--the context will be the model or collection unless specified by context, below).
Since:
  • 1.0.0
Returns:
Type
undefined

matches(attrs) : {function(Model):boolean}

Return a function that determines if this model contains all of the property/values in attrs
Parameters:
Name Type Description
attrs Object property/value pairs
Since:
  • 1.1.0
Returns:

function taking an Model that returns true if all of attrs are contained within it

Type
function(Model):boolean

off(eventType, callback, context) : {undefined}

Remove an event handler for an event type from the model or collection object.
Parameters:
Name Type Argument Description
eventType string | Object <optional>
 Types of event handlers to remove (may be a single event type, a space-delimited set of event types, or a map of events to callbacks). If omitted, remove all event handlers.
callback (context: object, data?: any, data2?: any)=> void <optional>
 If provided, remove handlers only for eventType events with the given callback function.
context Object <optional>
 If provided, remove handlers only for eventType events with the given callback function and context object.
Since:
  • 1.0.0
Returns:
Type
undefined

omit(keys) : {Object}

Return attribute/value pairs for the model minus those attributes listed in keys
Parameters:
Name Type Description
keys Array.<Object> | Object keys to exclude from the returned attribute/value pairs
Since:
  • 1.0.0
Returns:

array of the model's attribute/value pairs except those listed in keys

Type
Object

on(eventType, callback, context) : {undefined}

Add an event handler for an event type to the model or collection object.
Parameters:
Name Type Argument Description
eventType string | Object Types of event handlers to add (may be a single event type, a space-delimited set of event types, or an object mapping events to callbacks).
callback (context: Object, data?: any, data2?: any)=> void User's event handler callback function (called with the model or collection object and event specific values as parameters--the context will be the model or collection unless specified by context, below).
context Object <optional>
 A context for the event
Since:
  • 1.0.0
Returns:
Type
undefined

once(eventType, callback, context) : {undefined}

Add an event handler for an event type to the model or collection object, but only fire it once, then remove it from the list of handlers.
Parameters:
Name Type Argument Description
eventType string Types of event handlers to add (may be a single event type or a space-delimited set of event types).
callback (context: Object, data?: any, data2?: any)=> void User's event handler callback function (called with the model or collection object and event specific values as parameters--the context will be the model or collection unless specified by context, below).
context Object <optional>
 A context for the event
Since:
  • 1.0.0
Returns:
Type
undefined

pairs : {Array.<Object>}

Return an array of attributes/value pairs found in the model
Since:
  • 1.0.0
Returns:

returns the model's attribute/value pairs as an array

Type
Array.<Object>

pick(keys) : {Array.<Object>}

Return attribute/value pairs for the model for the keys
Parameters:
Name Type Description
keys Array.<Object> | Object keys for which to return attribute/value pairs
Since:
  • 1.0.0
Returns:

array of the model's attribute/value pairs filtered by keys

Type
Array.<Object>

previous(attr) : {Object}

Return the previous value of the given attribute, if any.
Parameters:
Name Type Description
attr string
Since:
  • 1.0.0
Returns:

previous value of attr, if any. If the attribute has not changed, returns undefined

Type
Object

previousAttributes : {Object}

Return a copy of the model's previously set attributes
Since:
  • 1.0.0
Returns:

a copy of the model's previous attributes

Type
Object

save(attributes, options) : {Object|boolean}

Saves the current Model object to the data service. Performs a data "update."
Events:

    change:attr: fired for each attribute changed, if passed in as part of the save: passing the model, name of the changed property, and options
    change:all: fired after all attributes have been set, if passed in as part of the save: passing the model and options
    request: fired when the request to save is going to the server, passing the model, xhr object, and options
    sync: fired when the model is saved to the data service, passing the model and the raw response
    error: fired if there is an error during the save, passing the model, xhr ajax object, and options

Parameters:
Name Type Argument Description
attributes Object <optional>
 One or more attribute name/value pairs to set on the model before the save.
options {success?: (model: Model, response: any, options: object)=> void, error?: (model: Model, error: any, options: object, xhr: any, status: any)=> void, contentType?: string, valdiate?: boolean, wait?: boolean, patch?: boolean, attrs?: object, [propName: string]: any} <optional>
 Options to control save
success: a user callback called when the save has completed successfully. This makes the save an asynchronous process. The callback is called passing the Model object, response from the AJAX call, and the fetch options argument.

error: a user callback function called if the save fails.

contentType: in case the user's REST service requires a different POST content type than the default, 'application/json'

validate: should the validation routine be called if available

wait: if true, wait for the server call before setting the attributes on the model

patch: should only changed attributes be sent via a PATCH?

attrs: pass a set of attributes to completely control the set of attributes that are saved to the server (generally used with patch)

Since:
  • 1.0.0
Returns:

returns false if validation failed, or the xhr object

Type
Object | boolean

set(property, value, options) : {Model|boolean}

Set the value(s) of one or more attributes of the model, and fire events. Events:

    change:attr: fired for each attribute set, passing the model, name of the changed property, and options
    change:all: fired after all attributes have been set, passing the model and options

Parameters:
Name Type Argument Description
property string | Object Property attribute name to set, or an Object containing attribute/value pairs
value Object <optional>
 Value for property if property is not an Object containing attribute/value pairs
options Object <optional>
Properties:
Name Type Argument Description
silent boolean <optional>
 prevent events from firing
unset boolean <optional>
 delete all the properties passed in rather than setting them
Since:
  • 1.0.0
Returns:

the model itself, false if validation failed on set

Type
Model | boolean

stopListening(otherObj, eventType, callback) : {undefined}

Remove event handlers from a model or collection object. If the arguments are omitted, removes all event handlers from the model or collection.
Parameters:
Name Type Argument Description
otherObj Model | Collection If specified, remove event handlers that target otherObj from this model or collection.
eventType string <optional>
 If specified, remove the event handlers for the given event types from this model or collection
callback (context: Object, data?: any, data2?: any)=> void <optional>
 If specified, remove event handlers that call the given user callback function from this model or collection
Since:
  • 1.0.0
Returns:
Type
undefined

sync(method, model, options) : {Object}

Parameters:
Name Type Argument Description
method string "create", "read", "update", or "delete"
model Model Model to be read/saved/deleted/created
options Object <optional>
 to control sync:
success: called if sync succeeds:
    For create, called with the response (attribute/value pairs); status (Ajax by default, but user-defined); xhr object (Ajax--if available)
    For read, called with the response (attribute/value pairs being fetched)
    For update, same as create
    For delete, called with the Model deleted, the data response (ignored), and the options passed to the destroy call
error: called if sync fails. Called with xhr, status, and error info, per jQuery Ajax (all if available)
Since:
  • 1.0.0
Returns:

xhr object

Type
Object

toJSON : {Object}

Return a copy of Model's current attribute/value pairs
Since:
  • 1.0.0
Returns:

a copy of the Model's current set of attribute/value pairs.

Type
Object

trigger(eventType) : {undefined}

Fire the given event type(s) for all registered handlers.
Parameters:
Name Type Description
eventType string Types of event handlers to fire (may be a single event type or a space-delimited set of event types).
Since:
  • 1.0.0
Returns:
Type
undefined

unset(property, options) : {boolean}

Deletes the given property from the model.
Events:

    change:attr: fired for each attribute unset: passing the model, name of the changed property, and options
    change:all: fired after all attributes have been unset: passing the model and options

Parameters:
Name Type Argument Description
property string Property to remove from model
options Object <optional>
Properties:
Name Type Argument Description
silent boolean <optional>
 do not fire change events if true
Since:
  • 1.0.0
Returns:

false if validation of the unset fails

Type
boolean

url : {string|null}

Return the URL used to access this model in the data source
Since:
  • 1.0.0
Returns:

url to access this model in the data source

Type
string | null

values : {Array.<Object>}

Return all of the model's attributes values as an array
Since:
  • 1.0.0
Returns:

array of all the model's attributes values

Type
Array.<Object>

Type Definitions

CustomURLCallbackOptions

Properties:
Name Type Argument Description
recordID string <optional>
 id of the record involved, if relevant