Docs

Everything You Need to Know

Models

API

Truck Tank

Model

$.Model(options)

This is a factor that creates a model object for you based on the options you provide. It takes two arguments, the data to encapsule in the model, and a handle to use as its identifier. The model uses the handle to inform the system when it has changed. Mediators listen for this handle and react when it is dispatched. Models can hold either an object of key-value paris, or a colleciton of objects. Depending on the contents, different methods will work. Colleciton methods will not work with an object and object methods will not work with a collection. But some methods work for both. Therefore check the explanation of each method below to see what type of data they work with.

After putting your data in a model, you can dispose of it if you want to free up memory:

// Create a new model:
var MyModel = $.Model(myData, 'mydata-handle');
// Set the data for garbage colleciton:
myData = null;

size

size()

If the model is collection, this will return the current number of items in the collection. If the data is an object, it will return undefined.

MyModel.size();

eq

eq(number)

If the model is a collection, this method allows you to get a collection item by its position in the collection. The numbering is zero-based like arrays.

MyModel.eq();

getProp

getProp(prop)

This method allows you to get a property's value in a model's object. This does not work with collections.

// Get the `name` property of an object in the model:
var name = MyModel.getProp('name');

setProp

setProp(prop, value, doNotPropogate)

This method lets you set the value of a property in a model's object data. If the property does not exist, it will be added.

If you provide a boolean true for the last argument, the model will not dispatch its change to the system, meaning that any mediators listening to the model's handle will not react.

// Set the name property in the model:
MyModel.setProp('name', 'John Doe');

setObject

setObject(obj, doNotPropogate)

This method lets you replace the object that a model holds with a completely different one. Simply provide the object you want to be the new content of the model as the argument for this method:

var newData = {
  name: 'Joe Bodoni',
  age: 32,
  job: 'brain surgeon'
}
// Set the data of the model to 
// the above data.
MyModel.setObject(newData);

// Same as above, but without propagating change:
MyModel.setObject(newData, true);

If you provide a second boolean true as the final parameter, the model will not dispatch its change to the system, meaning that any mediators listening to the model's handle will not react.

push

push(data, doNotPropogate)

If the model holds a collection, this method lets you push new data onto the collection. Of course you can push whatever kind of data you want onto a collection. But it makes sense to push data that matches the collection in format and structure.

This method works like push on arrays.

// Push a new object onto the collection.
MyModel.push({firstName: 'John', lastName: 'Doe', job: 'brain surgeon'});

// Don't propagate the change:
MyModel.push({firstName: 'John', lastName: 'Doe', job: 'brain surgeon'}, true);

pop

pop(doNotPropogate)

This method pops the last item off of a collection. That means the collection is now one item shorter.

var lastItem = MyModel.pop();
console.log(lastItem.name);

// Don't propagate the change:
var newLastItem = MyModel.pop(true);

If you provide a boolean true as a parameter, the model will not dispatch its change to the system, meaning that any mediators listening to the model's handle will not react.

unshift

unshift(data, doNotPropogate)

This method lets you add an item at the begining of a model's collection, just like unshift on arrays.

MyModel.unshift({firstName: 'Tom', lastName: 'Doe', job: 'Clown'});

If you provide a second boolean true as a parameter, the model will not dispatch its change to the system, meaning that any mediators listening to the model's handle will not react.

// Don't propagate the change:
MyModel.unshift({firstName: 'Tom', lastName: 'Doe', job: 'Clown'}) true;

shift

shift(doNotPropogate)

If the model holds a collection, this method lets you remove a item from the front of the collection, just like shift on an array.

var firstItem = MyModel.shift();

// Don't propagate the change:
var secondItem = MyModel.shift(true);

concat

concat(data, doNotPropogate)

This method lets you concatanate another collection to a model. If you provide a second boolean true as a parameter, the model will not dispatch its change to the system, meaning that any mediators listening to the model's handle will not react.

MyModel.concat(myArray);

// Don't propagate the change:
MyModel.concat(myArray2, true);

insert

insert(position, data, doNotPropogate)

This method lets you insert data at a specified index in a model's collection. The first argument is the position. This is zero-based. The second argument is the data to insert. Optionally you can provide a boolean true to tell the model not to dispatch its change.

MyModel.insert(20, {firstName: 'Suzy', lastName: 'Cue', job: 'CEO'});

// Don't propagate the change:
MyModel.insert(20, {firstName: 'Suzy', lastName: 'Cue', job: 'CEO'}, true);

unique

unique(doNotPropogate)

This method lets you eliminate any duplicates in your collections. By providing a boolean true parameter, you can tell the model not to propagate its change.

MyModel.unique();

// Don't propagate the change:
MyModel.unique(true);

index

index(prop, value)

Get the index of an object based on a property and value. This returns the first match.

var objectPos = MyModel.index('firstName', 'Joe');

filter

filter(args)

This method allows you to run a filter callback on the model's collection. This works the same as filter on an array:

