Model

Models are the basic data object in JointJS. They are a discrete chunk of data and a bunch of useful, related methods for performing computations and transformations on that data. dia.Cell extends mvc.Model.

Properties

attributes

model.attributes

The attributes property is the internal hash containing the model's state. Please use set() to update the attributes instead of modifying them directly.

Due to the fact that Events accepts space separated lists of events, attribute names should not include spaces.

changed

model.changed

The changed property is the internal hash containing all the attributes that have changed since its last set(). Please do not update changed directly since its state is internally maintained by set(). A copy of changed can be acquired from changedAttributes.

cid

model.cid

A special property of models, the cid or client id is a unique identifier automatically assigned to all models when they're first created.

cidPrefix

model.cidPrefix

If your model has an id that is anything other than an integer or a UUID, there is the possibility that it might collide with its cid. To prevent this, you can override the prefix that cids start with.

id

model.id

A special property of models, the id is an arbitrary string (integer id or UUID). If you set the id in the attributes hash, it will be copied onto the model as a direct property. model.id should not be manipulated directly, it should be modified only via model.set('id', …).

idAttribute

model.idAttribute

A model's unique identifier is stored under the id attribute. If you're directly communicating with a backend (MongoDB) that uses a different unique key, you may set a Model's idAttribute to transparently map from that key to id. If you set idAttribute, you may also want to override cidPrefix.

const Shape = mvc.Model.extend({
    idAttribute: "_id"
});

const shape = new Shape({ _id: 1, name: "Rectangle" });
console.log("Shape id: " + shape.id); // Shape id: 1

validationError

model.validationError

The value returned by validate during the last failed validation.

Methods

changedAttributes()

model.changedAttributes([attributes])

Retrieve a hash of only the model's attributes that have changed since the last set(), or false if there are none. Optionally, an external attributes hash can be passed in, returning the attributes in that hash which differ from the model. This can be used to figure out which portions of a view should be updated.

clear()

model.clear([options])

Removes all attributes from the model, including the idattribute. Fires a "change" event unless silent is passed as an option.

clone()

model.clone()

Returns a new instance of the model with identical attributes.

defaults()

model.defaults or model.defaults()

The defaults hash (or function) can be used to specify the default attributes for your model. When creating an instance of the model, any unspecified attributes will be set to their default value.

Remember that in JavaScript, objects are passed by reference, so if you include an object as a default value, it will be shared among all instances. Instead, define defaults as a function.

extend()

mvc.Model.extend(properties, [classProperties])

To create a Model class of your own, you can extend mvc.Model. Provide instance properties, and optional classProperties to be attached directly to the constructor function.

extend correctly sets up the prototype chain, so subclasses created with extend can be further extended and subclassed.

const BaseShape = mvc.Model.extend({
    initialize: function() {...}
});

const Shape = BaseShape.extend({...});

Brief aside on super: JavaScript does not provide a simple way to call super — the function of the same name defined higher on the prototype chain. If you override a core function like set, and you want to invoke the parent object's implementation, you'll have to explicitly call it, along these lines:

const Shape = mvc.Model.extend({
    set: function(attributes, options) {
        mvc.Model.prototype.set.apply(this, arguments);
        ...
    }
});

get()

model.get(attribute)

Get the current value of an attribute from the model. For example: model.get("title"). get() doesn't provide nesting capability in the form of a string. That means any path representation is considered to be one attribute.

has()

model.has(attribute)

Returns true if the attribute is set to a non-null or non-undefined value.

hasChanged()

model.hasChanged([attribute])

Has the model changed since its last set()? If an attribute is passed, returns true if that specific attribute has changed.

Note that this method is only useful during the course of a "change" event.

shape.on("change", function() {
    if (shape.hasChanged("title")) {
        ...
    }
});

initialize()

If the model defines an initialize function, it will be invoked when the model is created. Initialize is an empty function by default. Override it with your own initialization logic.

isValid()

model.isValid(options)

Run validate to check the model state. The validate method receives the model attributes as well as any options passed to isValid, if validate returns an error an "invalid" event is triggered, and the error is set on the model in the validationError property.

preinitialize()

For use with models as ES classes. If you define a preinitialize method, it will be invoked when the Model is first created, before any instantiation logic is run for the Model.

class BaseShape extends mvc.Model {
    preinitialize({ type }) {
        this.type = type;
    }

    initialize() {...}
}

previous()

model.previous(attribute)

During a "change" event, this method can be used to get the previous value of a changed attribute.

previousAttributes()

model.previousAttributes()

Return a copy of the model's previous attributes. Useful for getting a diff between versions of a model, or getting back to a valid state after an error occurs.

set()

model.set(attribute)

Set a hash of attributes (one or many) on the model. If any of the attributes change the model's state, a "change" event will be triggered on the model. set() doesn't provide nesting capability in the form of a string. That means any path representation is considered to be one attribute. You can find more information on managing model attributes for your shapes in the following learn section.

toJSON()

model.toJSON([options])

Return a shallow copy of the model's attributes object for JSON stringification. This can be used for persistance or serialization. Note that this method doesn't return a JSON string but rather an object that can be then serialized to JSON with JSON.stringify().

unset()

model.unset(attribute, [options])

Remove an attribute by deleting it from the internal attributes hash. Fires a "change" event unless silent is passed as an option.

validate()

model.validate(attributes, options)

This method is left undefined and you're encouraged to override it with any custom validation logic you have that can be performed in JavaScript. If the attributes are valid, don't return anything from validate; if they are invalid return an error of your choosing. It can be as simple as a string error message to be displayed, or a complete error object that describes the error programmatically.

It's possible to tell set() to validate the new attributes by passing { validate: true } as an option. The validate method receives the model attributes as well as any options passed to set(). "invalid" events are useful for providing coarse-grained error messages at the model or collection level.