Reference Functions


A reference function is any function that takes an id or an object and returns a “pseudo” strong type of an object. All reference functions start with a dollar sign ($) and follow by the type. Reference functions are mostly syntax sugar for document.getElementById() except when Awesome.DeobfuscateIds is set to true (which it is by default). When this is set, whatever Awesome.ObfuscationCharacter is set to (default is “_”) will be used to split an id and create reference synonyms. For example take the id “ctl00_content01_MyText”. You can reference the element by using $Element(“MyText”) or $Element(“content01_MyText”) or $Element(“ctl00_content01_MyText”). This is because ASP.NET tends to obfuscate ids in order to guarantee unique ids among controls. Because of this, however, ids with similar ids have the potential of causing problems, such as “01_MyText” and “02_MyText”. Trying to use $Element(“MyText”) will return the last element that contains “MyText” as part of the underscore split id. In practice, using good, distinct ids has proven to avoid any such problems.

You can turn this feature off by setting Awesome.DeobfuscatedIds to false. Then, all reference ids are absolute. This also speeds up the Build very slightly.


Elemental References

Elemental references, as discussed, is a wrapper for document.getElementById function using id synonyms. However, with Intellisense in Visual Studio, using a specific reference function will tell the code reader, and more importantly the programmer, that you are dealing with an element of a certain type. Intellisense will reveal functions, properties and fields that can be used for that specific type. The very basic reference function is $Element(). $Element will reference any element and shows functions and properties that are given to nearly all elements, such as BackgroundColor, Width and Style. Using a specific elemental reference function such as $Anchor will show all functions, properties and fields for the basic Element and those specific to the Anchor.

Besides $Element, there is also $Content and $Input which treats an element as content or an input field. Since all of the reference functions are a wrapper function over the same thing, effectively calling $Anchor() is the same as $TextBox(), but it’s easy to read if you know what element type you are dealing with and the Intellisense makes productivity a bit higher.  Here’s an example below:


<a href="MyAnchor">Test<a/>
<script type="text/javascript">


These essentially do the exact same thing. However, just because Intellisense shows properties, functions, events, etc of a referenced type doesn’t mean that the element is given this. For example, having a textbox with an id “MyText” and calling $Anchor(“MyText”).Href(“”) will throw an error because under the hood, “MyText” is a textbox, no matter how you want to treat it.


Object References

Object references are purely a syntax sugar ordeal. They help with Intellisense and code readability, but under the hood, they simply return the passed in object. They exist specifically for passed in parameters, which are typeless. You can assign a parameter to a reference function to itself so that further along in the code, you will get Intellisense for what it is. Below is an example:

function combineArrays(array1, array2){
    array1 = $Array(array1);
    array2 = $Array(array2);


After the first two lines, when you type array1 and hit “.”, you will be shown that you have a ForEach loop. Inside of the ForEach’s anonymous function, typing in array2 and hitting “,” will show you  have an Add function. While it doesn’t really do anything in the code, it makes for much more maintainable code and easier to read.

Last edited Mar 26, 2011 at 3:46 PM by dahrkdaiz, version 1


No comments yet.