Class: SC.RecordAttribute


Extends SC.Object.

A RecordAttribute describes a single attribute on a record. It is used to generate computed properties on records that can automatically convert data types and verify data.

When defining an attribute on an SC.Record, you can configure it this way:

title: SC.Record.attr(String, {
  defaultValue: 'Untitled',
  isRequired: YES|NO
})

In addition to having predefined transform types, there is also a way to set a computed relationship on an attribute. A typical example of this would be if you have record with a parentGuid attribute, but are not able to determine which record type to map to before looking at the guid (or any other attributes). To set up such a computed property, you can attach a function in the attribute definition of the SC.Record subclass:

relatedToComputed: SC.Record.toOne(function() {
  return (this.readAttribute('relatedToComputed').indexOf("foo")==0) ? MyApp.Foo : MyApp.Bar;
})

Notice that we are not using .get() to avoid another transform which would trigger an infinite loop.

You usually will not work with RecordAttribute objects directly, though you may extend the class in any way that you like to create a custom attribute.

A number of default RecordAttribute types are defined on the SC.Record.

Defined in: record_attribute.js

See:
SC.Record
SC.ManyAttribute
SC.SingleAttribute
Since:
SproutCore 1.0

Field Summary

Instance Methods

Field Detail

aggregate Boolean

Can only be used for toOne or toMany relationship attributes. If YES, this flag will ensure that any related objects will also be marked dirty when this record dirtied.

Useful when you might have multiple related objects that you want to consider in an 'aggregated' state. For instance, by changing a child object (image) you might also want to automatically mark the parent (album) dirty as well.

Default value:
NO
defaultValue Object|function

The default value. If attribute is null or undefined, this default value will be substituted instead. Note that defaultValues are not converted, so the value should be in the output type expected by the attribute.

If you use a defaultValue function, the arguments given to it are the record instance and the key.

Default value:
null
isEditable Boolean
If `NO` then attempts to edit the attribute will be ignored.
Default value:
YES
isRecordAttribute Boolean
Walk like a duck.
Default value:
YES
isRequired Boolean

If YES, then the attribute is required and will fail validation unless the property is set to a non-null or undefined value.

Default value:
NO
key String

The underlying attribute key name this attribute should manage. If this property is left empty, then the key will be whatever property name this attribute assigned to on the record. If you need to provide some kind of alternate mapping, this provides you a way to override it.

Default value:
null
lazilyInstantiate Boolean

Can only be used for toOne or toMany relationship attributes. If YES, this flag will lazily create the related record that was pushed in from the data source (via pushRetrieve) if the related record does not exist yet.

Useful when you have a record used as a join table. Assumptions then can be made that the record exists at all times (even if it doesn't). For instance, if you have a contact that is a member of groups, a group will be created automatically when a contact pushes a new group.

Note that you will have to take care of destroying the created record once all relationships are removed from it.

Default value:
NO
type Object|String

The attribute type. Must be either an object class or a property path naming a class. The built in handler allows all native types to pass through, converts records to ids and dates to UTF strings.

If you use the attr() helper method to create a RecordAttribute instance, it will set this property to the first parameter you pass.

Default value:
String
useIsoDate Boolean

If set when using the Date format, expect the ISO8601 date format. This is the default.

Default value:
YES

Instance Method Detail

apply(target, args)
Apply needs to implemented for sc_super to work.
Parameters:
target
args
See:
SC.RecordAttribute#call
attr(attributeType, opts)

The default method used to create a record attribute instance. Unlike create(), takes an attributeType as the first parameter which will be set on the attribute itself. You can pass a string naming a class or a class itself.

Parameters:
attributeType Object|String
the assumed attribute type
opts Hash
optional additional config options
Returns:
SC.RecordAttribute
new instance
call(record, key, value)

The core handler. Called when get() is called on the parent record, since SC.RecordAttribute uses isProperty to masquerade as a computed property. Get expects a property be a function, thus we need to implement call.

Parameters:
record SC.Record
The record instance
key String
The key used to access this attribute on the record
value Object
The property value if called as a setter
Returns:
Object
property value
fromType(record, key, value)

Converts the passed value from the core attribute value. This will apply any format transforms. You can install standard transforms by adding to the SC.RecordAttribute.transforms hash. See SC.RecordAttribute.registerTransform() for more.

Parameters:
record SC.Record
The record instance
key String
The key used to access this attribute on the record
value Object
The transformed value
Returns:
Object
The value converted back to attribute format
registerTransform(klass, transform)

Call to register a transform handler for a specific type of object. The object you pass can be of any type as long as it responds to the following methods

  • to(value, attr, klass, record, key) converts the passed value (which will be of the class expected by the attribute) into the underlying attribute value
  • from(value, attr, klass, record, key) converts the underlying attribute value into a value of the class

You can also provide an array of keys to observer on the return value. When any of these change, your from method will be called to write the changed object back to the record. For example:

{
  to: function(value, attr, type, record, key) {
    if(value) return value.toSet();
    else return SC.Set.create();
  },

  from: function(value, attr, type, record, key) {
    return value.toArray();
  },

  observesChildren: ['[]']
}
Parameters:
klass Object
the type of object you convert
transform Object
the transform object
Returns:
SC.RecordAttribute
receiver
toType(record, key, value)

Converts the passed value into the core attribute value. This will apply any format transforms. You can install standard transforms by adding to the SC.RecordAttribute.transforms hash. See SC.RecordAttribute.registerTransform() for more.

Parameters:
record SC.Record
The record instance
key String
The key used to access this attribute on the record
value Object
The property value before being transformed
Returns:
Object
The transformed value
transform()

Finds the transform handler. Attempts to find a transform that you registered using registerTransform for this attribute's type, otherwise defaults to using the default transform for String.

typeClass()

Returns the type, resolved to a class. If the type property is a regular class, returns the type unchanged. Otherwise attempts to lookup the type as a property path.

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)