`XM.Collection` is a standard class for querying the xTuple data source.
It should be subclassed for use with subclasses of `XM.Model` (which
themselves typically exist in the `XM` namespace). To create a new class,
simply extend `XM.Collection` and indicate the model to reference:
XM.MyCollection = XM.Collection.extend({
model: XM.MyModel
})
After your class is created, you can instantiate one and call `fetch` to
retrieve all records of that type.
var coll = new XM.MyCollection();
coll.fetch();
You can access the results on the `models` array.
coll.models;
You can specify options in fetch including `success` and `query` options.
The `success` option is the callback executed when `fetch` sucessfully
completes.
var options = {
success: function () {
console.log('Fetch completed!')
}
};
coll.fetch(options);
Use a query object to limit the result set. For example, this query will return results
with the first name 'Frank' and last name 'Farley':
var coll = new XM.ContactListItemCollection();
var options = {
query: {
parameters: [{
attribute: "firstName",
value: "Mike"
}, {
attribute: "lastName",
value: "Farley"
}]
}
};
coll.fetch(options);
The `query` object supports the following:
* parameters - Array of objects describing what to filter on.
Supports the following properties:
> attribute - The name of the attribute to filter on.
> operator - The operator to perform comparison on.
> value - The matching value.
> includeNull - "OR" include the row if the attribute is null irrespective
of whether the operator matches.
* orderBy - Array of objects designating sort order. Supports
the following properties:
> attribute - Attribute to sort by.
> descending - `Boolean` value. If false or absent sort ascending.
* rowLimit - Maximum rows to return.
* rowOffset - Result offset. Always use together with `orderBy`.
If no operator is provided in a parameter object, the default will be `=`.
Supported operators include:
- `=`
- `!=`
- `<`
- `<=`
- `>`
- `>=`
- `BEGINS_WITH` -- (checks if a string starts with another one)
- `ENDS_WITH` -- (checks if a string ends with another one)
- `MATCHES` -- (checks if a string is matched by a case insensitive regexp)
- `ANY` -- (checks if the number or text on the left is contained in the array
on the right)
- `NOT ANY` -- (checks if the number or text on the left is not contained in the array
on the right)
Examples
Example: Fetch the first 10 Contacts ordered by last name, then first name.
var coll = new XM.ContactListItemCollection();
var options = {
query: {
rowLimit: 10,
orderBy: [{
attribute: "lastName"
}, {
attribute: "firstName"
}]
}
};
coll.fetch(options);
Example: Fetch Contacts with 'Frank' in the name.
var coll = new XM.ContactListItemCollection();
var options = {
query: {
parameters:[{
attribute: "name",
operator: "MATCHES",
value: "Frank"
}],
}
};
coll.fetch(options);
Example: Fetch Accounts in Virginia ordering by Contact name descending. Note
support for querying object hierarchy paths.
var coll = new XM.AccountListItemCollection();
var options = {
query: {
parameters:[{
attribute: "primaryContact.address.state",
value: "VA"
}],
orderBy: [{
attribute: "primaryContact.name",
descending: true
}]
}
};
coll.fetch(options);
Example: Fetch Items with numbers starting with 'B'.
var coll = new XM.ItemListItemCollection();
var options = {
query: {
parameters:[{
attribute: "number",
operator: "BEGINS_WITH",
value: "B"
}]
}
};
coll.fetch(options);
Example: Fetch active To Do items due on or after July 17, 2009.
var coll = new XM.ToDoListItemCollection();
var dt = new Date();
dt.setMonth(7);
dt.setDate(17);
dt.setYear(2009);
var options = {
query: {
parameters:[{
attribute:"dueDate",
operator: ">=",
value: dt
}, {
attribute: "isActive",
value: true
}]
}
};
coll.fetch(options);
Example: Fetch contact(s) with an account number, account name, (contact) name,
phone, or city matching 'ttoys' and a first name beginning with 'M'. Note
an attribute array uses `OR` logic for comparison against all listed
attributes.
var coll = new XM.ContactListItemCollection();
var options = {
query: {
parameters:[{
attribute: ["account.number", "account.name", "name", "phone", "address.city"],
operator: "MATCHES",
value: "ttoys"
}, {
attribute: "firstName",
operator: "BEGINS_WITH",
value: "M"
}]
}
};
coll.fetch(options);