Class: Model

Oracle® JavaScript Extension Toolkit (JET)
3.2.0

E87541-01

QuickNav

Fields

oj. Model

Version:
  • 3.2.0
Object representing name/value pairs for a data service record

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
Source:

Mixes In

Fields

attributes :Object

Attribute/value pairs in the model.
Source:

customURL :function(string,Object):(string|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 oj.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

Source:

defaults :Object

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

id :String

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).
Source:

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".
Source:

urlRoot :String

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.
Source:

validate :function(Object,Object)|(string|Object|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

Source:

validationError :string|Object|null

The last value returned from a validate callback
Source:

Methods

<static> extend(properties, classProperties) → {function(new:Object, ...)}

Create a new, specific type of model object to represent single records from a JSON data set.
This:
  • {oj.Model}
Parameters:
Name Type Argument Description
properties Object <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
Source:
Returns:
new Model object
Type
function(new:Object, ...)

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
Source:
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) → {Object|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>
silent: if true, do not fire events
validate: if true, validate the unsetting of all properties
Source:
Returns:
the model, or false if validation on clear fails
Type
Object | boolean

clone() → {Object}

Return a copy of the model with identical attributes and settings
Source:
Returns:
copy of the model
Type
Object

destroy(options)

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 Object <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.
Source:

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 Object <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, xhr, and options arguments.

Source:
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) → {Object}

Returns the value of a property from the model.
Parameters:
Name Type Description
property string Property to get from model
Source:
Returns:
value of property
Type
Object

has(property) → {boolean}

Determines if the Model has a certain property set, vs. undefined.
Parameters:
Name Type Description
property string Property to check for
Source:
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 set of attributes passed in.
Parameters:
Name Type Argument Description
attribute Array <optional>
One or more attributes to check for changes
Source:
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 one or more of the passed-in attributes since retrieval or last update (if attributes parameter present).
Type
boolean

invert() → {Object}

Return an array of value/attribute pairs found in the model
Source:
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.
Source:
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
Source:
Returns:
true if validate passes or if no validate callback
Type
boolean

keys() → {Array}

Return all of the model's attributes as an array
Source:
Returns:
array of all the model's attributes
Type
Array

matches(attrs) → {function(Object)}

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
Source:
Returns:
function taking an oj.Model that returns true if all of attrs are contained within it
Type
function(Object)

omit(keys) → {Object}

Return attribute/value pairs for the model minus those attributes listed in keys
Parameters:
Name Type Description
keys Array | Object keys to exclude from the returned attribute/value pairs
Source:
Returns:
array of the model's attribute/value pairs except those listed in keys
Type
Object

pairs() → {Object}

Return an array of attributes/value pairs found in the model
Source:
Returns:
returns the model's attribute/value pairs as an array
Type
Object

pick(keys) → {Object}

Return attribute/value pairs for the model for the keys
Parameters:
Name Type Description
keys Array | Object keys for which to return attribute/value pairs
Source:
Returns:
array of the model's attribute/value pairs filtered by keys
Type
Object

previous(attr) → {Object}

Return the previous value of the given attribute, if any.
Parameters:
Name Type Description
attr string
Source:
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
Source:
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 Object <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)

Source:
Returns:
returns false if validation failed
Type
Object | boolean

set(property, value, options) → {Object|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>
Options:
silent: prevent events from firing
unset: delete all the properties passed in rather than setting them
Source:
Returns:
the model itself, false if validation failed on set
Type
Object | boolean

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

Parameters:
Name Type Argument Description
method string "create", "read", "update", or "delete"
model Object 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 oj.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)

Source:
Returns:
xhr object
Type
Object

toJSON() → {Object}

Return a copy of Model's current attribute/value pairs
Source:
Returns:
a copy of the Model's current set of attribute/value pairs.
Type
Object

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>

silent: do not fire change events if true
Source:
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
Source:
Returns:
url to access this model in the data source
Type
string | null

values() → {Array}

Return all of the model's attributes values as an array
Source:
Returns:
array of all the model's attributes values
Type
Array