Class: PXDB_COLLECTION

PXDB_COLLECTION()

A PXDB_COLLECTION class represents a collection of the corresponding PXDB_MODEL objects. This is equivalent to the result set of a database query.

There is no class named PXDB_COLLECTION; as for PXDB_MODEL, this is a 'metaclass', a form of class that will be generated for each of the schema types in the GraphQL schema. The classes will be stored on the classes property of the engine instance, with names specified as documented at pxdb.create_backbone_classes().

Except where specified, PXDB_COLLECTION classes work identically to standard Backbone Collections.

In this documentation, wherever PXDB_COLLECTION is stated, replace with the actual class name for the object type.

Constructor

new PXDB_COLLECTION()

Source:

Extends

  • Backbone.Collection

Members

(static) inheritSelection

Boolean flag. If true, the selection set on this collection by the selection() method will automatically be set on all models within this collection, when those models are added.

This will occur regardless of whether or not the models were created by create(), created independently via constructors and then added via add(), or fetched from the server via fetch().

The models can subsequently have their selections changed by calling selection() on them, but if the collection's selection is updated via the collection's selection() method, the models will have their selections reset if this flag is true.

Source:

(static) url

PXDB_COLLECTION classes do not use or need the url property to function. Its absence is documented here.

Source:

Methods

(static) sync()

This is the overriden sync method, which calls pxdb.backbone_sync() to perform GraphQL queries and mutations. It should not be called directly.

Source:

clearPaging()

Unsets the page size and number for this collection, disabling server-side paging until and unless paging() is called again.

Source:

expression(newexp) → {string}

Sets and/or returns the filter expression for this collection. The filter expression is used in PXDB GraphQL queries to determine what rows are returned. This is a logical expression with a syntax similar to a SQL where clause, but with some differences; this syntax is documented at (TBD).

Parameters:
Name Type Description
newexp string

New filter expression to set. If not provided, the existing filter expression is returned.

Source:
Returns:

Filter expression currently set for this collection.

Type
string

ordering(neworder) → {array}

Sets and/or returns the server-side ordering parameters for this collection. Server-side ordering is specified using an array of field names as strings, with the optional keywords'asc' and 'desc' appended to them, for ascending and descending order, respectively; if used, a space is required between the field name and the asc or desc keyword.

NB: Client-side sorting using Backbone's standard comparator facility is unaffected by this setting.

Parameters:
Name Type Description
neworder array

New ordering spec. If not provided, existing ordering is returned.

Source:
Returns:

Ordering currently set for this collection.

Type
array

paging(pagesize) → {array}

Sets and/or returns the server-side paging settings for this collection. Server-side paging is specified using a page size, with this method, and a page number, with the method setPage(). This instructs the server to return a maximum number of records equal to the page size, offset by the page number.

Note that it is possible for a paged query to return fewer records than the page size; this indicates that the "last page" has been reached. Setting the page number past the "last page" will result in no records being returned.

Server-side ordering should be used with this facility to ensure consistent results.

Page size must be a positive integer.

Calling this method will automatically reset the page number to 1.

Parameters:
Name Type Description
pagesize integer

Page size. If not provided, the current page size and number are returned.

Source:
Returns:

Page size and number currently set for this collection, as an array: page size is the first element, page number the second.

Type
array

selection(newselect) → {array}

Sets and/or returns the 'selection', that is, what fields are queried and returned on the model. This is checked against the schema, so only valid attributes can be queried.

The selection must be formatted as follows: an array of either strings, for scalar fields, or objects, for subselection of linked types: the key is the linked type name, value is an array of fields to select on that type.

For instance, consider a type "Person" that has fields "personid", "firstname", "lastname", and a linked type "EmailAddress" with fields "personid" and "email" on it; to select the personid, firstname, lastname, and EmailAddress_collection on the Person type, with the email on the EmailAddress linked type, the selection would be formatted like so:

['personid', 'firstname', 'lastname', {EmailAddress_collection: ['email']}].

NB: Setting the selection on a collection has no effect on the selection of the contained models, unless the collection attribute "inheritSelection" is set to true, in which case new models will have their selections set automatically to that of the containing collection.

In any case, selections can be set independently for a collection and for individual models (the latter by calling "selection()" on a given model); this is useful for fetching a set of records with basic attributes, and then "drilling down" to get more information on specific records.

Parameters:
Name Type Description
newselect array

New selection to assign. If not passed in, the existing selection is returned.

Source:
Returns:

Selection currently set on this model.

Type
array

setPage(pagenum) → {array}

Sets the page number when using server-side paging. Page number must be a positive integer. Returns the page size and number as for paging().

Parameters:
Name Type Description
pagenum integer

Page number.

Source:
Returns:

See paging() return value.

Type
array