Models are used to supply data to your application. The
data usually comes from an external API that the models execute
calls to. Because querying data from an external API happens
asynchronously, you will need to supply a callback
function whenever you make a call to a model method from a
controller.
Calling your model methods from controllers
First you need to create (add) a model, and then call its
methods from controller(s). Let's assume you have added a model
called article. Here's an example on how to call the
articleModel's method getArticles:
$models.article.getArticles({ some: 'parameters' },
function(response) {
// do something with the response that the model gave
});
Example on how to add a model is described below and is also
present in the demo application bundled with the Maverick
framework. In addition to calling your model methods from
controllers, you may optionally also call them from views (but it
is not recommended).
Public functions for handling models and model methods
$models.add()
Adds (creates) a model, instantiates it and exposes its
methods via models.[modelName].[methodName].
Arguments: [string] modelName, [function] constructor,
[object] methods
$models.add('article',
function() {}, {
getArticles: function(params, callback) {
$.getJSON('/articles.json', callback);
},
getArticleTypes: function(params, callback) {
$.getJSON('/articleType.json', callback);
}
});
In the example above, we create (add) a new model called
article. As you can see, each model can have multiple
methods — usually for fetching different types of data. In the
example above, we create (add) a model that has two methods:
getArticles and getArticleTypes. The first will
retrieve articles from a JSON file in the server and pass the
response to a callback function provided from the controller. The
second will retrieve articleTypes from a JSON file in the server
and again pass the response to a callback function in a similar
manner.
$models.getMany()
Queries
multiple models/methods and after all models have replied executes
a single callback function that receives data from all queried
models/methods.
Arguments: [function]
models.[modelName].[modelMethod]([mixed] params), [function]
models.[modelName].[modelMethod]([mixed] params), [function]
models.[modelName].[modelMethod]([mixed] params), ..., [function]
callback([mixed] params, [mixed] params, 2...)
$models.getMany(
$models.article.getArticles({ some: 'arguments' }),
$models.author.getAuthors({ some: 'other arguments' }),
$models.comment.getComments({ some: 'more arguments' }),
function(articles, authors, comments) {
// do something with the received data
});
As mentioned earlier,
querying data from external APIs happens asynchronously, and because it is often the
case that a single controller must fetch data from multiple sources
(model methods) before actually carrying on with actions, the
$models.getMany method kicks in. The $models.getMany
is a tricky method that allows you to fetch data from multiple
model methods simultaneously by passing a single callback function
that is only executed once all the model methods have replied their
data.
In the example above, we query three different model methods
($models.article.getArticles,
$models.author.getAuthors and
$models.comment.getComments)
and provide a single in-line callback function that is executed
after the data from all three models have been received.
Handling responses with models.getMany()
The responses from the models are gathered and provided to the
callback function as objects. For example, if the getArticles
method provides multiple arguments in its response, all those
arguments are grouped into an object. The same goes for all model
method calls. Responses from each method end up as objects in the
same order as provided to the final callback function.