// Function to filter model objects by id:
var filterModel = function(id) {
  var whichPerson = MyModel.filter(function(person) {
    return person.guid === id;
  });
  console.log(whichPerson.name);
};
// Get object with this id:
filterModel('asd234asd241');

map

map(args)

This method lets you map a function to every item in the model's collection. This works like map on an array:

MyModel.map(function(person) {
  console.log(person.name);
});

pluck

pluck(property)

This method lets you get the value of a property from every object in a collection. This returns an array of the values found. If no property was found, it will return an empty array.

var allNames = MyModel.pluck('name');

sort

sort

MyModel.sort();

reverse

reverse()

This method reverse the order of items in a model's collection.

MyModel.reverse();

sortBy

sortBy(props)

This method lets you sort a model's collection by the provided properties. You can sort by one property or more. Sorting will be in the order of provided properties. For example, you could sort a collection by last name, first name, age and income.

MyModel.sortBy('lastName', 'firstName');

delete

delete(data, doNotPropogate)

This method lets you delete either an object property, if you provide a property, or a collection's object if you provide an index position. To delete an object from a collection, the number must be zero-based, like with arrays.

// Delete property from model's object:
MyModel.delete('firstName');

// Delete 10th object from model's collection:
MyModel.delete(9);

This method lets you concatanate another collection to a model. If you provide a second boolean true as a parameter, the model will not dispatch its change to the system, meaning that any mediators listening to the model's handle will not react.

run

run(callback)

This method lets you run a function on the model. Differs from map in that it does not run on each index of the collection. The callback has access to the model and the model's data.

MyModel.run(function(model, data) {
  var names = model.pluck('name');
  names.forEach(function(name) {
    console.log(name);
  });
  data.forEach(function(job) {
    console.log(job);
  });
});

poke

poke()

As you may have noticed, it's possible to modify a model and tell it not to dispatch its changeds. This is useful where you have a view or views bound to a model and you want to make a number of changes. After you have made all those changes, you can get the model to dispatch its final state by `poking` it with this method, so that mediators can update their views:

// Tell the model to dispatch its current state:
MyModel.poke();

getHandle

getHandle()

This method lets you find out what handle a model is using.

MyModel.getHandle();

setHandle

setHandle(handle)

Sometimes you might want to change the handle a model is using so that another mediator can intercept the model's changes. You can do that using this method:

MyModel.setHandle('a-different-handle');

purge

purge()

This method lets you set the model's data to empty. If the model's data is an object, it will be set to {}. If it's a collection, it will get set to [].

MyModel.purge();

hasData

hasData()

This method lets you check to see if the model contains any data. It returns a boolean true/false.

MyModel.hasData();

getType

getType

This method lets you check what kind of data a model holds. If its and object, it returns 'object'. If its a collection, it returns 'array'.

if (MyModel.getType() === 'array') {
  console.log('This model holds a colleciton.')
}

isIterable

isIterable()

This method lets you determine whether the data that a model holds is iterable. This returns a boolean true/false.

if (MyModel.isIterable()) {
  MyModel.forEach(function(item) {
    console.log(item.name + ': ' + item.price);
  });
}

forEach

forEach(callback)

This method lets you run a function that iterates over each item in a model's collection. This works like foreach on an array.

MyModel.forEach(function(item) {
  console.log(item.name);
});

getData

getData()

This method returns the data that a model holds.

// Get the data in a model:
var items = MyModel.getData();

setItemProp

setItemProp(index, prop, value, doNotPropogate)

This method lets you set the value of a property on an object in a collection. The first argument is the index for the object in the collection. The second argument is the property whose value you want to set. If this property does not exist on the object at that index, this will create it. The third argument is the value for the property. And optional fourth value is a boolean true, which tells the model not to dispatch its changes to the system.

MyModel.setItemProp(23, 'price', '300.00');

// Tell the model not to dispatch the changes:
MyModel.setItemProp(23, 'price', '300.00', true);

getItemProp

getItemProp(index, prop)

// Get the name property from
// object at position 15:
MyModel.getItemProp(14, 'name');

deleteItemProp

deleteItemProp(index, prop, doNotPropogate)

This method lets you delete a property from an object in a model's colleciton. The first argument is the index for the object. The second is the property to delete. Optionally you can provide a third boolean true argument to prevent the model from dispatching its changes to the system.

// Delete name off of object at position: 27:
MyModel.deleteItemProp(26, 'name');

getLastModTime

getLastModTime()

This method lets you get the last time a model was modified. If the model has never been modified, it will return undefined.

var modTime = MyModel.getLastModTime();

isBoxed

isBoxed()

This method lets you check to see if a model is Boxed. It returns a boolean true/false.

var boxed = MyModel.isBoxed();

isAutoBoxed

isAutoBoxed()

This method lets you check to see if a model is set to auto box when it changes. It returns a boolean true/false.

var autoBoxed = MyModel.isAutoBoxed();

getLastBoxTime

getLastBoxTime()

This method lets you get the last time that a model was boxed. If it was not boxed, it returns undefined.

var lastTimeStored = MyModel.getLastBoxTime();