Java Server Pages, Java Programming - Cheap Web Hosting Blog

370Part IIIDocument Objects Referencesubjects that extend well beyond the scope of this book. You can begin to explore this sub- ject within the context of Mozilla-based browsers and scripting athttp://www.mozilla.org/scriptable/. clientInformationValue:navigator object.Read-OnlyCompatibility:WinIE4+, MacIE4+, NN-, Moz-, Safari- In an effort to provide scriptable access to browser-level properties while avoiding referenceto the Navigator browser brand, Microsoft provides the clientInformationproperty. Itsvalue is identical to that of the navigatorobject an object name that is also available in IE. Use the navigatorobject for cross-browser applications. (See Chapter 38 on the CD-ROM.) Related Items:navigatorobject. clipboardDataValue:Object.Read/WriteCompatibility:WinIE5+, MacIE-, NN-, Moz-, Safari- Use the clipboardDataobject to transfer data for such actions as cutting, copying, and past- ing under script control. The object contains data of one or more data types associated witha transfer operation. Use this property only when editing processes via the Edit menu (orkeyboard equivalents) or context menu controlled by script typically in concert with edit- related event handlers. Working with the clipboardDataobject requires knowing about its three methods, shown inTable 16-1. Familiarity with the edit-related event handlers ( before and after versions ofcut, copy, and paste) is also helpful (see Chapter 15). Table 16-1: window.clipboardData Object MethodsMethodReturnsDescriptionclearData([format])NothingRemoves data from the clipboard. If no formatparameter is supplied, all data is cleared. Dataformats can be one or more of the following strings: Text, URL, File, HTML, Image. getData(format)StringRetrieves data of the specified format from theclipboard. The format is one of the following strings: Text, URL, File, HTML, Image. The clipboard is notemptied when you get the data, so that the data canbe retrieved in several sequential operations. setData(format, data)BooleanStores string data in the clipboard. The format is oneof the following strings: Text, URL, File, HTML, Image. For non-text data formats, the data must bea string that specifies the path or URL to the content. Returns trueif the transfer to the clipboard issuccessful. windowObject.appCore

369Chapter 16Window and Frame ObjectsWindow properties are far more flexible on all browsers when your scripts generate a newwindow (with the window.open()method): You can influence the size, toolbar, or other viewoptions of a window. Recent browser versions provide even more options for new windows, including the position of the window and whether the window should even display a title bar. Again, if an option can conceivably be used to deceive a user (for example, silently hiding onewindow that monitors activity in another window), signed scripts and/or user permission arenecessary. The windowobject is also the level at which a script asks the browser to display any of threestyles of dialog boxes (a plain alert dialog box, an OK/Cancel confirmation dialog box, or aprompt for user text entry). Although dialog boxes are extremely helpful for cobblingtogether debugging tools for your own use (see Chapter 45 on the CD-ROM), they can be verydisruptive to visitors who navigate through Web sites. Because most JavaScript dialog boxesare modal (that is, you cannot do anything else in the browser until you dismiss the dialogbox), use them sparingly, if at all. Remember that some users may create macros on theircomputers to visit sites unattended. Should such an automated access of your site encountera modal dialog box, it is trapped on your page until a human intervenes. All dialog boxes generated by JavaScript identify themselves as being generated byJavaScript. This is primarily a security feature to prevent deceitful scripts from creating sys- tem- or application-style dialog boxes that convince visitors to enter private information. Itshould also discourage dialog box usage in Web page design. And that s good, because dialogboxes tend to annoy users. With the exception of the IE-specific modal and modeless dialog boxes (see the window.showModalDialog()and window.showModeless()methods), JavaScript dialog boxes arenot particularly flexible in letting you fill them with text or graphic elements beyond the basics. In fact, you can t even change the text of the dialog box buttons or add a button. With DHTML- capable browsers, you can use positioned divor iframeelements to simulate dialog boxbehavior in a cross-browser way. With respect to the W3C DOM, the window is outside the scope of the standard throughDOMLevel 2. The closest that the standard comes to acknowledging a window at all is thedocument.defaultViewproperty, which evaluates to the windowobject in today s browsers(predominantly Mozilla). But the formal DOM standard specifies no properties or methodsforthis view object. PropertiesappCoreComponents[] controllers[] promptersidebarValues:See text.Read-OnlyCompatibility:WinIE-, MacIE-, NN6+, Moz1+, Safari- NN6+/Mozilla provides scriptable access to numerous services that are part of the xpconnectpackage ( xp stands for cross-platform ). These services allow scripts to work with COMobjects and the mozilla.org XUL (XML-based User Interface Language) facilities lengthywindowObject.appCore

