Class: SC.RecordArray


Extends SC.Array, SC.Enumerable, SC.Object.

A RecordArray is a managed list of records (instances of your SC.Record model classes).

Using RecordArrays

Most often, RecordArrays contain the results of a SC.Query. You will generally not create or modify record arrays yourselves, instead using the ones returned from calls to SC.Store#find with either a record type or a query.

The membership of these query-backed record arrays is managed by the store, which searches already-loaded records for local queries, and defers to your data source for remote ones (see SC.Query documentation for more details). Since membership in these record arrays is managed by the store, you will not generally add, remove or rearrange them here (see isEditable below).

Query-backed record arrays have a status property which reflects the store's progress in fulfilling the query. See notes on status below.

(Note that instances of SC.Query are dumb descriptor objects which do not have a status or results of their own. References to a query's status or results should be understood to refer to those of its record array.)

Internal Notes

This section is about RecordArray internals, and is only intended for those who need to extend this class to do something special.

A RecordArray wraps an array of store keys, listed on its storeKeys property. If you request a record from the array, e.g. via objectAt, the RecordArray will convert the requested store key to a record suitable for public use.

The list of store keys is usually managed by the store. If you are using your RecordArray with a query, you should manage the results via the store, and not try to directly manipulate the results via the array. If you are managing the array's store keys yourself, then any array-like operation will be translated into similar calls on the underlying storeKeys array. This underlying array can be a real array, or, if you wish to implement incremental loading, it may be a SparseArray.

If the record array is created with an SC.Query object (as is almost always the case), then the record array will also consult the query for various delegate operations such as determining if the record array should update automatically whenever records in the store changes. It will also ask the query to refresh the storeKeys list whenever records change in the store.

Defined in: record_array.js

Since:
SproutCore 1.0

Field Summary

Instance Methods

Field Detail

needsFlush Boolean

Set to YES when the query is dirty and needs to update its storeKeys before returning any results. RecordArrays always start dirty and become clean the first time you try to access their contents.

NOT_EDITABLE SC.Error
Standard error throw when you try to modify a record that is not editable
query SC.Query

The SC.Query object this record array is based upon. All record arrays MUST* have an associated query in order to function correctly. You cannot change this property once it has been set.

NOTE: You MUST set this property on the RecordArray when creating it or else it will fail.

QUERY_MATCHING_THRESHOLD Number

Number of milliseconds to allow a query matching to run for. If this number is exceeded, the query matching will be paced so as to not lock up the browser (by essentially splitting the work with an invokeNext)

status Number

Reflects the store's current status in fulfilling the record array's query. Note that this status is not directly related to the status of the array's records:

  • The store returns local queries immediately, regardless of any first-time loading they may trigger. (Note that by default, local queries are limited to 100ms processing time per run loop, so very complex queries may take several run loops to return to READY status. You can edit SC.RecordArray.QUERY_MATCHING_THRESHOLD to change this duration.)
  • The store fulfills remote queries by passing them to your data source's fetch method. While fetching, it sets your array's status to BUSY_LOADING or BUSY_REFRESHING. Once your data source has finished fetching (successfully or otherwise), it will call the appropriate store methods (e.g. dataSourceDidFetchQuery or dataSourceDidErrorQuery), which will update the query's array's status.

Thus, a record array may have a READY status while records are still loading (if a local query triggers a call to SC.DataSource#fetch), and will not reflect the DIRTY status of any of its records.

store SC.Store

The store that owns this record array. All record arrays must have a store to function properly.

NOTE: You MUST set this property on the RecordArray when creating it or else it will fail.

storeKeys SC.Array
The array of `storeKeys` as retrieved from the owner store.

Instance Method Detail

add(record)

Adds the specified record to the record array if it is not already part of the array. Provided for compatibility with SC.Set.

Parameters:
record SC.Record
Returns:
SC.RecordArray
receiver
contains(record)

Returns YES if the passed record can be found in the record array. This is provided for compatibility with SC.Set.

Parameters:
record SC.Record
Returns:
Boolean
destroy()

Destroys the record array. Releases any storeKeys, and deregisters with the owner store.

Returns:
SC.RecordArray
receiver
errorObject()

Returns the current error object only if the record array is in an error state. If no explicit error object has been set, returns SC.Record.GENERIC_ERROR.

errorValue()

Returns the receiver if the record array is in an error state. Returns null otherwise.

find(query, target, target)

Extends the standard SC.Enumerable implementation to return results based on a Query if you pass it in.

Parameters:
query SC.Query
a SC.Query object
target Object
the target object to use
target
Returns:
SC.RecordArray
flush(_flush)

Applies the query to any pending changed store keys, updating the record array contents as necessary. This method is called automatically anytime you access the RecordArray to make sure it is up to date, but you can call it yourself as well if you need to force the record array to fully update immediately.

Currently this method only has an effect if the query location is SC.Query.LOCAL. You can call this method on any RecordArray however, without an error.

Parameters:
_flush Boolean
to force it - use reload() to trigger it
Returns:
SC.RecordArray
receiver
isEditable()

The current editable state of the query. If this record array is not backed by a query, it is assumed to be editable.

isError()

Returns YES whenever the status is SC.Record.ERROR. This will allow you to put the UI into an error state.

propertyWillChange(key)
Parameters:
key
refresh()

Call whenever you want to refresh the results of this query. This will notify the data source, asking it to refresh the contents.

Returns:
SC.RecordArray
receiver
reload()

Will recompute the results of the attached SC.Query. Useful if your query is based on computed properties that might have changed.

This method is for local use only, operating only on records that have already been loaded into your store. If you wish to re-fetch a remote query via your data source, use refresh() instead.

Returns:
SC.RecordArray
receiver
remove(record)

Removes the specified record from the array if it is not already a part of the array. Provided for compatibility with SC.Set.

Parameters:
record SC.Record
Returns:
SC.RecordArray
receiver
toString()
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)