Web Gadget SDK Web Gadget SDK
[Back to Web Gadget API Reference]
Web.Bindings Class
Bindings are cross-browser component model for attaching different behaviors to existing and custom elements. Bindings are conceptually similar to DHTML bindings with the additional benefits of being compatible cross-browser, support the prioritization network stack of the core framework, and provide enhanced interfaces for better integration with other components and the overall browser.

This class provides methods to programmatically bind elements and selectors to a web binding.
attachElementBinding Method
Attaches a binding directly to an element asynchronously. You should use this version of the method if the binding sources are not included on the page or if you are not sure.
Syntax
Web.Bindings.attachElementBinding( elItem, vBindingType, objScope,
                                   objParams, strNamespace, fnCallback,
                                   astrBindingSource, astrStyleSource, ePriority );
Parameters
Parameter Description
elItem The DOM element object to which we are attaching the binding to.
vBindingType A string or an actual JavaScript class that identifies the type of the binding object to attach.
objScope The object scope represents the parent binding and is used to establish an object hierarchy.
objParams Object passed to the constructor of the Binding object being attached.
strNamespace TBD
fnCallback Callback function to call when the binding is instantiated.
astrBindingSource Array of JavaScript sources that contain your bindings.
astrStyleSource Array of CSS sources that contain the style sheets used in your bindings.
ePriority The priority to download the scripts required to load this binding. If not specified, the priority defaults to High. Supported values are:
  • Web.Utility.Prioritizer.Priorities.High
  • Web.Utility.Prioritizer.Priorities.Medium
  • Web.Utility.Prioritizer.Priorities.Low
  • Web.Utility.Prioritizer.Priorities.Lowest
Return Value
None
Example
The following example uses the attachElementBinding method to programmatically attach a binding.
TBD
attachElementBindingSync Method
Attaches a binding directly to an element. You should use this version of the method if the binding definitions are already included on the page.
Syntax
var arrBindings = Web.Bindings.attachElementBindingSync(elItem, vBindingType, objScope, objParams, strNamespace);
Parameters
Parameter Description
elItem The DOM element object to which we are attaching the binding to.
vBindingType A string or an actual JavaScript class that identifies the type of the binding object to attach.
objScope The object scope represents the parent binding and is used to establish an object hierarchy.
objParams Object passed to the constructor of the Binding object being attached.
strNamespace TBD
Return Value
An array of binding objects instantiated.
Example
The following example uses the attachElementBindingSync method to programmatically attach binding. 
    Microsoft.Live.GadgetSDK.ParentBinding = function( p_elSource, p_args, p_namespace )
    {
        Microsoft.Live.GadgetSDK.ParentBinding.initializeBase(this, arguments);
        
        m_this = this;
        ...
        
        this.initialize = function(p_objScope)
        {
            var btnEl = document.create("div");
            btnEl.id = "button";
            var settingsMenuBinding = Web.Bindings.attachElementBindingSync( btnEl, 
                                                                             Microsoft.Live.GadgetSDK.SampleButton,
                                                                             m_this,
                                                                             {ParamA:"A", ParamB:"B"} );
            ...
        }

        ...
    }
attachEvent Method
Attaches an event handler function to a binding object's event.
Syntax
binding.attachEvent(strEventName, fnCallback);
Parameters
Parameter Description
strEventName Name of the binding object's event to attach to.
fnCallback Function to call whenever the event fires.
Return Value
None
Example
See the section on Working with Bindings in the Windows Live Gadget Developer's Guide for an example on how to attach to and detach from Binding events.
attachSelectorBinding Method
Attaches a binding via a CSS Selector asynchronously. You should use this version of the method if the binding sources are not included on the page or if you are not sure.
Syntax
Web.Bindings.attachSelectorBinding( vSelector, vBindingType, objScope,
                                    objParams, strNamespace,  elScope,
                                    fnCallback, astrBindingSource, astrStyleSource, ePriority );
Parameters
Parameter Description
vSelector The CSS selector to attach to. Mose CSS selectors are supported. For defining selectors for custom elements, do not escape the ":" between the namespace and element. For example, in CSS you would specify "foo\:bar". For bindings, only specify "foo:bar".
If no selector is specified, the binding is bound to the HTML element of the web page. This is typically used by application-level bindings that are managing the relationship and communication for other sub-bindings on the web page.
vBindingType Specifies the binding implementation. This can either be a string or the actual JavaScript class of the binding class.
objScope The object scope represents the parent binding and is used to establish an object hierarchy.
objParams Object passed to the constructor of the Binding object being attached.
strNamespace TBD
elScope An HTML element that represents which element acts as the root when applied to the selector. If this argument is not specified, the entire document is scanned for matching elements.
fnCallback Callback function to call when the binding is instantiated.
astrBindingSource Array of JavaScript sources that contain your bindings.
astrStyleSource Array of CSS sources that contain the style sheets used in your bindings.
ePrioirty The priority to download the scripts required to load this binding. If not specified, the priority defaults to High. Supported values are:
  • Web.Utility.Prioritizer.Priorities.High
  • Web.Utility.Prioritizer.Priorities.Medium
  • Web.Utility.Prioritizer.Priorities.Low
  • Web.Utility.Prioritizer.Priorities.Lowest
Return Value
None
Example
TBD 
TBD
attachSelectorBindingSync Method
Attaches a binding via a CSS Selector synchronously. This method should be used if the binding definitions are already included on the page.
Syntax
Web.Bindings.attachSelectorBindingSync( vSelector, vBindingType, objScope,
                                        objParams, strNamespace, elScope );
Parameters
Parameter Description
vSelector The CSS selector to attach to. Mose CSS selectors are supported. For defining selectors for custom elements, do not escape the ":" between the namespace and element. For example, in CSS you would specify "foo\:bar". For bindings, only specify "foo:bar".
If no selector is specified, the binding is bound to the HTML element of the web page. This is typically used by application-level bindings that are managing the relationship and communication for other sub-bindings on the web page.
vBindingType Specifies the binding implementation. This can either be a string or the actual JavaScript class of the binding class.
objScope The object scope represents the parent binding and is used to establish an object hierarchy.
objParams Object passed to the constructor of the Binding object being attached.
strNamespace TBD
elScope An HTML element that represents which element acts as the root when applied to the selector. If this argument is not specified, the entire document is scanned for matching elements.
Return Value
Boolean value indicating whether the string contained in the StringBuilder object is empty or not. True if the string is empty, false otherwise.
Example
TBD 
    Microsoft.Live.GadgetSDK.ParentBinding = function( p_elSource, p_args, p_namespace )
    {
        Microsoft.Live.GadgetSDK.ParentBinding.initializeBase(this, arguments);
        
        m_this = this;
        m_el = p_elSource;
        ...
        
        this.initialize = function(p_objScope)
        {
            m_el.innerHTML = "<span class='getStarted'>" + "Hello" + "</span>";
            var helloBinding = Web.Bindings.attachSelectorBindingSync( '.getStarted', 
                                                                       Microsoft.Live.GadgetSDK.SampleBinding,
                                                                       null,
                                                                       {onclick:OnClickGetStarted, classname:"getStarted"} );
            ...
        }

        ...
    }
detachEvent Method
Detaches an event handler from a binding object's event.
Syntax
binding.detachEvent(strEventName, fnCallback);
Parameters
Parameter Description
strEventName Name of the event to detach from.
fnCallback Call back function to detach from.
Return Value
None
Example
See the section on Working with Bindings in the Windows Live Gadget Developer's Guide for an example on how to attach to and detach from Binding events.
©2006 Microsoft Corporation.