368Part IIIDocument Objects ReferenceSyntaxCreating a window: var windowObject = window.open([parameters]); Accessing window properties or methods: window.property| method([parameters]) self.property| method([parameters]) windowObject.property | method([parameters]) Compatibility:WinIE3+, MacIE3+, NN2+, Moz1+, Safari1+ About this objectThe windowobject has the unique position of being at the top of the object hierarchy, encom- passing even the almighty documentobject. This exalted position gives the windowobject anumber of properties and behaviors unlike those of any other object. Chief among its unique characteristics is that because everything takes place in a window, you can usually omit the windowobject from object references. You ve seen this behavior inprevious chapters when I invoked document methods, such as document.write(). The com- plete reference is window.document.write(). But because the activity was taking place inthe window that held the document running the script, that window was assumed to be partof the reference. For single-frame windows, this concept is simple enough to grasp. As previously stated, among the list of properties for the windowobject is one called self. This property is synonymous with the windowobject itself (which is why it shows up in hier- archy diagrams as an object). Having a property of an object that is the same name as theobject may sound confusing, but this situation is not that uncommon in object-oriented envi- ronments. I discuss the reasons why you may want to use the selfproperty as the window sobject reference in the selfproperty description that follows. As indicated earlier in the syntax definition, you don t always have to specifically create awindowobject in JavaScript code. After you start your browser, it usually opens a window. That window is a valid windowobject, even if the window is blank. Therefore, after a userloads your page into the browser, the windowobject part of that document is automaticallycreated for your script to access as it pleases. One conceptual trap to avoid is believing that a windowobject s event handler or customproperty assignments outlive the document whose scripts make the assignments. Except forsome obvious physical properties of a window, each new document that loads into the win- dow starts with a clean slate of window properties and event handlers. Your script s control over an existing (already open) window s user interface elements varieswidely with the browser and browser version for which your application is intended. Beforethe version 4 browsers, the only change you can make to an open window is to the status lineat the bottom of the browser window. With IE4+ and NN4+, however, you can control suchproperties as the size, location, and (with signed scripts in Navigator and Mozilla) the pres- ence of chrome elements (toolbars and scrollbars, for example) on the fly. Many of theseproperties can be changed beyond specific safe limits only if you cryptographically sign thescripts (see Chapter 46 on the CD-ROM) and/or the user grants permission for your scripts tomake those modifications. window

367Chapter 16Window and Frame ObjectsPropertiesMethodsEvent Handlersframes[]moveBy()onmouseout historymoveTo()onmouseover innerHeightnavigate()onmouseup innerWidthopen()onmovelengthprint()onreset loadingprompt()onresizelocationreleaseEvents()onscrolllocationbarresizeBy()onselect menubarresizeTo()onsubmit namerouteEvent()onunloadnavigatorscroll() offscreenBufferingscrollBy() openerscrollTo() outerHeightsetActive() outerWidthsetInterval() pageXOffsetsetTimeout() pageYOffsetshowHelp() parentshowModalDialog() personalbarshowModelessDialog() pkcs11sizeToContent() prompterstop() returnValuescreenscreenLeft screenTop screenX screenYscrollbarsscrollMaxXscrollMaxYscrollXscrollYselfsidebarstatusstatusbartoolbartopwindow See Chapter 15. To handle captured or bubbled events of other objects in IE4+ and W3C DOM browserswindow

366Part IIIDocument Objects ReferenceBut when the object model also exposes HTML elements, the notion of the frameelementobject is somewhat distinct from the frame object of the original model. The frameelementobject represents an object whose properties are dominated by the attributes you set insidethe tag. This provides access to settings, such as the frame border andscrollability the kinds of properties that are not exposed to the original frame object. References to the frame and frameelement objects are also different. You ve seen plenty ofexamples of how to reference an old-fashioned frame earlier in this chapter. But access to aframeelement object is either via the element s idattribute or through the child node rela- tionship of the enclosing framesetelement (you cannot use the parentNodeproperty toback your way out of the current document to the frameelement that encloses the docu- ment). The way I prefer is to assign an idattribute to tags and access the frameele- ment object by way of the documentobject that lives in the parent (or top) of the framesethierarchy. Therefore, to access the frameBorderproperty of a frameelement object from ascript living in any frame of a frameset, the syntax isparent.document.all.frame1ID.frameBorderor, for IE5+/NN6+/W3Cparent.document.getElementById( frame1ID ).frameBorderWhen the reference goes through the frameelement object you can still reach the documentobject in that frame via the element object s contentWindowor contentDocumentproperties(see the frameelement object later in this chapter). window ObjectPropertiesMethodsEvent HandlersappCorealert()onabort clientInformationattachEvent() onafterprintclipboardDataback()onbeforeprintclosedblur() onbeforeunloadcomponents[]captureEvents()onblur controllers[]clearInterval()onchange cryptoclearTimeout()onclick defaultStatusclose()onclose dialogArgumentsconfirm()ondragdropdialogHeightcreatePopup()onerrordialogLeftdetachEvent() onfocus dialogTopexecScript()onhelpdialogWidthfind()onkeydown directoriesfireEvent() onkeypress documentfocus() onkeyup eventforward()onloadexternalhandleEvent()onmousedown frameElementhome()onmousemove window

