Java Server Pages, Java Programming - Cheap Web Hosting Blog

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

360Part IIIDocument Objects Referencehave a document that requires considerable scrolling to get through, you may want to main- tain a static set of navigation controls visible at all times. By placing those controls be theylinks or image maps in a separate frame, you have made the controls available for immedi- ate access, regardless of the scrolled condition of the main document. Creating framesThe task of defining frames in a document remains the same whether or not you re usingJavaScript. The simplest framesetting document consists of tags that are devoted to settingup the frameset, as follows: The preceding HTML document, which the user never sees, defines the frameset for theentire browser window. Each frame must have a URL reference (specified by the srcattribute) for a document to load into that frame. For scripting purposes, assigning a nametoeach frame with the nameattribute greatly simplifies scripting frame content. The frame object modelPerhaps the key to successful frame scripting is understanding that the object model in thebrowser s memory at any given instant is determined by the HTML tags in the currentlyloaded documents. All canned object model graphics in this book, such as Figure 16-1, do notreflect the precise object model for your document or document set. For a single, frameless document, the object model starts with just one windowobject, whichcontains one document, as shown in Figure 16-1. In this simple structure, the windowobjectisthe starting point for all references to any loaded object. Because the window is alwaysthere it must be there for a document to load into a reference to any object in the docu- ment can omit a reference to the current window. In a simple two-framed frameset model (see Figure 16-2), the browser treats the container ofthe initial, framesetting document as the parent window. The only visible evidence that thedocument exists is that the framesetting document s title appears in the browser windowtitlebar. Figure 16-1:The simplest window document relationship. WindowDocument

Window andFrameObjectsAquick look at the basic document object model diagram inChapter 14 (see Figure 14-1) reveals that the windowobject isthe outermost, most global container of all document-related objectsthat you script with JavaScript. All HTML and JavaScript activitytakes place inside a window. That window may be a standardWindows, Mac, or XWindows application-style window, complete withscrollbars, toolbars, and other chrome; you can also generate win- dows that have only some of a typical window s chrome. A frame isalso a window, even though a frame doesn t have many accou- trements beyond scroll bars. The windowobject is where everythingbegins in JavaScript references to objects. IE4+, NN6+, and W3Cbrowsers treat the frameset as a special kind of windowobject, sothat it is also covered in this chapter. Of all the objects associated with browser scripting, the windowandwindow-related objects have by far the most object-specific terminol- ogy associated with them. This necessitates a rather long chapter tokeep the discussion in one place. Use the running footers as a naviga- tional aid through this substantial collection of information. Window TerminologyThe windowobject is often a source of confusion when you firstlearnabout the document object model. A number of synonyms forwindowobjects muck up the works: top, self, parent, and frame. Aggravating the situation is that these terms are also properties of awindowobject. Under some conditions, a window is its own parent, but if you define a frameset with two frames, you have only one par- ent among a total of three windowobjects. It doesn t take long beforethe whole subject can make your head hurt. If you do not use frames in your Web applications, all of theseheadaches never appear. But if frames are part of your design plan, you should get to know how frames affect the object model. FramesThe application of frames has become a religious issue among Webdesigners: some swear by them; others swear at them. I believe therecan be compelling reasons to use frames at times. For example, if you1616CHAPTER …In This ChapterScriptingcommunication amongmultiple framesCreating and managingnew windowsControlling the size, position, andappearance of thebrowser windowDetails of window, frame, frameset, andiframeobjects …