Binding in Awesome

Awesome comes with a binding function and syntax that is used all through out AwesomeScript. The main function is called Awesome.EvalBind(). This function takes a string with a specific syntax and an object that results in a value. The string indicates how to retrieve the value for the object. There are no functions that utilizes this in Awesome’s core, but many controls and extensions make use of it.

Basic Binding

Basic binding requires just a single string with either a field name, property or function that belongs to an object. Anything that utilizes the binding features will retrieve the value of the field, property or function from the object and return its value for use. EvalBind automatically detects if the string refers to a field, property or function. Below is an example:

    alert(Awesome.EvalBind("length", "Testing binding"));

This function simply alerts the length property of the string "Testing binding".

Child Object Binding

You can access the properties of the objects in a binding string to retrieved nested values. For example, if you wanted to evaluate the binding of an anchor’s Text’s length component, you would use the string “Text.length”. It is known that Text will be a property of the anchor and it will return a string, from that we can get the length of the string. See the example below:

    alert(Awesome.EvalBind("Text.length", $Anchor("A1")));

Default Value

If you evaluate a binding string and the value ends up being undefined, the result will return an empty string since binding usually refers to binding to the HTML. If a value doesn’t exist, you can default the value if it doesn’t exist (undefined or null) by using the “:” indicator. Below is an example:

    alert(Awesome.EvalBind("Tag:Empty String!", $Anchor("A1")));

 

If the Tag for the anchor “A1” has not been set, then this will return “Empty String!” when evaluated.

Mapping Binding Values

You can take binding values and map them directly to another object with an indexer (arrays, Dictionaries, etc) using the @ symbol after the binding property.

    var map = ["Pending", "Processing", "Complete", "Rejected"];
    var o = { Order: { Status: 1} };

    alert(Awesome.EvalBind("Order.Status@map", o));

This will evaluate the Order property of the object “o” first, which returns an object with a Status property, which is evaluated next. This will return “1”. The @map indicates that the value should then be mapped to the global variable “map” and pull the value from this. This will fully return “Processing”.

Variable Binding and Functions

You can also call functions on evaluated values by simply using the function name, for example “Text.ToUpper()” This will return the Text property, call ToUpper() on it and return that value.

You can store bindings to a temporary variable to be used later in the binding expression by using the –> indicator. A quick example is “Text->a”. This can be referred to later on. To use a variable that was stored to in the expression, use #name, where name is the name of the variable to return. Finally, to use a variable that exists globally or statically, use the * indicator. Finally, you can use string literals by escaping the double quotes or using single quotes. Below is an example of all of these being used in one expression:

alert(Awesome.EvalBind("Text->a.Href->b.*String.Format(\"{0} - {1}!\", #a, #b)", $Anchor("A1")));

This expression seems pretty complicated, so lets break this down. First off, we will be evaluating on the Anchor named “A1”. The first thing we will retrieve is its Text property and store it to a variable named “a”. Next, we will retrieve the Href of the anchor and store it to the variable “b”. Next, we want to refer to a static variable, String, so we can use the String.Format. So we use “*String” to bring this object into view, meaning we’re now evaluating the String static object, not the anchor.

This is not a special case, instead, every time a section  separated by a “.” is evaluated, that value returned becomes the object “in focus”. For the Text->a part, we’re storing the value so the anchor remains in focus, same with Href->b. If you think about the previous examples, such as “Text.length”, Text returns a string for a value and that because the object in focus, then we can call length on the string to get the full value.

Now that we have the String static object, we can access the Format function, passing a format expression being used as normal. However, we want to pass in the Text and Href we retrieved earlier to the Format function, so we refer to these variables with “#”. If we leave out the “#”, then the  evaluation will try to resolve “a” and “b” to the current object in focus (in this case, the static String object). After the expression is fully evaluated, it will return the text and href separated by a – and ending with a !, such as “Click here – www.google.com!”

To use a literal value without any evaluation, use the $, such as Awesome.EvalBind(“Text.Substring($0, $5)”, $Anchor(“A1”)) which will return the first 4 characters of the text inside of the anchor “A1”.

Real World Example

AwesomeQuery lets you pull subsets of objects from an array using a QueryClause by calling From(_array). You can select only specific properties from the items in the array by calling Select(“property here”). The Select function allows for normal binding expression.

<a href="google.com">Google</a>
<a href="yahoo.com">Yahoo!</a>
<a href="bing.com">Bing</a>
<script type="text/javascript">
    Page.OnLoad.Add(function () {
            alert(From(Page.Query("a")).Select("Text.ToUpper()"));
        });
</script>

 This function simply selects all the anchors on the page. The From function creates a QueryClause on the returned set of HTML objects. Select will then select the “Text” property on all of the anchors and call ToUpper on them, return them as an array of strings. The end result in this is “GOOGLE, YAHOO!, BING” in the alert.

On one last note, you can use a number to refer to items as if it were an array or string. Replacing “ToUpper()” in the example above with “0” so that it reads “Text.0” will result in return “G, Y, B” since 0 is the first character in each of the returned strings.

Controls such as the GridView, along with the AwesomeBinding extension, make use of the binding expression to allow you to pull values from objects without having to manually set the values.

String.BindFormat

String.BindFormat makes use of binding expressions to pull values out of an object. Below is an example:

    alert(String.BindFormat("{Text} - {Href}!", $Anchor("A1")));

 

This function follows all the rules of the binding expressions, replacing each token found with {} with the values evaluated from the expressions between them. This will return the same value as seen above, such as “Click here – www.google.com!”.

Last edited Sep 19, 2011 at 1:58 PM by dahrkdaiz, version 5

Comments

No comments yet.