|
From: Philippe O. <pom...@us...> - 2005-05-15 23:44:49
|
Update of /cvsroot/easystruts/easystruts-website/lib/x-cbe/x3151_cbe4191_z4/cross-browser.com/cbe/docs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv435/lib/x-cbe/x3151_cbe4191_z4/cross-browser.com/cbe/docs Added Files: getting_started.html cbe_reference.html core_om.html event_om.html Log Message: Added new web site sources and data --- NEW FILE: core_om.html --- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>CBE Core Object Model Documentation</title> <meta name='author' content='Mike Foster, cross-browser.com'> <meta name='description' content="CBE is a Cross-Browser DHTML API for IE, Gecko, Opera, Netscape, Konqueror, AOL and browsers with similar object models. CBE implements some of the W3C DOM2 interfaces."> <style type='text/css'><!-- body { font-family:verdana,arial,sans-serif,helvetica; font-size:12px; color:#000000; margin:0px; padding:0px; background:#cccccc; } a:link, a:visited, a:active { font-family:verdana,arial,sans-serif; font-size:12px; color:#666666; } a:hover { font-family:verdana,arial,sans-serif; font-size:12px; color:#3333ff; background:#cccccc; } p { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; } ul { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; background:#ffffff; } pre { font-family:"courier new",monotxt,courier; font-size:12px; color:#3333ff; background:#ffffff; } xmp { font-family:"courier new",monotxt,courier; font-size:12px; color:#3333ff; background:#ffffff; } .monoSpc { font-family:monospace; font-size:14px; } h1 { font-family:verdana,arial,sans-serif; font-size:16px; color:#3333ff; background:#cccccc; padding:2px; } h2 { font-family:verdana,arial,sans-serif; font-size:12px; color:#3333ff; background:#ffffff; border-top:1px dotted #000000; margin:1em 0em 1em 0em;} h3 { font-family:verdana,arial,sans-serif; font-size:12px; color:#666666; background:transparent; } td { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; vertical-align:top; } .clsTitle { font-family:verdana,arial,sans-serif; font-size:24px; color:#ffffff; margin:0px; padding:0px; vertical-align:middle; background-color:#3333ff; border-top:1px solid #ffffff; border-left:1px solid #ffffff; border-bottom:1px solid #000000; } .clsSubTitle { font-family:verdana,arial,sans-serif; font-size:10px; color:#ffffff; margin:0px; padding:0px; vertical-align:bottom; background-color:#3333ff; text-align:right; border-top:1px solid #ffffff; border-bottom:1px solid #000000; border-right:1px solid #000000; } --></style> </head> <body marginwidth='0' marginheight='0'><a name="topofpage"></a> <!-- Title --> <table width='100%' border='0' cellspacing='0' cellpadding='4'> <tr> <td height='40' class='clsTitle'> CBE Core Object Model</td> <td height='40' class='clsSubTitle'>Cross-Browser.com </td> </tr></table> <table width='80%' align='center' cellspacing='10' cellpadding='10'><tr><td bgcolor='#ffffff'><!-- indentation table --> <h1>CBE Core Object Model</h1> <h2>Implementing W3C DOM2 Interfaces</h2> <h3>The Idea</h3> <p>When I started working on the second version of CBE, I began to rethink the interface. By that I mean the <i>names</i> of the functions and objects, and how they relate to each other. Most of the other API's I studied had proprietary interfaces. They had function names like <i>getX()</i>, <i>setX()</i>, etc. There's nothing wrong with this type of interface - in fact I really liked it. So I began to think about what to name <i>my</i> functions, but I didn't want to use the names someone else had already used. Well... I'm not really good at coming up with cool names ;)</p> <p>During this time, I was studying the <a href='http://w3c.org/'>W3C</a> recommendations. I suddenly realized - all the names were there, already created for me! And not only that, but they provided a complete object model specification. I then decided that, somehow, my API should not only use the names from the W3C recommendations, but attempt also to actually implement their object model interfaces in <b>cross-browser</b> Javascript.</p> <p><b>CBE 4</b> is a partial implementation of some of the W3C DOM2 interfaces. This document discusses the CBE core object model. The CBE <a href="event_om.html">event model</a> is discussed in another document.</p> <h3>The Implementation Object</h3> <p>The following is a very simple example of programming DHTML in a DOM1 environment.</p> <p><i>Listing 1</i></p> <pre> window.onload = function() { var e1 = document.getElementById('E1'); e1.style.left = 100 + 'px'; e1.style.top = 100 + 'px'; e1.style.visibility = 'visible'; } </pre> <p>Now look at the following which uses CBE. It accomplishes the same task - positions an element at the point (100,100) and makes it visible. But this will work the same in all the different browsers CBE supports. And that's the whole purpose of CBE - to provide a programming interface as close as possible to the standard, while providing consistent, cross-browser semantics and rendering.</p> <p><i>Listing 2</i></p> <pre> function windowOnload() { var e1 = document.getElementById('E1'); e1.cbe.left(100); e1.cbe.top(100); e1.cbe.visibility('visible'); } </pre> <p>I'm sure you see the differences between the two code listings.</p> <ol> <li><i>The window.onload Event</i><br> Listing 1 directly hooks the window.onload event to initialize it's positioned element on the page. Listing 2 defines a function named <b>windowOnload()</b> to accomplish the same purpose. The actual window.onload event is hooked by the CBE system itself, and creates the CBE object model - then it calls windowOnload().</li> <li><i>The CSSP Object</i><br> In Listing 1 the CSSP object is named <i>style</i>. With CBE it is named <i>cbe</i>. Because CBE uses so many standard names, it must keep them within their own scope.</li> <li><i>Properties v/s Methods</i><br> Listing 1 reads and writes <i>properties</i> of the CSSP object. With CBE you call <i>methods</i> of the CSSP object. Browser differences are rectified within the methods.</li> <li><i>Specifying Units</i><br> In listing 1 you must specify the units. In CBE all numeric units are Pixels.</li> </ol> <p>CBE provides some <i>shortcut</i> methods. The following accomplishes the same as Listings 1 and 2, but is written the way I would normally program with CBE.</p> <p><i>Listing 3</i></p> <pre> function windowOnload() { var e1 = cbeGetElementById('E1').cbe; e1.moveTo(100,100); e1.show(); } </pre> <h3>CrossBrowserElement</h3> <!-- * --> <p>The CrossBrowserElement object is a partial implementation of the DOM2 <b>Element</b> interface. It is a <i>subclass</i> of CrossBrowserNode, and so inherits those properties and methods. CrossBrowserElement objects populate the CBE Object Tree. A CrossBrowserElement object is created for each DIV or SPAN with id!="" and added to it's associated Element object as a property named <b>cbe</b>.</p> <p>The window.onload event is received by a function in <i>cbe_core.js</i>. It calls the function cbeInitialize(), which creates the CBE object model. Consider the following HTML.</p> <pre> <div id='E1' class='clsCBE'>This is e1</div> </pre> <p>Now notice the difference between accessing the native Element object and the CrossBrowserElement object, and then compare this with listing 3.</p> <p><i>Listing 4</i></p> <pre> function windowOnload() { <b>// ne is a reference to the native Element object</b> var ne = document.getElementById('E1'); <b>/* e is a reference to the CrossBrowserElement object associated with the native Element object whose id is 'E1' */</b> var e = ne.cbe; e.moveTo(100,100); e.show(); } </pre> <h3>The CBE Object Tree</h3> <p>The function cbeInitialize() connects all the CrossBrowserElement objects into a <i>tree structure</i> using property names from the DOM2 Node interface. This tree structure models the <i>parent/child</i> (nesting) relationships among the CrossBrowserElement objects. When cbeInitialize() has finished creating the object model, it calls windowOnload(), if you have defined it. The window.on<b>un</b>load event is also received by a CBE function. It first calls windowOnunload(), if you have defined it, then nulls the cbe property of each positioned Element.</p> <p>The following illustrates the tree structure that is created for the HTML in listing 5. Notice that there are two additional CrossBrowserElement objects in the tree. One is associated with the native <b>window</b> object, and the other is associated with the native <b>document</b> object. Their respective id's are the values of the variables <b>window.idWindow</b> and <b>window.idDocument</b>.</p> <table border='0' cellspacing='0' cellpadding='20'><tr> <td valign='top'> <p><i>Listing 5</i></p> <pre> <div id='P1' class='clsCBE'> <div id='P1C1' class='clsCBE'> </div> <div id='P1C2' class='clsCBE'> </div> </div> <div id='P2' class='clsCBE'> <div id='P2C1' class='clsCBE'> </div> <div id='P2C2' class='clsCBE'> </div> </div> </pre> </td> <td><img border='0' src='../graphics/cbe_tree.gif'></td> </tr></table> <p>There are common terms used to describe the relationships between objects in a tree structure. In the descriptions below I'll refer to the tree built from listing 5.</p> <ul> <li><i>node</i> - Each individual item in the tree.</li> <li><i>root</i> - The first node of the tree. <i>window.cbe</i> is the root node of the CBE object tree.</li> <li><i>parent</i> - The node one level up. P1 is the parent of P1C1 and P1C2.</li> <li><i>child</i> - The node one level down. P1C1 and P1C2 are the children of P1.</li> <li><i>Sibling</i> - Nodes on the same level. P1C1 and P1C2 are siblings (they have the same parent).</li> <li><i>Ancestor</i> - Any of the nodes as you follow the connections up to the root. <i>document.cbe</i> is not the parent of P1C1, but is it's ancestor.</li> <li><i>Descendant</i> - Any of the nodes as you follow the connections down. The opposite of ancestor. P1C1 is a descendant of <i>window.cbe</i>.</li> </ul> <h3>CrossBrowserNode</h3> <!-- * --> <p>The CrossBrowserNode object is a partial implementation of the DOM2 <b>Node</b> interface. It's properties provide for the implementation of the CBE Object Tree.</p> <p>CrossBrowserNode Properties:</p> <ul> <li>childNodes</li> <li>firstChild</li> <li>lastChild</li> <li>nextSibling</li> <li>parentNode</li> <li>previousSibling</li> </ul> <p>In CBE, <i>childNodes</i> is an integer, and is simply the number of child nodes. The remaining properties point to CrossBrowserElement objects.</p> <p>With the CrossBrowserNode properties you can <i>traverse</i> (walk) the tree, that is, <i>visit</i> (apply a function to) each node in the tree (or sub-tree). I've also provided a function named <a target="cbeRefWin" href="../cbe_reference.html#cbeTraverseTreeLink">cbeTraverseTree()</a> which will perform a pre-order traversal of the entire tree (or sub-tree). If you need post-order traversal let me know and I'll provide that function.</p> <p>For the following example, imagine that the nodes P1 and P2 are containers for a dhtml <i>window</i>. Within them may be many different positioned elements, nested at different levels. When the user clicks anywhere within the container we want to raise the container's z-index, to make it come to the top of any other <i>windows</i>. The following function would be useful, and it makes use of the CrossBrowserNode properties and the tree structure.</p> <p><i>Listing 6</i></p> <pre> function getTopContainer(oThis) { var ancestor = oThis; while (ancestor.id != window.idDocument) { ancestor = ancestor.parentNode; } return ancestor; } </pre> <h3>ClientSnifferJr</h3> <!-- * --> <p>There is one <a target="cbeRefWin" href="../cbe_reference.html#ClientSnifferJrPropertiesLink">ClientSnifferJr</a> object, named <b>is</b>. It is the client detection object, which is available immediately after <i>cbe_core.js</i> has loaded. With the <b>is</b> object you can determine which browser your page is currently running on.</p> <p><i>Listing 7</i></p> <pre> function windowOnload() { var s = "Welcome "; if (is.opera) s += "Opera"; else if (is.gecko) s += "Gecko"; else if (is.nav) s += "Navigator"; window.defaultStatus = s + " User!"; } </pre> <p>See the object reference for a complete list of events, properties and methods for all the objects discussed in this document.</p> </td></tr></table><!-- end indentation table --> </body> </html> --- NEW FILE: getting_started.html --- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Getting Started with CBE</title> <meta name='author' content='Mike Foster, cross-browser.com'> <meta name='description' content="CBE is a Cross-Browser DHTML API for IE, Gecko, Opera, Netscape, Konqueror, AOL and browsers with similar object models. CBE implements some of the W3C DOM2 interfaces."> <style type='text/css'><!-- body { font-family:verdana,arial,sans-serif,helvetica; font-size:12px; color:#000000; margin:0px; padding:0px; background:#cccccc; } a:link, a:visited, a:active { font-family:verdana,arial,sans-serif; font-size:12px; color:#666666; } a:hover { font-family:verdana,arial,sans-serif; font-size:12px; color:#3333ff; background:#cccccc; } p { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; } ul { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; background:#ffffff; } pre { font-family:"courier new",monotxt,courier; font-size:12px; color:#3333ff; background:#ffffff; } xmp { font-family:"courier new",monotxt,courier; font-size:12px; color:#3333ff; background:#ffffff; } .monoSpc { font-family:monospace; font-size:14px; } h1 { font-family:verdana,arial,sans-serif; font-size:16px; color:#3333ff; background:#cccccc; padding:2px; } h2 { font-family:verdana,arial,sans-serif; font-size:12px; color:#3333ff; background:#ffffff; border-top:1px dotted #000000; margin:1em 0em 1em 0em;} h3 { font-family:verdana,arial,sans-serif; font-size:12px; color:#666666; background:transparent; } td { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; vertical-align:top; } .clsTitle { font-family:verdana,arial,sans-serif; font-size:24px; color:#ffffff; margin:0px; padding:0px; vertical-align:middle; background-color:#3333ff; border-top:1px solid #ffffff; border-left:1px solid #ffffff; border-bottom:1px solid #000000; } .clsSubTitle { font-family:verdana,arial,sans-serif; font-size:10px; color:#ffffff; margin:0px; padding:0px; vertical-align:bottom; background-color:#3333ff; text-align:right; border-top:1px solid #ffffff; border-bottom:1px solid #000000; border-right:1px solid #000000; } --></style> </head> <body marginwidth='0' marginheight='0'><a name="topofpage"></a> <!-- Title --> <table width='100%' border='0' cellspacing='0' cellpadding='4'> <tr> <td height='40' class='clsTitle'> Getting Started with CBE</td> <td height='40' class='clsSubTitle'>Cross-Browser.com </td> </tr></table> <table width='80%' align='center' cellspacing='10' cellpadding='10'><tr><td bgcolor='#ffffff'><!-- indentation table --> <h1>Getting Started with CBE</h1> <ul> <li><a href='#ifsLink'>Initial File Setup</a> <br>Install the Library <br>Start a Project <br>Include? <br>Test Your Setup </li> <li><a href='#threeLink'>DHTML</a> <br>CSS <br>HTML <br>Javascript <li><a href='#etLink'>First Experiment</a> <br>Color <br>Size <br>Position <br>Visibility <br>Initialization </li> <li><a href='#esLink'>Preparation for Development</a> <br>Study the CBE Object & Event Models <br>Get Familiar with the Library <br>Create a Development Environment </li> <li><a href='#dtLink'>Debugging Tips</a> <br>Syntax Errors <br>Logic Errors <br>Watch Variables <br>Break Points <br>CBE Debug Window </li> </ul> <a name='ifsLink'></a> <h2>Initial File Setup</h2> <h3>Install the Library</h3> <p>Create a new folder for the CBE project on your hard-drive. <a href="javascript:showC(2)">Download</a> the latest version of the CBE library into the new folder and unzip it there.</p> <h3>Start a Project</h3> <p>The following template is included with the download as the file <a href="../cbe_template.html">cbe_template.html</a>. When you start a CBE project, use a <i>copy</i> of the template file.</p> <pre> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>CBE Template</title> <style type='text/css'><!-- body { color:#000000; background:#FFFFFF; margin:0px; padding:0px; } .clsCBE { position:absolute; visibility:hidden; width:100%; height:100%; clip:rect(0,100%,100%,0); color:#000000; margin:0px; padding:0px; } --></style> <script type='text/javascript' src='cbe_core.js'></script> <script type='text/javascript'><!-- var e1; function windowOnload() { with (e1 = cbeGetElementById('E1').cbe) { color('#FFFFFF'); background('#0000FF'); resizeTo(200,200); moveTo('center'); show(); } } //--></script> </head> <body marginwidth='0' marginheight='0'> <div id='E1' class='clsCBE'>E1</div> </body> </html> </pre> <h3>Include?</h3> <p>Often I'll use the phrase <i>include a javascript file</i>. What do I mean by <i>include</i>? It is a preprocessor directive for the C language. It directs the preprocessor to literally <i>include</i> (insert) the referenced file into the current file. Javascript doesn't have a corresponding keyword - but it does provide similar functionality.</p> <p>Refer to the template above. The first SCRIPT element is empty - it doesn't have any Javascript between the opening and closing tags. But it does assign a value to the <b>src</b> attribute. This value specifies the URL of a Javascript file that is to be <i>included</i> at that point in the template copy. In this case, it specifies that <i>cbe_core.js</i> is in the same folder as the template copy.</p> <p>The second SCRIPT element is not empty, it has Javascript between the opening and closing tags, and so it does not assign a value to the <b>src</b> attribute.</p> <p>The CBE library consists of several different Javascript files. The object reference indicates what file needs to be <i>included</i> to enable a particular feature.</p> <h3>Test Your Setup</h3> <p>Make a copy of the template file (I'll assume its named "proj.html"), and open it in your favorite Browser. You will see a blue square in the center of the browser window. The white text "E1" will be in the upper-left corner of the square. I refer to the square in general as an <i>element</i>. This element's <b>id</b> is <i>E1</i>, so I'll refer to that particular square as E1.</p> <a name='threeLink'></a><p align='right'><a href='#topofpage'>Top</a> | <a href='../index.html'>Home</a></p> <h2>DHTML</h2> <p>Dynamic HTML is the cooperation of three technologies: CSS, HTML, and Javascript. For each <i>positioned element</i> on the page, there must be related CSS, HTML, and Javascript. By the phrase <i>positioned element</i> I mean an element whose CSS property <b>position</b> has the value 'absolute' or 'relative'.</p> <h3>CSS</h3> <p>This CSS defines a Class named clsCBE. Its <i>position</i> property is set to 'absolute'.</p> <pre> .clsCBE { position:absolute; } </pre> <h3>HTML</h3> <p>This HTML defines an Element with its <i>id</i> attribute set to 'E1' and its <i>class</i> attribute set to 'clsCBE'. All the styles defined by the CSS Class <i>clsCBE</i> are applied to this element.</p> <pre> <div id='E1' class='clsCBE'> </div> </pre> <h3>Javascript</h3> <p>The Javascript uses the <i>id</i> attribute of the Element to access the Element <i>object</i> and it's properties.</p> <pre> window.onload = function() { var e1 = document.getElementById('E1'); e1.style.visibility = 'visible'; } </pre> <p>The Class can be applied to more than one element. The Identifier (<i>id</i> attribute) of each element must be unique.</p> <a name='etLink'></a><p align='right'><a href='#topofpage'>Top</a> | <a href='../index.html'>Home</a></p> <h2>First Experiment</h2> <p>Open proj in your favorite text editor. You now have proj open in both an editor and a browser. After you make changes to proj in the editor, save the file, go to the browser and refresh it, to see the effect of your changes.</p> <h3>Color</h3> <p>Change the <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#backgroundLink">background</a> value to '#FF0000', save the file, and refresh the browser. Now e1 is red. Change the <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#colorLink">color</a> value to '#000000', save the file, and refresh the browser. The text is now black. Here's a <a href="color_charts.html">color chart</a> with color values. It is more cross-browser to use the hex values instead of the color names.</p> <h3>Size</h3> <p>The arguments to the <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#resizeToLink">resizeTo</a> method are <i>width</i>, and <i>height</i>. Experiment with different values.</p> <h3>Position</h3> <p>Experiment with the <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#moveToLink">moveTo</a> method. Here is it's syntax: <b>moveTo(x, y)</b>, where x and y are pixel coordinates with the point <b>(0,0)</b> at the upper-left corner of the element's <i>containing</i> element.</p> <p>Move e1 to the point <b>(-200, 0)</b>. It will be at the top of the window, but half-way <i>off</i> the window to the left. So x and y can also be negative.</p> <p>The <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#moveToLink">moveTo</a> method can take arguments other than a pixel point. It can take a <i>cardinal</i> point, that is, a point designated by north, south, east, etc. The syntax follows. The square brackets indicate an optional parameter.</p> <p><b>moveTo(sCardinal [, iMargin [, bOutside ]])</b></p> <ul> <li><i>sCardinal</i><br> One of the following strings: 'n', 'ne', 'e', 'se', 's', 'sw', w, 'nw', 'center'. The element will be positioned in the corner, on the side, or in the center of it's containing CBE object.</li> <li><i>iMargin</i><br> A signed integer value, indicating the distance between the edge of the container and the element. Assumed zero, if not present.</li> <li><i>bOutside</i><br> A boolean (true/false) value. If it is true, the element will be positioned outside of the container's edge. If it is false (or not present), the element will be positioned inside the container's edge.</li> </ul> <p>Experiment with moving e1 to the different corners and sides of the window. Experiment with the <b>margin</b>. Then give an <b>outside</b> argument.</p> <h3>Visibility</h3> <p>An element's visibility is controlled by the <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#visibilityLink">visibility()</a> method. This method accepts one, optional argument of type string. This method returns a boolean value - true if the element is visible, and false if it is hidden.</p> <p>There are two shortcut methods provided, <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#showLink">show()</a> and <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#hideLink">hide()</a>, and they do exactly what they say. They do not accept arguments and have no return values.</p> <h3>Initialization</h3> <p>When the CBE object model is created, <i>nothing</i> is done to the positioned elements. You might think because size, position, and visibility are set in the CSS, that you don't have to set those properties in script - and in some browsers that's true, but in some browsers an element's properties are not initialized with the CSS values. You have to set them initially in script. At a minimum, setting <b>size</b>, <b>position</b>, and <b>visibility</b> should be part of your normal initialization for each object. A logical place to perform this initialization is in <i>windowOnload()</i>. Look at the code above for the CBE template, and notice the initialization of the element.</p> <a name='esLink'></a><p align='right'><a href='#topofpage'>Top</a> | <a href='../index.html'>Home</a></p> <h2>Preparation for Development</h2> <h3>Study the CBE Object & Event Models</h3> <p>To develop applications with CBE you need a general understanding of the CBE <a href='core_om.html'>object model</a> and <a href='event_om.html'>event model</a>. This is not a waste of time - you are not learning a <i>proprietary</i> API. The CBE API is an implementation of some of the W3C DOM2 interfaces. There are only minor differences. So by learning the CBE object and event models you are also developing your understanding of the DOM2 standards.</p> <h3>Get Familiar with the Library</h3> <p>Get familiar with the CBE library by viewing the examples I've provided, by perusing the object reference and other documentation I've provided, and especially by <i>using</i> the library. Start a new project with a copy of your CBE template file. Look through the object reference and choose a method you want to experiment with. Most entries in the reference have a <i>snippet</i> of an example. Copy the snippet and paste it into your new file. The snippets are designed to be used with that template - most of them have a <b>windowOnload()</b> function that can take the place of the same function in the template. If there's a particular example that interests you, download that example file, get it working on your own computer, then experiment with it.</p> <p>Refer to the reference for the valid values and ranges of each argument to the method you're using, and experiment with them. As before, you have your file open in an editor and a browser. Change the value of one of the arguments, save the file, and refresh the browser to see the changes.</p> <h3>Create a Development Environment</h3> <p>Learn to utilize the development/debugging tools CBE provides. Here's <a href="../examples/tools.html">a list</a> of the functions in <i>cbe_debug.js</i>.</p> <p><i>The Debug Window</i> - The Debug link on the menubar will open, close, or refresh the CBE Debug Window. This window provides development/debugging support. It shows the object tree for the current page, the properties for the selected object, provides a command line for calling methods of the selected object, and provides an area where the application can display messages by calling <a target="cbeRefWin" href="../cbe_reference.html#cbeDebugMsgLink" title="Reference Link">cbeDebugMsg()</a>. The debug window file <i>cbe_debug.html</i> is included with the CBE download. You can use the debug window as you develop applications on your own computer.</p> <p><i>The Reference Window</i> - The object reference opens in it's own window. As you study the examples, or as you are developing your own application, you can quickly view the documentation for a particular method, property, or event - without leaving the page you're studying.</p> <p><i>Development Environment</i> - The CBE debug and reference windows, the application window, and your own text editor form a <i>development environment</i>. To help with this <i>environment</i> here's a little feature: <a href="javascript:cbeTileWindows()">Tile the CBE Windows</a>. Clicking a reference link on one of my pages will cause the reference window to scroll to the appropriate entry, and then bring itself to the top (give itself the focus).</p> <p>The CBE debug and reference windows can be used on your own computer as you develop your own applications with CBE. To use the debug window, include a minimum of the following in the file you're developing. Call <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#cbeDebugWindowLink">cbeDebugWindow()</a> to open, close, or refresh the debug window.</p> <ul> <li>cbe_core.js</li> <li>cbe_event.js</li> <li>cbe_debug.js</li> </ul> <a name='dtLink'></a><p align='right'><a href='#topofpage'>Top</a> | <a href='../index.html'>Home</a></p> <h2>Debugging Tips</h2> <p>You can download some very nice Javascript debugging programs for a variety of platforms, but your initial debugging can be done with simple techniques right in your code. Most browsers will give the line number of an error - this is essential. Some browsers give better error descriptions than others. There are basically two types of errors: syntax errors, and logic errors.</p> <h3>Syntax Errors</h3> <p>A syntax error will occur when you have not followed the <i>grammer</i> of Javascript: forget to put two quotes around a string; forget to put a closing curly brace; have punctuation in the wrong place, etc. The browser will inform you of most syntax errors.</p> <h3>Logic Errors</h3> <p>After you correct your syntax errors, the script still may not work properly while running: it may be mis-calculating a value, or perhaps an <b>if</b> condition is using the logically wrong (but syntactically valid) operator. These are logic errors.</p> <p>Among the tools that most Debuggers provide for solving errors are <i>Watch Variables</i> and <i>Breakpoints</i>. You can utilize these same concepts without a debugger.</p> <h3>Watch Variables</h3> <p>A watch variable is a variable for which you want to watch the value, <i>as the script is running</i> - that is, as the page is active in a browser.</p> <p>A simple technique for using watch variables without a debugger is to use the window's <b>status bar</b> (some browsers are better at this than others). For example, in the following code fragment I want to <i>watch</i> the value of the variable <b>dx</b>. I insert line number 9. Notice the "//// debug" comment. I do this so I won't forget why I added this line, and so, later, I can search my file for "debug", and delete all those lines.</p> <p>Now I save the file, refresh the browser, and watch the value of dx on the status bar, as the script is running.</p> <pre> 1: if (cl + dx < 0) { 2: cl = 0; 3: dx = 0; 4: } 5: else if (cr + dx > this.width()) { 6: cr = cl + this.clipWidth(); 7: dx = 0; 8: } 9: window.status = "dx: " + dx; ////////////////////// debug </pre> <h3>Break Points</h3> <p>There are times when a variable's value is changing too quickly to use a watch. You need to stop the script and look at the variable. A break point is a line in the script at which <i>the script stops running</i>. You can then look at the current values of variables. When you are ready, you let the script continue running.</p> <p>A simple technique for using break points without a debugger is to use Javascript's <b>alert()</b> function. This function stops the script, displays a message, and waits for the user clik the OK button. The script then continues executing. This technique is not <i>exactly</i> like a break point, but its close enough. For example, in the following code fragment I want to see the value of dx only if it enters the <i>else if</i> block, and before it is assigned zero. I insert line number 6. <pre> 1: if (cl + dx < 0) { 2: cl = 0; 3: dx = 0; 4: } 5: else if (cr + dx > this.width()) { 6: alert("dx: " + dx); ////////////////////// debug 7: cr = cl + this.clipWidth(); 8: dx = 0; 9: } </pre> <h3>The CBE Debug Window</h3> <p>The CBE debug window provides a variety of features that help with debugging. Select an object by clicking it's <b>id</b> in the object tree, or by clicking on the object itself on the application page. Most of the selected object's properties are then displayed. You can call a method of the selected object by typing the method and it's arguments into the text field provided and pressing Enter or clicking the Call button. For example, type this: <b>hide()</b> and click Call. The selected object will be hidden. Type this: <b>background('#cccccc')</b> and click Call. The background color of the selected object will change.</p> <p>Your application script can pass a string to <a title="Reference Link" target="cbeRefWin" href="../cbe_reference.html#cbeDebugMsgLink">cbeDebugMsg()</a> and it will be displayed in the message area of the debug window.</p> </td></tr></table><!-- end indentation table --> </body> </html> --- NEW FILE: event_om.html --- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>CBE Event Model Documentation</title> <meta name='author' content='Mike Foster, cross-browser.com'> <meta name='description' content="CBE is a Cross-Browser DHTML API for IE, Gecko, Opera, Netscape, Konqueror, AOL and browsers with similar object models. CBE implements some of the W3C DOM2 interfaces."> <style type='text/css'><!-- body { font-family:verdana,arial,sans-serif,helvetica; font-size:12px; color:#000000; margin:0px; padding:0px; background:#cccccc; } a:link, a:visited, a:active { font-family:verdana,arial,sans-serif; font-size:12px; color:#666666; } a:hover { font-family:verdana,arial,sans-serif; font-size:12px; color:#3333ff; background:#cccccc; } p { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; } ul { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; background:#ffffff; } pre { font-family:"courier new",monotxt,courier; font-size:12px; color:#3333ff; background:#ffffff; } xmp { font-family:"courier new",monotxt,courier; font-size:12px; color:#3333ff; background:#ffffff; } .monoSpc { font-family:monospace; font-size:14px; } h1 { font-family:verdana,arial,sans-serif; font-size:16px; color:#3333ff; background:#cccccc; padding:2px; } h2 { font-family:verdana,arial,sans-serif; font-size:12px; color:#3333ff; background:#ffffff; border-top:1px dotted #000000; margin:1em 0em 1em 0em;} h3 { font-family:verdana,arial,sans-serif; font-size:12px; color:#666666; background:transparent; } td { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; vertical-align:top; } .clsTitle { font-family:verdana,arial,sans-serif; font-size:24px; color:#ffffff; margin:0px; padding:0px; vertical-align:middle; background-color:#3333ff; border-top:1px solid #ffffff; border-left:1px solid #ffffff; border-bottom:1px solid #000000; } .clsSubTitle { font-family:verdana,arial,sans-serif; font-size:10px; color:#ffffff; margin:0px; padding:0px; vertical-align:bottom; background-color:#3333ff; text-align:right; border-top:1px solid #ffffff; border-bottom:1px solid #000000; border-right:1px solid #000000; } --></style> </head> <body marginwidth='0' marginheight='0'><a name="topofpage"></a> <!-- Title --> <table width='100%' border='0' cellspacing='0' cellpadding='4'> <tr> <td height='40' class='clsTitle'> CBE Event Model</td> <td height='40' class='clsSubTitle'>Cross-Browser.com </td> </tr></table> <table width='80%' align='center' cellspacing='10' cellpadding='10'><tr><td bgcolor='#ffffff'><!-- indentation table --> <h1>CBE Event Model</h1> <h2>Implementing The W3C DOM2 Event Model</h2> <h3>Overview</h3> <p>It will be helpful to first read about the CBE <a href="core_om.html">core object model</a>.</p> <p>The CBE Event Model is an implementation of the W3C DOM2 event model. Like the CBE core object model, it involves only CrossBrowserElement objects. Event listeners receive CrossBrowserEvent object arguments. CrossBrowserEvent objects flow up and down the CBE object tree in different phases of the event. You can add more than one listener of a particular event type to an object!</p> <h3>Event Listeners</h3> <p>An event <i>listener</i> is just an event handler function you provide. The function will receive one argument, a CrossBrowserEvent object. You add (or register) an event listener to a specific CrossBrowserElement object by calling the object's <a target="cbeRefWin" href="../cbe_reference.html#addEventListenerLink">addEventListener()</a> method. Let's look at it's syntax:</p> <p><b>addEventListener(eventType, eventListener, useCapture)</b></p> <p>The eventType argument is a string such as "mouseOver". The eventListener argument is a reference to a function. The useCapture argument is boolean.</p> <p>In listing 1 a mouseOver event listener is added to the E1 element. When the mouse first moves over the element, the function <i>mouseOverListener</i> will be called and passed a CrossBrowserEvent object as an argument.</p> <p><i>Listing 1</i></p> <pre> function windowOnload() { var e1 = document.getElementById('E1').cbe; e1.addEventListener('mouseOver', mouseOverListener, false); } function mouseOverListener(e) { alert('The mouse is over ' + e.cbeCurrentTarget.id); } </pre> <p>Event listeners are removed by calling the object's <a target="cbeRefWin" href="../cbe_reference.html#removeEventListenerLink">removeEventListener()</a> method. It must be passed the same arguments as were passed to addEventListener().</p> <h3>Basic Event Flow</h3> <p>CrossBrowserEvent objects are only sent to CrossBrowserElement objects. When an event occurs, a specific CrossBrowserElement object is designated as the <i>event target</i>, and is specified in the event object's <b>cbeTarget</b> property. The event then travels up and down the CBE object tree looking for event listeners registered on the same event type as the event. This occurs in three distinct phases, in this order: the CAPTURING_PHASE, the AT_TARGET phase, and the BUBBLING_PHASE.</p> <p>After an event target has been designated, an array is built which consists of every CrossBrowserElement object along the <i>parent chain</i> between the event target and the root of the object tree, but not including the event target. This <i>parent chain</i> array is used during the capturing and bubbling phases.</p> <h3>The Capturing Phase</h3> <p>The capturing phase begins at the top node of the parent chain - at <b>window.cbe</b>. The node then dispatches the event to all event listeners that have been added to the node that have the same <i>type</i> as the event and that had passed useCapture==true in the call to addEventListener(). The next node in the parent chain then dispatches the event. This continues down the parent chain until the parent of the event target node dispatches the event to it's listeners.</p> <p>A capturing event listener will not be triggered by events dispatched directly (AT_TARGET) to the event target upon which it is registered.</p> <h3>The At-Target Phase</h3> <p>After the capturing phase, the at-target phase begins. The event target node dispatches the event to all event listeners that have been added to the node that have the same <i>type</i> as the event and that had passed useCapture==false in the call to addEventListener().</p> <h3>The Bubbling Phase</h3> <p>After the at-target phase, the bubbling phase begins. This phase begins at the parent of the event target. This node dispatches the event to all event listeners that have been added to the node that have the same <i>type</i> as the event and that had passed useCapture==false in the call to addEventListener(). Then the parent of that node dispatches the event. This continues up the parent chain until the root node of the object tree dispatches the event to it's listeners. Event listeners registered as capturers will not be triggered during this phase.</p> <h2>CrossBrowserEvent</h2> <p>The CrossBrowserEvent object is a partial implementation of some of the W3C DOM2 Event interfaces. See the reference for details on each <a target="cbeRefWin" href="../cbe_reference.html#CrossBrowserEventPropertiesLink">property</a>.</p> <h3>cbeTarget & cbeCurrentTarget</h3> <p>When a listener receives an event, the event object's <b>cbeCurrentTarget</b> property points to the CrossBrowserElement object of the current listener. Effectively, it is the listener's <i>this</i> pointer. The event object's <b>cbeTarget</b> property points to the CrossBrowserElement object which is the actual target of the event.</p> <h3>stopPropagation() & preventDefault()</h3> <p>If an event listener wishes to prevent further propagation of the event (stop/prevent the capturing or bubbling phase) it may call the <b>stopPropagation()</b> method of the event object. This will prevent further propagation of the event, although the event will still be dispatched to any remaining event listeners registered on the same object.</p> <p>An EventListener may call the <b>preventDefault()</b> method of the event object to cancel any default action associated with the event.</p> <h2>CBE Supported Events</h2> <p>The following events are supported by this implementation of the DOM2 event model.</p> <ul> <li>click </li> <li>mousedown </li> <li>mouseup </li> <li>mousemove </li> <li>mouseover </li> <li>mouseout </li> <li>keypress </li> <li>keyup </li> <li>keydown </li> </ul> <p>CBE also provides support for the following events but not yet within the new event model.</p> <ul> <li>drag</li> <li>dragStart</li> <li>dragEnd</li> <li>slide</li> <li>slideStart</li> <li>slideEnd</li> <li>dragResize (specialized)</li> <li>scroll (for window object)</li> <li>resize (for window object)</li> </ul> <p>See the object reference for details on CrossBrowserElement <a target="cbeRefWin" href="../cbe_reference.html#CrossBrowserElementEventsLink">events</a>.</p> </td></tr></table><!-- end indentation table --> </body> </html> --- NEW FILE: cbe_reference.html --- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>CBE Object Reference</title> <meta name='author' content='Mike Foster, cross-browser.com'> <meta name='description' content='Object reference for CBE, a Cross-Browser DHTML API for IE, Gecko, Opera, Netscape, Konqueror, AOL and similar browsers'> <style type='text/css'><!-- body { font-family:verdana,arial,sans-serif,helvetica; font-size:12px; color:#000000; margin:0px; padding:0px; background:#cccccc; } a:link, a:visited, a:active { font-family:verdana,arial,sans-serif; font-size:12px; color:#666666; } a:hover { font-family:verdana,arial,sans-serif; font-size:12px; color:#3333ff; background:#cccccc; } p { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; } ul { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; background:#ffffff; } pre { font-family:"courier new",monotxt,courier; font-size:12px; color:#3333ff; background:#ffffff; } xmp { font-family:"courier new",monotxt,courier; font-size:12px; color:#3333ff; background:#ffffff; } .monoSpc { font-family:monospace; font-size:14px; } h1 { font-family:verdana,arial,sans-serif; font-size:16px; color:#3333ff; background:#cccccc; padding:2px; } h2 { font-family:verdana,arial,sans-serif; font-size:12px; color:#3333ff; background:#ffffff; border-top:1px dotted #000000; margin:1em 0em 1em 0em;} h3 { font-family:verdana,arial,sans-serif; font-size:12px; color:#666666; background:transparent; } td { font-family:verdana,arial,sans-serif; font-size:12px; color:#000000; vertical-align:top; } [...1742 lines suppressed...] <a name='syntax'></a> <p align='right'><a href='#topofpage'>Top</a></p> <h2>Parameter Syntax</h2> <p>Any parameter in square brackets is optional. The OR symbol '|' is used to indicate a choice of two different parameters. Each parameter has a <i>data type prefix</i> which will be one of the following.</p> <ul> <li><b>b</b> - boolean</li> <li><b>i</b> - signed integer</li> <li><b>u</b> - unsigned integer</li> <li><b>s</b> - string</li> <li><b>c</b> - string specifying a color, preceded with '#' (use cbeHexString() to convert numbers to color strings)</li> <li><b>d</b> - date object</li> <li><b>o</b> - object reference</li> <li><b>f</b> - function reference</li> <li><b>x</b> - either a string that can be evaluated, or a function reference. cbeEval() accepts <i>x</i> arguments</li> </ul> </td></tr></table><!-- end indentation table --> </body> </html> |
