Class StorableCollection

Extends StorableObject.
StorableCollection is a way of grouping together many StorableObjects.
Defined in: <lib\storage.js>.

Class Summary
Constructor Attributes	Constructor Name and Description
	StorableCollection() A StorableCollection is a way of grouping together many StorableObjects.

Method Summary
Method Attributes	Method Name and Description
<static>	StorableCollection.add(obj) Adds a StorableObject to this collection.
<static>	StorableCollection.first() Gets the first object in this StorableCollection.
<static>	StorableCollection.forEach(f) Executes a function once on each member of this collection.
<static>	StorableCollection.limit(n) Returns a view consisting of the first `n` elements of this collection or view.
<static>	StorableCollection.remove(obj) Removes StorableObjects from this collection.
<static>	StorableCollection.reverse() Returns a view with the order of elements reversed.
<static>	StorableCollection.size() Returns the number of elements in a collection.
<static>	StorableCollection.skip(n) Returns a view that skips the first `n` elements of this collection or view.
<static>	StorableCollection.sort(compare) Returns a sorted view of this collection based on a sorting function, or by object creation date if no sorting function is given.
<static>	StorableCollection.sortBy(propertyName1, propertyName2, etc) Returns a sorted view of this collection based on a property name.

Class Detail

StorableCollection()

A StorableCollection is a way of grouping together many StorableObjects.

StorableObjects in a StorableCollection are not stored in any particular order, but you can use the sort or sortBy methods to access the objects in order. A collection usually contains objects of the same "type" in that they have a similar set of properties, but this is not strictly required.

If you are familiar with SQL databases, a StorableCollection provides much of the same functionality that a table provides in SQL, and you can think of each StorableObject in the collection as analogous to a row in a SQL table. Unlike SQL tables, StorableCollections do not have pre-defined columns. You can add StorableObjects with any properties you want.

After a StorableCollection is created, you add StorableObjects to it by calling StorableCollection.add(), as documented below.

StorableCollections are also StorableObjects. Therefore, each StorableCollection has an "id" property, and may be retreived with a call to getStorable(). Usually, however, StorableCollections are assigned to properties of the global storage object, as in the examples below.

import("storage");

// A collection of books
storage.books = new StorableCollection();

// Here we add a new StorableObject to the collection
storage.books.add(new StorableObject({title: "Shantaram", author: "Gregory David Roberts" }));

// If you call add with an object that is not a StorableObject, it
// gets converted to a StorableObject.  So this is a more compact way
// of doing the same thing.
storage.books.add({title: "Musashi", author: "Eiji Yoshikawa"});
storage.books.add({title: "Hackers & Painters", author: "Paul Graham"});

function printBook(book) {
  printp(html("<i>", book.title, "</i> (by ", book.author, ")"));
}

// Print books sorted by their StorableObject creation date.
storage.books.sort().forEach(printBook);
print(html(""));

// Print books sorted alphabetically by title.
storage.books.sortBy("title").forEach(printBook);
print(html(""));

// Print books sorted reverse-alphabetically by author.
storage.books.sortBy("-author").forEach(printBook);

Method Detail

<static> {StorableObject} StorableCollection.add(obj)

Adds a StorableObject to this collection.

var c = new StorableCollection();
c.add({name: "John"});

Parameters:
{object} obj: The object to add to this collection. If obj is not a StorableObject, a new StorableObject is created from obj by passing it to the StorableObject constructor, copying its properties.

Returns:: {StorableObject} The added object.

<static> {number} StorableCollection.first()

Gets the first object in this StorableCollection.

print(storage.mycollection.filter({status: 3}).first());

Returns:: {number} The first object in this collection.

<static> StorableCollection.forEach(f)

Executes a function once on each member of this collection.

// prints most recent 10 items of a collection.
storage.mycollection.sort().reverse().forEach(function(o) {
  printp("recent object: ", o);
});

Parameters:
{function} f: The function to call on each member of this collection. Returning false will cause forEach to abort.

<static> StorableCollection.limit(n)

Returns a view consisting of the first n elements of this collection or view. Useful in combination with sort to get, for example, the 10 most recent items in a collection.

limit() is a "chainable" operation: it can be applied to other filtered, sorted, or limited views.

storage.mycollection.filter({user: "bob"}).limit(10).forEach(printp);

Parameters:
{number} n: How many elements to limit the new view to.

Returns:: A limited view of this collection.

<static> StorableCollection.remove(obj)

Removes StorableObjects from this collection.

var c = storage.users; // a StorableCollection
c.remove({name: "John"});

Parameters:
{object} obj: The object to remove from this collection. If obj is a StorableObject, obj itself is removed from this collection. If obj is an collection or a view on a collection (such as one created by filter), then all objects provided in that collection are removed. Finally, if obj is just a plain object, then all members of this collection that have the same properties and values as obj are removed. Note: passing an {} removes all objects form this collection.

See:: #StorableCollection.filter

<static> StorableCollection.reverse()

Returns a view with the order of elements reversed.

reverse() is a "chainable" operation: it can be applied to other filtered, sorted, or limited views.

Returns:: A new view of this collection

<static> {number} StorableCollection.size()

Returns the number of elements in a collection. Can also be applied to filtered and sorted views of a collection. (This number may be approximate if your collection is very large or if many requests are modifying it simultaneously.)

var size = storage.mycollection.filter({status: 3}).size();

Returns:: {number} The size of this collection.

<static> StorableCollection.skip(n)

Returns a view that skips the first n elements of this collection or view.

skip() is a "chainable" operation: it can be applied to other filtered, sorted, or limited views.

This is particularly useful for paginating elements in a storable collection. If there are n elements per page, and you want to display page p, then you can get a view of this page's elements with collection.skip(n*(p-1)).limit(n), as in the example below.

// rendering part of a paginated collection
var p = request.param("pageNum");
var n = 10; // items per page
var view = mycollection.sort().skip(n*(p-1)).limit(n);
view.forEach(printp);

Parameters:
{number} n: How many elements to skip.

Returns:: A new view of this collection with the first n elements skipped.

<static> StorableCollection.sort(compare)

Returns a sorted view of this collection based on a sorting function, or by object creation date if no sorting function is given.

sort() does not modify the StorableCollection is is called on. Instead, it returns a view of the StorableCollection, which can be further sorted, limited, or iterated over.

sort() is a "chainable" operation: it can be applied to other filtered, sorted, or limited views, as in the example below.

function ageCompare(p1, p2) { return p2.age - p1.age; }
function printPerson(p) { printp(p.name); }

storage.people.sort(ageCompare).forEach(printPerson);

Parameters:

{function} compare Optional

As with the function argument to Array.sort, compare should take two arguments a and b, and return a negative value, 0, or a positive value, if a < b, a = b, or a > b, respectively.

If no sort function is passed in, the returned view is sorted by object creation time, oldest objects first.

Returns:: A sorted view of this collection.

<static> StorableCollection.sortBy(propertyName1, propertyName2, etc)

Returns a sorted view of this collection based on a property name. This is sometimes more convienent than calling the more general sort() method and writing your own comparator function.

sortBy is a "chainable" operation: it can be applied to other filtered, sorted, or limited views.

// sorts by "lastName" property, descending, and then 
// secondarily by "firstName" property, ascending.

storage.people.sortBy("-lastName", "firstName").forEach(printp);

Parameters:
{string} propertyName1: Which property to use to compare the collected objects on. Optionally prepend the property name with a "-" to reverse the sort order.
{string} propertyName2: A secondary property to further sort the objects.
{string} etc: etc.

Returns:: A sorted view of this collection.

Classes

Class StorableCollection