<p>A <i>property path</i> is a string that is used to reference some property in SproutCore. For example the property path:</p>
<p><code>Contacts.contactController.content</code></p>
<p>Refers to the “content” property on the <code>Contacts.contactController</code> object.</p>
<p>You use property paths in SproutCore when you setup bindings and observers and to get and set properties on objects. The following show examples of using property paths:</p>
<pre><code>
Contacts.selectedContactController = SC.ObjectController.extend({
// Refers to the "selection" property on the Contacts.contactsController object.
contentBinding: "Contacts.contactsController.selection",
// Observes the "emailAddress" property on the this object (Contacts.selectedContactController)
emailAddressObserver: function() {
this.getNewAddressValue() ;
}.observes("emailAddress"),
getNewAddressValue: function() {
// gets the "value" property on the this.emailAddress object.
var addresses = this.getPath('emailAddress.value') ;
}
});
</code></pre>
<h1>Types of Property Paths</h1>
<p>SproutCore understands a variety of property paths. Most of them can be used anywhere a property path is needed, but some have meaning in special circumstances:</p>
<h3>Simple Properties</h3>
<p><code>"property"</code></p>
<p>A simple property path consists of just a property name. In SproutCore documentation this is sometimes called a property key. A simple property path always refers to the property on whatever object you are references.</p>
<p><i>Examples Here</i></p>
<h3>Absolute Properties</h3>
<p><code>"Namespace.object.property"</code></p>
<p>An absolute property path names both the object and the property in the path. It always contains at least one period and does not start with a period. Everything up to the last period is treated as an absolute path to an object. In the example above, the object is “Namespace.object” and the property is “property”.</p>
<p>You use this most often when setting up bindings and referencing application views.</p>
<p><i>Examples Here</i></p>
<h3>Relative Properties</h3>
<p><code>".object.property"</code></p>
<p>A relative property is a variation on the absolute path. Like absolute paths, you name both the object and the property but SproutCore will start by searching the current object instead of at the global level. For example, the above property’s object would be “this.object” while the property would be “property”.</p>
<p>This form is used very rarely. If you find yourself using this pattern often, you probably should consider using bindings.</p>
<h3>Chained Properties</h3>
<p><code>"Namespace.object*anotherObject.property</code></p>
<p><code>"*anotherObject.property"</code></p>
<p>Both Absolute and and Relative property paths can use a special variant called a “chained property”. Regular property paths are converted to an object/property reference at the time that you use them. This means, for example, if you setup a binding like:</p>
<p><code>valueBinding: "Contacts.selectedContact.emailAddress.value"</code></p>
<p>The object for this property will be whatever is at “Contacts.selectedContact.emailAddress”. But what if the selected contact changes? Since the binding was setup earlier in the application, the binding will not update to reflect the address change. In this case, you can use a chained property:</p>
<p><code>valueBinding: "Contacts.selectedContact*emailAddress.value"</code></p>
<p>This tells SproutCore that you expect the emailAddress to change and you would like to monitor changes for both emailAddress <span class="caps">AND</span> value for the binding.</p>
<p>Chained property paths are a useful way to reduce the complexity of your code when you have deeply nested properties that you need to observe. However, they can also be fairly expensive to setup and observe so you should avoid using them in “hot” code such as item views for collections. They are fine to use for wiring up controllers and bits of static UI however.</p>
<p><i>Example Here</i></p>
<h1>Related Links</h1>
<ul>
<li>[[Bindings, Properties, and Observers]]</li>
</ul>
<h1>Comments</h1>
2008-06-26T14:18:21-07:00
30875
about-sproutcore-property-paths
18944
About SproutCore Property Paths
2008-06-26T14:36:06-07:00
11814