Atlas Client Controls

In Chapters 2 and 3, you learned the basics of JavaScript and key Ajax technologies, especially asynchronous calls, that support it. As you saw, Ajax itself is no big deal. The effects that Atlas lets you create are possible without Atlas. Everything you do with Atlas creates HTML, CSS, and JavaScript on the client side, which is also possible with any other server-side technology.

The real value of Atlas is that it greatly facilitates development of Ajax-powered applications. Although you can create applications without it, Atlas can make their implementation go faster. Also, with Atlas, your need to master browser-agnostic JavaScript is not a top priority, though, as is always the case, having such skills will give you a much better understanding of how Atlas works its magic.

This chapter covers client-side controls that ship with Atlas and mimic the behavior of ASP.NET web controls. This not only allows for consistent development on both the server and the client, but also supports convenient features like data binding, which you’ll explore in Chapter 5.

Atlas implements its client controls in the Sys.UInamespace.Sys.UIis the client-side equivalent of the similarly named and well-knownWeb.UInamespace in ASP.NET.

In older Atlas releases, the client-side namespace was namedWeb.UI, as well.

Sys.UIcontains a large number of Atlas HTML controls and web controls. The functionality of Atlas controls is similar but not identical to ASP.NET server controls. Atlas controls provide a consistent, browser-independent model that enables JavaScript code to access and change client controls properties, something that with non-Atlas controls would require quite a bit of JavaScript knowledge as well as some workarounds for browser inconsistencies.

Table 4-1 lists controls provided by Atlas. The table lists the HTML elements that the Atlas control works with and the equivalent DOM object or method that you would use in JavaScript.

Table 4-1. Atlas controls

Using Atlas Controls

There are two concepts the Atlas framework uses with the controls in Sys.UI. Some of these controls provide JavaScript access to standard JavaScript methods. The others provide JavaScript access to HTML elements on the current page. Both ways are demonstrated in this section.

Accessing JavaScript Methods

One example of the first method is implemented by Sys.UI.Window. This implements a client-side message box. The JavaScript language supports three types of modal message boxes:

window.alert()
   Message box with an OK button

window.confirm()
   Message box with OK/Cancel or Yes/No buttons

window.prompt()
   Message box with an input field and an OK button

Inside the AtlasSys.UI.Windowclass, the functionality for callingwindow.alert()orwindow.confirm()is encapsulated in themessageBox()method. The default behavior is to present awindow.alert()box. This corresponds to the message box styleSys.UI.MessageBoxStyle.OK. The alternative is to use theSys.UI.MessageBoxStyle.OKCancelstyle, which useswindow.confirm()under the covers.

But what about thewindow.prompt()window? For consistency with Visual Basic, this is implemented via theinputBox()method instead of themessageBox()method.

The followingexample implements all three variants of client modal window. Three client-side buttons are in place for calling the Atlas functionality:

  <input type="button" value="MessageBoxOK" onclick="MessageBoxOKClick();" />
  <input type="button" value="MessageBoxOKCancel"
  onclick="MessageBoxOKCancelClick();" />
  <input type="button" value="InputBox" onclick="InputBoxClick();" />

Each of the three functions—click1(),click2(), andclick3()—call an Atlas method, as shown in the following code:

  <script language="JavaScript" type="text/javascript">
  function MessageBoxOKClick() {
    Sys.UI.Window.messageBox("Using Sys.UI.Window");
  }

  function MessageBoxOKCancelClick() {
    Sys.UI.Window.messageBox("Using Sys.UI.Window", Sys.UI.MessageBoxStyle.  
  OKCancel);
  }

  function InputBoxClick() {
    Sys.UI.Window.inputBox("Using Sys.UI.Window", "<enter text here>");
  }
  </script>

To use Atlas functionality in a page, you must include the Atlas library. The AtlasScriptManager element takes care of that:

  <atlas:ScriptManager runat="server"></atlas:ScriptManager>

Example 4-1 shows the code you need for your first Atlas example in this chapter.

Example 4-1. Modal JavaScript windows with Atlas

ControlMessageBox.aspx

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"> <head runat="server">
  <title>Atlas</title>

  <script language="JavaScript" type="text/javascript">
  function MessageBoxOKClick() {
    Sys.UI.Window.messageBox("Using Sys.UI.Window");
  }

  function MessageBoxOKCancelClick() {
    Sys.UI.Window.messageBox("Using Sys.UI.Window", Sys.UI.MessageBoxStyle. OKCancel);
  }

  function InputBoxClick() {
    Sys.UI.Window.inputBox("Using Sys.UI.Window", "<enter text here>");
  }
  </script>