365Chapter 16Window and Frame ObjectsDespite the horrible WinIE4+ bug just described , it is best to construct the code so that theparent s onloadevent handler triggers all the scripts that you want to run after loading. Youshould also test your pages thoroughly for any residual effects that may accrue if someoneresizes a window or clicks Reload. Blank framesOften, you may find it desirable to create a frame in a frameset but not put any document in ituntil the user has interacted with various controls or other user interface elements in otherframes. Most modern browsers have a somewhat empty document in one of their internalURLs (about:blank). However, this URL is not guaranteed to be available on all browsers. Ifyou need a blank frame, let your framesetting document write a generic HTML document tothe frame directly from the srcattribute for the frame, as shown in the skeletal code inListing 16-3. Loading an empty HTML document requires no additional transactions. Listing 16-3: Creating a Blank Frame Viewing frame source codeStudying other scripters work is a major learning tool for JavaScript (or any programminglanguage). With most scriptable browsers you can easily view the source code for any frame, including those frames whose content is generated entirely or in part by JavaScript. Click thedesired frame to activate it (a subtle border may appear just inside the frame on somebrowser versions, but don t be alarmed if the border doesn t appear). Then select FrameSource (or equivalent) from the View menu (or right-click submenu). You can also print orsave a selected frame. Frames versus frame element objectsWith the expansion of object models that expose every HTML element to scripting (IE4+ andW3C DOM compatible browsers), a terminology conflict comes into play. Everything that youhave read about frames thus far in the chapter refers to the original object model, where aframe is just another kind of window, with a slightly different referencing approach. That stillholds true, even in the latest browsers.

364Part IIIDocument Objects ReferenceSwitching from frames to framelessSome sites load themselves in a frameset by default and offer users the option of getting ridof the frames. Only IE4+ and W3C browsers let you modify a frameset s colsor rowsproper- ties on the fly to simulate adding or removing frames from the current view (see the frame- setelement object later in this chapter). In other browsers, you cannot dynamically changethe makeup of a frameset after it has loaded, but you can load the content page of the frame- set into the main window. Simply include a button or link whose action loads that documentinto the topwindow object: top.location.href = mainBody.html ; A switch back to the frame version entails nothing more complicated than loading the frame- setting document. Inheritance versus containmentScripters who have experience in object-oriented programming environments probablyexpect frames to inherit properties, methods, functions, and variables defined in a parentobject. That s not the case with scriptable browsers. You can, however, still access those par- ent items when you make a call to the item with a complete reference to the parent. For exam- ple, if you want to define a deferred function in the framesetting parent document that allframes can share, the scripts in the frames refer to that function with this reference: parent.myFunc() You can pass arguments to such functions and expect returned values. Frame synchronizationA pesky problem for some scripters plans is that including immediate scripts in the frameset- ting document is dangerous. Such scripts tend to rely on the presence of documents in theframes being created by this framesetting document. But if the frames have not yet been cre- ated and their documents have not yet loaded, the immediate scripts will likely crash andburn. One way to guard against this problem is to trigger all such scripts from the frameset sonloadevent handler. In theory, this handler won t trigger until all documents have success- fully loaded into the child frames defined by the frameset. Unfortunately, IE4+ for Windowshas a nasty bug that fires the onloadevent handler in the frameset even if the loading hasbeen interrupted by the browser s Stop button or a press of the Esc key. At the same time, becareful with onloadevent handlers in the documents going into a frameset s frames. If one ofthose scripts relies on the presence of a document in another frame (one of its brothers orsisters), you re doomed to eventual failure. Anything coming from a slow network or serverto a slow modem can get in the way of other documents loading into frames in the idealorder. One way to work around these problems is to create a Boolean variable in the parent docu- ment to act as a flag for the successful loading of subsidiary frames. When a document loadsinto a frame, its onloadevent handler can set that flag to trueto indicate that the documenthas loaded. Any script that relies on a page being loaded should use an ifconstruction totest the value of that flag before proceeding.

