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
- Fields borrowed from SC.Object:
- concatenatedProperties, isDestroyed, isObject, nextProperty, object, property, target, toInvalidate
- Fields borrowed from SC.Observable:
- isObservable
- Fields borrowed from SC.Enumerable:
- isEnumerable
- Fields borrowed from SC.Array:
- isSCArray
Instance Methods
- add(record)
- contains(record)
- destroy()
- errorObject()
- errorValue()
- find(query, target, target)
- flush(_flush)
- isEditable()
- isError()
- propertyWillChange(key)
- refresh()
- reload()
- remove(record)
- toString()
Field Detail
needsFlush BooleanSet 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.
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.
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)
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
READYstatus. You can editSC.RecordArray.QUERY_MATCHING_THRESHOLDto change this duration.) - The store fulfills remote queries by passing them to your data source's
fetchmethod. While fetching, it sets your array's status toBUSY_LOADINGorBUSY_REFRESHING. Once your data source has finished fetching (successfully or otherwise), it will call the appropriate store methods (e.g.dataSourceDidFetchQueryordataSourceDidErrorQuery), 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.
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.
Instance Method Detail
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
Returns YES if the passed record can be found in the record array. This is
provided for compatibility with SC.Set.
Destroys the record array. Releases any storeKeys, and deregisters with
the owner store.
- Returns:
- SC.RecordArray
- receiver
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.
Returns the receiver if the record array is in an error state. Returns
null otherwise.
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
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
The current editable state of the query. If this record array is not backed by a query, it is assumed to be editable.
Returns YES whenever the status is SC.Record.ERROR. This will allow
you to put the UI into an error state.
- Parameters:
- key
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
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
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