Properties and Attached Properties in the JavaScript API
Microsoft Silverlight will reach end of support after October 2021. Learn more.
Attached properties are a concept defined by the XAML language, used first in WPF, and subsequently also used in Silverlight 1.0 and Silverlight 2. In XAML, attached property usages are straightforward and are also consistent across the aforementioned technologies. When used with JavaScript API, attached property access at run-time requires a different syntax, which is unique to the JavaScript API. Also, the JavaScript API has two utility methods that provide an alternative property-setting syntax for Silverlight properties in general, including attached properties. This topic describes the syntax for getting and setting properties and attached properties for the JavaScript API, and the usage of the GetValue/SetValue utility methods.
This topic contains the following sections.
- GetValue and SetValue
- Attached Properties in WPF and Managed Code
- Attached Properties in Silverlight (JavaScript API)
- Attached Property Syntax for JavaScript
- Related Topics
GetValue and SetValue
Properties in the Silverlight object model are exposed to JavaScript through an object.property notation, similar to many other in-browser programming models. Because it is prototype-based, you can also set property values that are not in the API on any object in JavaScript, and then get that value later.
The JavaScript API for Silverlight also provides two accessor methods, GetValue and SetValue , which get and set properties based on passing the relevant property name as a string. These methods are actually providing an intermediate "wrapper" implementation that processes JavaScript into native objects for Silverlight, but are exposed as part of the general user API because they are occasionally useful for certain scenarios. Example usages are given in the reference pages for the GetValue and SetValue, in case you encounter such a scenario. That said, you generally do not need to use the GetValue / SetValue methods. The object.property notation for getting and setting properties is equivalent and is generally more intuitive.
.gif "Note") Note: |
|---|
If you are familiar with WPF or the managed API for Silverlight, you might know about the GetValue and SetValue methods that are part of the property system. These are not entirely equivalent to the Silverlight JavaScript GetValue/SetValue . In WPF or the managed API for Silverlight, GetValue and SetValue can only act on dependency properties, whereas GetValue/SetValue can act on any Silverlight property available in the JavaScript API. |
Attached Properties in WPF and Managed Code
It may be useful to provide some background on the attached property usages that are available for WPF and managed code. In managed code, the XAML parser uses a discovery pattern for determining the accessors for attached properties, in order to process the values. The discovery pattern is based on methods named Get* and Set*, and is described in the XAML language specifications (though the managed specifics of the WPF implementation are not described there).
Attached Properties in Silverlight (JavaScript API)
For the JavaScript API, the XAML parser recognizes a small number of attached properties:
The XAML parser behavior considers an attached property name as a whole string and as a discrete property that happens to be settable on any UIElement in the object tree. However, this cannot work for the JavaScript access because the dot in the attached property name triggers a step into the object model and would presume an intermediate object/property value Canvas that does not exist on the parent.
Attached Property Syntax for JavaScript
You set attached properties in JavaScript for Silverlight by using a syntax that resembles a JavaScript indexer syntax: object["attachedPropertyName"], where attachedPropertyName is a string that defines the full dotted name of the attached property (for example Canvas.Top). Another way to think of the whole attachedPropertyName is as the DefiningClass.AttachedProperty parts of a single attachedPropertyName string.
You can also use GetValue/SetValue to set an attached property, although just as with standard properties the GetValue/SetValue usages are really the less common alternative.
The most important aspect to note here is that in both the GetValue/SetValue notations and the abridged notation, the . (dot) is considered part of the property name/identifier, and must be within the quotes. The following example shows the various syntaxes through usage:
// Set the value using the ["attachedPropertyName"] notation.
anObject["Canvas.Top"] = 40;
// Set the value using the SetValue method.
anObject2.setValue("Canvas.Top", 40);
// Get the value using the ["attachedPropertyName"] notation.
var top = anObject["Canvas.Top"];
// Get the value using the GetValue method.
var top2 = anObject2.GetValue("Canvas.Top");