Document how to parameterize collections

[Conny Brunnkvist]

Let's say I have multiple categories on my blog, each identified by its key in the URL e.g. /articles/category/cooking. So the method declaration for this could be:

api.config({
        url : Alloy.CFG.apiRoot,
        methods : [{
            name : 'getCategoryArticles',
            get : '/articles/category/<category_key>'
        }],
        models : [{
            name : "Article",
            id : "id",
            collections : [{
                name : "CategoryArticles",
                content : "articles",
                read : "getCategoryArticles"
            }],
        }]
});

Now I have to pass in the key for the category when I ask to update the collection somehow. This can currently be achieved by passing the parameter of the "read" method as part of the fetch call as follows:

Alloy.Collections.CategoryArticles.fetch({
    category_key: 'cooking'
});

...but it seems to be a bit undocumented, it works, but I would like to know if this is an intentional feature and if so, I think we should document that use case somehow because it is arguable a very common pattern. 📜

[Jason Kneen]

That's a correct pattern - anything for get, put methods that use parameters in the URL can be replaced with this method, with the "body" property used if you to submit properties as a body object.

What you're doing here is correct.

[Jason Kneen]

added an example.