</head>
<body>
  <form id="form1" runat="server">
    <atlas:ScriptManager runat="server">
    </atlas:ScriptManager>
    <div>
      <input type="button" value="MessageBoxOK" onclick="MessageBoxOKClick();" /
>
      <input type="button" value="MessageBoxOKCancel" onclick="MessageBoxOKCancelClick();" />
      <input type="button" value="InputBox" onclick="InputBoxClick();" />
    </div>
  </form>
</body>
</html>

Figure 4-1 shows the result when you click the InputBox button.

Figure 4-1.  Clicking a button opens a JavaScript window

This is nice functionality, but not yet of real value, since only very basic JavaScript functionality is encapsulated by the Atlas controls you are using. However, there are other controls with actual real-world use.

Accessing HTML Elements

Atlas controls also enable you to put HTML controls in the page and then access them usingan object-oriented, client-side approach. So although you are using HTML elements, you can use a client-side abstraction layer to access their contents.

The syntax for using Atlas to access HTML elements can seem a bit strange at first. Imagine the page contains a<span>element like the following:

  <span id="Label1">This is a label</span>

You could also use a<label>HTML element; however, this is most commonly used as a caption element for form fields, although the output in the browser is identical to a<span>element.

If you were using plain old JavaScript, you could access this element with the following code:

  var label = document.getElementById("Label1")

You could then set some properties of this element, including style information. However, the exact JavaScript you use would be different on different browsers, and you have to have a fairly good knowledge of JavaScript and the DOM, beyond just mastering the syntax.

The Atlas way is different. First, you have to determine the appropriate Atlas control class for the client-side element. (These are listed in Table 4-1.) For the<span>element, you useSys.UI.Label. The code must instantiate the class and provide the ID of the HTML element. However this ID will be specified in a nonstandard way: startingwith a dollar sign, and with the actual ID in parentheses:

  var label = new Sys.UI.Label($("Label1"));

The next step is not mandatory in this specific example, but it is in most other scenarios and is therefore generally recommended: calling theinitialize()method. This method registers delegates and event handlers so that you can set such properties. If you do not use event handling(as in the next few examples), calling theinitialize()method can be skipped:

  label.initialize();

Finally, you can call the methods that get and set the properties that these elements provide. Table 4-2 lists the most commonly used class members. More information about these common methods is provided later in the chapter. In addition, the sections that follow describe methods that are unique to each Atlas control class.

Table 4-2. Standard Atlas methods for setting HTML element properties

Table 4-2. Standard Atlas methods for setting HTML element properties (continued)

As you can see, a lot of the relevant style information about an element on a page can be set using the abstraction layer Atlas is providing.

Labels

For the Atlas Label control, Atlas supports the two following additional methods, which are both shown in Example 4-2.

get_text()
   Retrieves the current text of the element

set_text()
   Sets (changes) the text in the element

Remember that JavaScript and the browser DOM do not offer an equivalent to ASP.NET’sInnerTextproperty. The property that bothget_text()andset_text()are accessing isinnerHTML, so you always have to consider escaping special characters to avoid side effects. This will be covered in Chapter 5.

Example 4-2 does three things:

1. It creates the client-sideSys.UI.Labelobject.
   
2. It reads the old text using theget_text()method.
   
3. It writes new text using theset_text()method.

Example 4-2. Using an Atlas Label control

ControlLabel.aspx

<%@ Page Language="C#" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head runat="server">
  <title>Atlas</title>

  <script language="JavaScript" type="text/javascript">
  window.onload = function(){
    var label = new Sys.UI.Label($("Label1"));
    var d = new Date();
    var time = d.getHours() + ":" + d.getMinutes() + ":" + d.getSeconds();
    label.set_text(label.get_text() + time);
  }
  </script>

</head>
<body>

  <form id="form1" runat="server">
    <atlas:ScriptManager runat="server">
    </atlas:ScriptManager>
    <div>
      <span id="Label1">time goes here: </span>
    </div>
  </form>
</body>
</html>

After the page loads, the current time is determined and then put in the<span>element. Figure 4-2 shows the result.

Figure 4-2.  The current time appears in the label

In ordinary JavaScript programming, you setwindow.onloadto an anonymous JavaScript function to be sure that code will be executed only when the HTML markup in the page has been fully loaded. To simplify this, Atlas comes with a convenient feature: if you call an Atlas function namedpageLoad(), the function will execute when the page’sloadevent occurs, first guaranteeing that the Atlas framework has been completely loaded and initialized.

Please check back next week for the continuation of this article.