Section 4.2. Using Atlas Controls
4.2. Using Atlas ControlsThere 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. 4.2.1. Accessing JavaScript MethodsOne 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:
Inside the Atlas Sys.UI.Window class, the functionality for calling window.alert() or window.confirm() is encapsulated in the messageBox() method. The default behavior is to present a window.alert() box. This corresponds to the message box style Sys.UI.MessageBoxStyle.OK. The alternative is to use the Sys.UI.MessageBoxStyle.OKCancel style, which uses window.confirm() under the covers. But what about the window.prompt() window? For consistency with Visual Basic, this is implemented via the inputBox() method instead of the messageBox() method. The following example 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 functionsclick1(), click2(), and click3()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 Atlas ScriptManager 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
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. 4.2.2. Accessing HTML ElementsAtlas controls also enable you to put HTML controls in the page and then access them using an 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 >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 use Sys.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: starting with 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 the initialize() 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 the initialize() 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.
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. 4.2.3. LabelsFor the Atlas Label control, Atlas supports the two following additional methods, which are both shown in Example 4-2.
Example 4-2 does three things:
Example 4-2. Using an Atlas Label control
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
4.2.4. ImagesThe HTML <img> element represents an image on the page. The Sys.UI.Image class implements an Atlas version of a client-side image (represented in the DOM with the Image object). In addition to the common methods listed earlier in this chapter, the Atlas Image class supports the following methods:
Once again, standard DOM properties are encapsulated in a class. You don't have to learn much JavaScript, just get accustomed to the methods that Atlas exposes. Example 4-3 shows you how to manipulate the empty <img> element on the page, which initially looks like this: <img /> By default, the XHTML validation in Visual Studio will complain about missing attributes, but you will be using JavaScript code to set the required src and alt attributes. Example 4-3. Using an Atlas Image control
Figure 4-3 shows the result. For this example to work, you need the file atlaslogo.gif in the root directory of the web site; you will find the file in the code downloads for this book (http://www.oreilly.com/catalog/atlas). Figure 4-3. The Image control; the Properties window shows the alternate text 4.2.5. HyperlinksIn HTML, the <a> element is used to link to other pages and to documents, and it is also for bookmarks. In Atlas, hyperlinks are represented with the Sys.UI.HyperLink class. This class implements the get_navigateURL() and set_navigateURL() methods for setting the link target (only the target URL, not the target frame or window). It also provides a click event, which can be acted upon. (Event handling is covered later in this chapter in the "Handling Control Events" section.) In Example 4-4, an empty link (<a></a>) is created, and a link target is added dynamically. In the example, the link is the same Atlas logo image that you used in the preceding example. It is not possible to directly set the text of the link. A link might not necessarily be a text link, but could also contain an image or another element. Therefore, the text of the link can be thought of as another object, and if you want to set the link text, you have to put another element (with ID) inside the link. Example 4-4. Using an Atlas Link control
Figure 4-4 shows the result. Figure 4-4. An Image control is now a hyperlink 4.2.6. ButtonsHTML supports various kinds of buttons, e.g., <input type="submit"> to submit a form, <input type="reset"> to clear a form (reset it to its original state), and <input type="button"> and <button> for a button with no predefined behavior that can be enriched with JavaScript. Atlas implements buttons (<input type="button"> or <button>, i.e., buttons that cannot serve any purpose without JavaScript) with Sys.UI.Button. The following methods are supported:
Whenever you set the argument or command, the built-in event handling mechanism is started. A different approach for binding functionality to buttons can be found in Chapter 6. 4.2.7. CheckboxesHTML uses <input type="checkbox"> for checkboxes. A checkbox has only two states: checked or not checked. These states can be set using JavaScript, so Atlas provides this functionality as well. The set_checked() method can change the state of a checkbox (by providing a Boolean value), and get_checked() retrieves the current state. The associated class is Sys.UI.CheckBox. Example 4-5 uses HTML to create a checkbox, and Atlas/JavaScript to set its checked state to true. Example 4-5. Using an Atlas CheckBox control
Figure 4-5 shows the result displayed. Figure 4-5. Atlas has checked the checkbox 4.2.8. Selection ListsHTML selection lists (<select>...</select>) can come in different forms: a drop-down list where the user has to click to see all list elements, or a selection list where some of the elements are already visible. Both types of lists 78re covered by Atlas with the Sys.UI.Select class. Unlike using JavaScript to work with a <select> element, the ability to set the individual values of the list's elements is not provided by the Atlas classes.
But we can demonstrate the get_selectedValue() method, which determines the value attribute of the currently selected item in the list.
Since event handling isn't covered until later in this chapter, in Example 4-6, the change event of the list is not captured, and instead the state of the list is analyzed every second. This is done using the setInterval() JavaScript function. This polling technique is used only for the sake of the example here; Chapter 5 will cover a much better way to keep two elements in sync, namely through the use of data binding. function pageLoad() { window.setInterval( function() { //access the list and output its selected value }, 1000); } Example 4-6 shows how to use Atlas to check for a current selection and display the selection value in a <span> element (Sys.UI.Label). Example 4-6. Using an Atlas Select control
Figure 4-6 shows the result. Figure 4-6. The selected value is written to the Label control
4.2.9. Text FieldsA single-line text box is represented in HTML using <input type="text">. This element can also be monitored and controlled using the Atlas library and the appropriate class for it, Sys.UI.TextBox. The functionality provided by Atlas covers keyboard event handling and, of course, both read and write access for the text of the element itself. The methods for the latter task are get_text() and set_text(). Example 4-7 outputs the data entered into the text field, using the same polling approach as in the preceding example (setInterval()) to periodically copy the contents of the text box to an Atlas Label control. Example 4-7. Using an Atlas TextBox control
Figure 4-7 shows the result. Figure 4-7. The text in the text box appears in the label
4.2.10. Base MethodsAs discussed earlier in "Introducing Atlas Client Controls," Atlas supports common methods for each control within Sys.UI. Most of these set some property that JavaScript exposes for all controls. Two examples of this are the get_accessKey() and set_accessKey() methods that control the DOM accesskey property. Methods with somewhat more visible results are those for controlling the CSS class of an element. This makes changing the layout of elements on the fly very easy. Here are the methods that are supported:
Example 4-8 demonstrates the toggleClassClass() method, which internally uses addCssClass(), containsCssClass(), and removeCssClass(). The example also uses the get_cssClass() method. In the page, the following three CSS classes are defined that can complement each other (i.e., every class covers another style). <style type="text/css"> .style1 { font-family: Monospace; } .style2 { border-style: solid; } .style3 { color: #00f; } </style> The JavaScript code in the example selects one of these classes at random and then calls toggleCssClass(). A Label control periodically displays the current class or classes being used. Example 4-8. Using the base CSS methods for Atlas controls
Figure 4-8 shows the result. Figure 4-8. Two styles were applied at random |