363Chapter 16Window and Frame ObjectsListing 16-1: Prevention from Getting Framed Your document may appear momentarily inside the other site s frameset, but then the slate iswiped clean, and your top-level document rules the browser window. Ensuring framingWhen you design a Web application around a frameset, you may want to make sure that apage always loads the complete frameset. Consider the possibility that a visitor adds onlyone of your frames to a bookmarks list. On the next visit, only the bookmarked page appearsin the browser, without your frameset, which may contain valuable navigation aids to the site. A script can make sure that a page always loads into its frameset by comparing the URLs ofthe topand selfwindows. If the URLs are the same, it means that the page needs to load theframeset. Listing 16-2 shows the simplest version of this technique, which loads a fixed frame- set. The listing includes a workaround for an NN4-specific behavior that prevents printing aframe. (NN4 for Windows and UNIX reloads a page into a separate hidden window for printingand runs any immediate scripts in the process.) For a more complete implementation thatpasses a parameter to the frameset so that it opens a specific page in one of the frames, seethe location.searchproperty in Chapter 17. Listing 16-2: Forcing a Frameset to Load

362Part IIIDocument Objects ReferenceReferencing framesThe purpose of an object reference is to help JavaScript locate the desired object in theobject model currently held in memory. A reference is a road map for the browser to follow, so that it can track down, say, the value of a particular text field in a particular document. Therefore, when you construct a reference, think about where the script appears in theobject model and how the reference can help the browser determine where it should go tofind the distant object. In a two-generation scenario, such as the one shown in Figure 16-2, three intergenerational references are possible: .Parent-to-child .Child-to-parent .Child-to-childAssuming that you need to access an object, function, or variable in the relative s frame, thefollowing are the corresponding reference structures: frameName.objFuncVarName; parent.objFuncVarName; parent.frameName.objFuncVarName. The rule is this: Whenever a reference must point to another frame, begin the reference withthe windowobject that the two destinations have in common. To demonstrate that rule onthe complex model in Figure 16-3, if the left-hand child frame s document needs to referencethe document at the bottom right of the map, the reference structure istop.frameName.frameName.document. … Follow the map from the top windowobject down through two frames to the final document. JavaScript has to take this route, so your reference must help it along. Top versus parentAfter seeing the previous object maps and reference examples, you may be wondering, Whynot use topas the leading object in all trans-frame references? From an object model point ofview, you ll have no problem doing that: A parent in a two-generation scenario is also the topwindow. What you can t count on, however, is your framesetting document always being thetopwindow object in someone s browser. Take the instance where a Web site loads otherWeb sites into one of its frames. At that instant, the topwindow object belongs to someoneelse. If you always specify topin references intended just for your parent window, your refer- ences won t work and will probably lead to script errors for the user. My advice, then, is touse parentin references whenever you mean one generation above the current document. Preventing framingYou can use your knowledge of topand parentreferences to prevent your pages from beingdisplayed inside another Web site s frameset. Your top-level document must check whether itis loaded into its own top or parent window. When a document is in its own top window, a ref- erence to the topproperty of the current window is equal to a reference to the current win- dow (the windowsynonym selfseems most grammatically fitting here). If the two values arenot equal, you can script your document to reload itself as a top-level document. When it iscritical that your document be a top-level document, include the script in Listing 16-1 in theHead portion of your document:

361Chapter 16Window and Frame ObjectsFigure 16-2:The parent and frames are partof the object model. Each tag inside the tag set creates another windowobject into which adocument is loaded. Each of those frames, then, has a documentobject associated with it. From the point of view of a given document, it has a single window container, just as in themodel shown in Figure 16-1. And although the parentobject is not visible to the user, itremains in the object model in memory. The presence of the parent often makes it a conve- nient repository for variable data that need to be shared by multiple child frames or mustpersist between loading of different documents inside a child frame. In even more complex arrangements, as shown in Figure 16-3, a child frame itself may load aframesetting document. In this situation, the difference between the parentand topobjectsstarts to come into focus. The top window is the only one in common with all frames in Figure16-3. As you see in a moment, when frames need to communicate with other frames (andtheir documents), you must fashion references to the distant object via the windowobjectthat they all have in common. Figure 16-3:Three generations ofwindow objects. TopParentChildFrameDocumentChildFrameChildFrameDocumentChild FrameParent DocumentTopParentTopParentDocumentDocumentTopParent