Docs

Everything You Need to Know

Tutorials

Models

More Than Just Data

ChocolateChip-UI's models provide several things. First and foremost is encapsulation and abstraction. This allows us to isolate your data from accidental modification. It also enable's us to add capabilities for your data without having to register events, getters and setters or other intrusive operations. At the end of the day, the data you put in a ChocolateChip-UI model is clean and untouched. You can extract it from the model at any time.

// Data for model:
var person = {
  firstName: 'John',
  lastName: 'Doe',
  age: 32,
  job: 'developer'
};

// Define model:
var personModel = $.Model(person, 'person-model');

Models expose a lot of useful methods to handle your data. You can find out about them in the section about Model API. Since the model we create above holds an object, we can use any of the model's object methods on it to change the data. But first lets create a view that we can bind to this object:

<li id='person'>
  <div>
    <h3>${ person.firstName } ${ person.lastName }</h3>
    <h4>${ person.age }</h4>
    </p>${ person.job }</p>
  </div>
</li>

<script>
// Define a view:
var PersonView = $.View({
  element: '#person',
  // Bind view to model:
  model: personModel
});
PersonView.render();
</script>

Because we've bound the view to the person model, when we render the view, it does so with the data from the model. From now on, when we make any changes to the model, when we render the view, it will automatically get the latest version of the data.

When a model holds an object, we have object related methods that we can use. For example, we can query a property on the model with getProp. So, with the above model, we can get the firstName doing:

var firstName = PersonView.getProp('firstName');

Getting a property does not change a model, and so there will be no change in its bound view. But if we change a property, it will:

PersonView.setProp('firstName', 'Tom');

By changing the property on our model, we cause the model to notify the dispatch receiver, which in turn re-renders the view with the first name "Tom". Besides updating a property value on the model, we could add a new property using the same method. This would also trigger a re-render of the view. Note that if the property is not in the template, it won't get output. That said, it is possible to update a view's template to accomodate changing data needs.

You can also delete a model's property. Say, we want to delete the age property. We can do the following:

PersonView.remove('age');

Collections

Not all models hold objects. In fact, most models will hold arrays of objects. When you create a model from an array, you have a whole range of methods to access the objects in the array. When you bind a array model to a view, the view renders its template for each object in the array.

Earlier we made a person object. Now we're going to make an array of person objects and turn it into model:

var people = [
  {
    firstName: 'John',
    lastName: 'Doe',
    age: 32,
    job: 'developer'
  },
  {
    firstName: 'Sam',
    lastName: 'Smith',
    age: 28,
    job: 'mechanic'
  },
  // etc.
];

// Make a collection model:
var PeopleModel = $.Model(people, 'people-handle');

// Bind this model to our person view:
var PersonView = $.View({
  element: '#person',
  // Bind view to collection model:
  model: PeopleModel
});
PersonView.render();

This will result in a list of two persons being rendered by the view. Now if we modify the model, the list will update automatically. Collection models support the same types of methods as arrays: push, pop, unshift, shift, sort, reverse, etc. Any of the methods that modify the model will alert the view's dispatch receiver that it has changed. And the receiver will then update the view. If we push or pop an item to the model, the list will update without us having to write any DOM manipulation code.

// Push another person object:
PeopleModel.push({
  firstName: 'Sally',
  lastName: 'Daniels',
  age: 27,
  job: 'entrepreneur'
});
// The view bound to PeopleModel
// will automatically update.

When Not To Use

Just because you can put data in a model doesn't mean you should. If your data is of a temporary nature, or is extremely simple, don't bother putting it in a model. If you need to perform multiple operations on the data in rapid succession, leave it raw JavaScript. You'll get better performance. However, there may be times where the array model methods make it trivial for you to accomplish complex tasks. In that case, use a model.

To learn more about collection model methods, please consult the documentation.