What's the correct syntax for data-win-bind?


  • What can I pass to the data-win-bind attribute? The docs are clearly out of sync. That's obvious when you look at the declarative binding sample. It seems that you can pass it an initial setup binding method? For instance, here's some markup from the basic binding page:

     <p data-win-bind="style.background: color BasicBinding.toCssColor">

            And here's your color as a background.</p>

    It seems like style.background is being initialized to the color property of some object and then there's that method reference which ends up building a programmatic binding (by calling the WinJS.Binding.bind method). Can anyone explain what's going on here? what can I pass to the data-win-bind attribute?


    Luis Abreu

    Thursday, March 22, 2012 1:04 PM

All replies

  • Hi Luis,

    You need to use the correct CSS style attibutes.

    So for example, background color is defined like this in a CSS file:

       background-color: #ffd800

    so you would use something similar to this:

    <p data-win-bind="style.background-color: BasicBinding.toCssColor">

            And here's your color as a background.</p>

    Do you understand why your definition would never work now?


    Jeff Sanders (MSFT)

    Thursday, March 22, 2012 3:36 PM
  • Hello Jeff.

    Yeah, I understand what you're saying regarding the color stuff and passing the values in the correct format. My question is not really that. What I want to know is what what's the correct syntax associated with the data-win-bin attribute.

    btw, I'm not sure if you're suggesting that my example won't work. ie, are you saying that this won't work:

    <p data-win-bind="style.background: color BasicBinding.toCssColor">

            And here's your color as a background.</p>

    (notice the use of the *color* property)

    If that is the case, then I believe you're wrong because:

    1.) I've copied that code from the win 8 consumer preview samples (declarative binding project, basicscenario.html file)

    2.) I've tried your code and it doesn't work (ie, I've tried removing color and using only the setup method as you suggest, but it simply doesn't work)

    So, back to the main question. The docs say that data-win-bind can only have property/value pairs (ie, property:value; anotherProperty:value), but the sample makes it obvious that you can pass it some sort of initialization function. can you elaborate more about this?


    Luis Abreu

    Friday, March 23, 2012 10:17 AM
  • The declaritive binding sample uses complex binding.

    I am not suggesting you cannot get this to work, but from your example there is simply no way to determine what you are doing or what the rest of your code may be doing (and why it would fail).

    So yes, in the baseline example you need to ensure it is value pairs, you CAN do function based complex binding too (as the sample shows).  You can use that as a great sample of how to do this.  You can also do complex binding.

    Here is how to do complex binding to an object:



    Jeff Sanders (MSFT)

    Friday, March 23, 2012 2:17 PM
  • Hello Jeff.

    Thanks for your patience. I believe I'm still failing to communicate with you :)

    Notice that I'm only interested in understanding what can be put in the data-wind-bind attribute...

    Lets see if I can understand what you said. Whenever we use declarative binding, the expected syntax is to use one or more key:value pair entries, right? Example:

    <div data-win-bind="innerHTML: name">...

    Now, it also looks like you can specify an initialization function (which is what the sample seems to be doing). In this case, you can pass one or more value pairs followed by an initialization function? Ie, to influence the way the declarative binding gets created, I can do this:

    <div data-win-bind="innerHTML: name initializeMyBinding">...

    And then have the following function:

    function initializeMyBinding(source, sourceProperty, destination, destinationProperty ){
      //do my initialization here

     //return a binding object?


    My question is: besides this initialization binding function that you can pass to the data-wind-bind method (*and* which isn't mentioned anywhere in the docs), is there anything else? What about converters? Does binding support converters (still haven't found anything about it yet)...

    I've already read all the info in the quick starts and I think I've understand what the bind method you mention does: basically, it sets up a function which will be called when a property of an observable object changes and it returns an object with a cancel method which should be invoked when you no longer are interested in getting notifications about those property changes.

    Luis Abreu

    Friday, March 23, 2012 3:01 PM
  • Yes, Communication via forums can be difficult!

    If I understand you correctly:  Yes!  I believe you do understand binding in HTML apps.

    DataBinding is all covered starting here and I think it is all documented:


    1. We document the value pair here: http://msdn.microsoft.com/en-us/library/windows/apps/hh700358.aspx

    2. We reference complex binding in the above documentation and point you here: How to use templates to bind data.

    and of course templates.

    You can use binding converters in your code!



    Does that help?



    Jeff Sanders (MSFT)

    Friday, March 23, 2012 3:28 PM
  • It does help. lets see if I got this right (I'm with a netbook, so I don't have VS here to test this)

    ok, let's start with Peter's link: http://peterkellner.net/2011/12/27/building-a-windows-8-metro-style-javascript-html5-css3-app-using-listview/ 

    he uses this template:

    <div style="margin: 15px 15px 15px 15px">
        <img data-win-bind="src: govtrack_id convertGovTrackIdToImgTag" 
            alt="Databound image" />

    and says that convertGovTrackIdToImgTag is a converter function defined like this:

    convertGovTrackIdToImgTag = WinJS.Binding.converter(function (govTrackId) {
        var retUrl = 'http://www.govtrack.us/data/photos/' + govTrackId + '-50px.jpeg';
        return retUrl;

    A converter function is a method which is called before the value is copied from source to destination. So, this function will get called whenever there's a change in the observable object, right?

    If this is correct, then the answer to my initial question is that each pair prop/value passed to the data-win-bin attribute can also reference a converter function (recall that my initial question was about what could be passed to data-win-bind attribute)

    Now, the reason for my confusion (besides seeing  no example of how to use a converter in the MS docs) is the  declarative sample available http://code.msdn.microsoft.com/windowsapps/DeclarativeBinding-bfcb42a5

    in this example, we've got the following declarative binding (http://code.msdn.microsoft.com/windowsapps/DeclarativeBinding-bfcb42a5/sourcecode?fileId=43658&pathId=1441755956):

    <!-- This binding shows that dot notation works for the destination property as well, and 
            demonstrates using a binding action - the BasicBinding.toCssColor function will be called 
            as part of this binding. --> 
          <p data-win-bind="style.background: color BasicBinding.toCssColor"        And here's your color as a background.</p> 

    So, if my previous assumptions are correct, then BasicBinding.toCssColor is a converter which should be called whenever a change happens in the color property of the data source object. However, the comments in the JS code below got me baffled :

            // This method is called to set up the binding. It only gets called once. 
            // Source is the source object, sourceProperty is the strings 
            // supplied in the binding action, dest is the destination object, 
            // and destProperty is the destination property string. 
            toCssColor: function (source, sourceProperty, dest, destProperty) { 
                // in this case, we're binding to a composite property. In order 
                // to get things to fire properly, we're going to hook up 
                // to multiple fields in the source object. 
                // helper method to actually set the style 
                function setBackColor() { 
                    dest.style.backgroundColor = rgb(source.color.red, source.color.green, source.color.blue); 
                // in this case, we're binding to a composite property. In order 
                // to get things to fire properly, we're going to hook up 
                // to multiple fields in the source object. 
                // Make sure to return the result of calling bind - this allows the 
                // binding system to properly clean up if the target element gets 
                // removed from the DOM. 
                return WinJS.Binding.bind(source, { 
                    color: { 
                        red: setBackColor, 
                        green: setBackColor, 
                        blue: setBackColor, 

    as you can see, it says that toCssColor is an "initialization function" (instead of a converter function?) which will only be called once and that would mean that it's not a converter (because a conveter might  be called several times).

    Now, what I'm thinking right now is that this converter will only be called once because it returns a new binding object which will replace the initial binding expression. in other words, if it did return a string with the color instead of a complex binding, then the toCssColor would be called whenever there was a change in the color properties.

    If this is correct, then it seems like I've finally understood what this means:

    <div data-win-bind="innerHTML: someProperty someName"

    ie, bind innerHTML to someProperty and pass it through someName to get the value that should be passed to the innerHTML property whenever someProperty changes.

    Am I correct? 

    Luis Abreu

    Friday, March 23, 2012 8:00 PM