Diff for /books/www/chapters/ch05.html between versions 1.1 and 1.2

version 1.1, 2002/09/17 21:10:35 version 1.2, 2002/09/23 15:23:31
Line 7 Line 7
 <H2><A NAME="77038"></A> Faces of JavaScript in Mozilla</H2>  <H2><A NAME="77038"></A> Faces of JavaScript in Mozilla</H2>
 <P>As you have already  <!--INDEX scripting:JavaScript, overview -->  <!--INDEX JavaScript:overview --> seen in some examples in this book, the user interface uses JavaScript extensively to create behavior and to glue various widgets together into a coherent whole. When you add code to the event handler of one element to manipulate another-for example, when you update the value of a textbox using a XUL button-you take advantage of this first "level" of scriptability. In this role, JavaScript uses the Document Object Model (DOM) to access parts of the user interface as a hierarchical collection of objects. The section <A HREF="#77054">"Adding Scripts to the UI</A>," later in this chapter, discusses this highest level of scripting.  <P>As you have already  <!--INDEX scripting:JavaScript, overview -->  <!--INDEX JavaScript:overview --> seen in some examples in this book, the user interface uses JavaScript extensively to create behavior and to glue various widgets together into a coherent whole. When you add code to the event handler of one element to manipulate another-for example, when you update the value of a textbox using a XUL button-you take advantage of this first "level" of scriptability. In this role, JavaScript uses the Document Object Model (DOM) to access parts of the user interface as a hierarchical collection of objects. The section <A HREF="#77054">"Adding Scripts to the UI</A>," later in this chapter, discusses this highest level of scripting.
 <P>At a second level, JavaScript glues the entire user interface to the XPCOM libraries beneath, which create the application core. At this level, XPConnect (see the section <A HREF="#77066">"What Is XPConnect?</A>" later in this chapter) provides a bridge that makes these components "scriptable," which means that they can be invoked from JavaScript and used from the user interface layer. When JavaScript calls methods and gets data from scriptable components, it uses this second layer of scriptability.  <P>At a second level, JavaScript glues the entire user interface to the XPCOM libraries beneath, which create the application core. At this level, XPConnect (see the section <A HREF="#77066">"What Is XPConnect?</A>" later in this chapter) provides a bridge that makes these components "scriptable," which means that they can be invoked from JavaScript and used from the user interface layer. When JavaScript calls methods and gets data from scriptable components, it uses this second layer of scriptability.
<P>Finally, at the third and ultimate level of Mozilla scripting, JavaScript can be used as a "first-order" language for creating the application core itself, for writing software components or libraries whose services are called. We discuss this third level of scripting and provide a long example in the section <A HREF="ch08.htm#77065">"Creating a JavaScript XPCOM Component</A>" in <A HREF="ch08.htm#77048">Chapter 8</A>.<P>Finally, at the third and ultimate level of Mozilla scripting, JavaScript can be used as a "first-order" language for creating the application 
 core itself, for writing software components or libraries whose services are called. We discuss this third level of scripting and provide a long 
 example in the section <A HREF="ch08.html#77065">"Creating a JavaScript XPCOM Component</A>" in <A HREF="ch08.html#77048">Chapter 8</A>.
 <P>When you use JavaScript in these contexts, the application architecture looks something like <A HREF="#77002">Figure 5-1</A>, in which scripting binds the user interface to the application core through XPConnect and can reside as a software component using such technologies as XPIDL and XPCOM.  <P>When you use JavaScript in these contexts, the application architecture looks something like <A HREF="#77002">Figure 5-1</A>, in which scripting binds the user interface to the application core through XPConnect and can reside as a software component using such technologies as XPIDL and XPCOM.
 <P><CENTER><IMG SRC="foo.gif"></CENTER>  <P><CENTER><IMG SRC="foo.gif"></CENTER>
 <P><I>Figure 5-1: <A NAME="77002"></A></I>  <P><I>Figure 5-1: <A NAME="77002"></A></I>
Line 256  dump(count + " items checked \n"); Line 258  dump(count + " items checked \n");
   
  &lt;/menubar&gt;</PRE>   &lt;/menubar&gt;</PRE>
   
<P>When you add this to the xFly application window (from <A HREF="ch02.htm#77034">Example 2-10</A>, for example, above the basic <TT>vbox</TT> structure), you get an application menu bar with a menu item, Toggle, that reverses the checked state of the three items in the "Fly Types" menu, as seen in <A HREF="#77004">Figure 5-2</A>.<P>When you add this to the xFly application window (from <A HREF="ch02.html#77034">Example 2-10</A>, for example, above the basic <TT>vbox</TT> 
 structure), you get an application menu bar with a menu item, Toggle, that reverses the checked state of the three items in the "Fly Types" menu, as seen in <A HREF="#77004">Figure 5-2</A>.
 <P><CENTER><IMG SRC="foo.gif"></CENTER>  <P><CENTER><IMG SRC="foo.gif"></CENTER>
 <P><I>Figure 5-2: <A NAME="77004"></A></I>  <P><I>Figure 5-2: <A NAME="77004"></A></I>
 <I>Toggling the state of menu items in xFly</I>  <I>Toggling the state of menu items in xFly</I>
Line 281  dump(count + " items checked \n"); Line 284  dump(count + " items checked \n");
   
 <P>While the window and button events in <A HREF="#77020">Example 5-5</A> carry out some inline script, there is a variation with the <TT>onchange</TT> handler attached to the <TT>menulist</TT> element. <TT>onchange</TT> contains a JavaScript function call whose definition may live in the XUL document itself or in an external file that is included by using the <TT>src</TT> attribute on a <TT>script</TT> element:  <P>While the window and button events in <A HREF="#77020">Example 5-5</A> carry out some inline script, there is a variation with the <TT>onchange</TT> handler attached to the <TT>menulist</TT> element. <TT>onchange</TT> contains a JavaScript function call whose definition may live in the XUL document itself or in an external file that is included by using the <TT>src</TT> attribute on a <TT>script</TT> element:
 <PRE>&lt;script type="application/x-javascript" src="chrome://mypackage/content/myfile.js" /&gt;</PRE>  <PRE>&lt;script type="application/x-javascript" src="chrome://mypackage/content/myfile.js" /&gt;</PRE>
<P>A large basic set of event handler attributes is available for use on XUL elements (and HTML elements). <A HREF="appc.htm#77003">Appendix C</A> has a full listing of these events along with explanations. The following subset <!--INDEX attributes:event handling:XUL elements -->  shows the potential for script interaction when the UI uses event handlers:<P>A large basic set of event handler attributes is available for use on XUL elements (and HTML elements). <A HREF="appc.html#77003">Appendix 
 C</A> has a full listing of these events along with explanations. The following subset <!--INDEX attributes:event handling:XUL elements -->  shows the potential for script interaction when the UI uses event handlers:
 <PRE>onabort  <PRE>onabort
 onblur  onblur
 onerror  onerror
Line 562  retval=OK;</PRE> Line 566  retval=OK;</PRE>
 <I>How XPConnect fits into the application model</I>  <I>How XPConnect fits into the application model</I>
   
 <P>In Mozilla, XPConnect is the bridge between JavaScript and XPCOM components. The XPConnect technology wraps natively compiled components with JavaScript objects. XPCOM, Mozilla's own cross-platform component technology, is the framework on top of which these scriptable components are built. Using JavaScript and XPConnect, you can create instances of these components and use their methods and properties as you do any regular JavaScript object, as described here. You can access any or all of the functionality in Mozilla in this way.  <P>In Mozilla, XPConnect is the bridge between JavaScript and XPCOM components. The XPConnect technology wraps natively compiled components with JavaScript objects. XPCOM, Mozilla's own cross-platform component technology, is the framework on top of which these scriptable components are built. Using JavaScript and XPConnect, you can create instances of these components and use their methods and properties as you do any regular JavaScript object, as described here. You can access any or all of the functionality in Mozilla in this way.
<P><A HREF="ch08.htm#77048">Chapter 8</A> describes more about the XPConnect technology and how it connects components to the interface. It also describes the components themselves and their interfaces, the XPCOM technology, and how you can create your own XPCOM components.<P><A HREF="ch08.html#77048">Chapter 8</A> describes more about the XPConnect technology and how it connects components to the interface. It also 
 describes the components themselves and their interfaces, the XPCOM technology, and how you can create your own XPCOM components.
 <H4><A NAME="77067"></A> Creating XPCOM objects in script</H4>  <H4><A NAME="77067"></A> Creating XPCOM objects in script</H4>
<P><A HREF="#77030">Example 5-10</A> demonstrates  <!--INDEX XPCOM:methods:JavaScript implementation -->  <!--INDEX JavaScript:XPCOM objects, creating --> the creation and use of an  <!--INDEX XPCOM:components --> XPCOM component in JavaScript. In this example, the script instantiates the <TT>filepicker</TT> object and then uses it to display a file picker dialog with all of the file filters selected. To run this example, add the function to your <I>xfly.js</I> file and call it from an event handler on the "New" menu item you added in <A HREF="ch03.htm#77042">Example 3-5</A>.<P><A HREF="#77030">Example 5-10</A> demonstrates  <!--INDEX XPCOM:methods:JavaScript implementation -->  <!--INDEX JavaScript:XPCOM objects, 
 creating --> the creation and use of an  <!--INDEX XPCOM:components --> XPCOM component in JavaScript. In this example, the script instantiates the <TT>filepicker</TT> object and then uses it to display a file picker dialog with all of the file filters selected. To run this example, add the function to your <I>xfly.js</I> file and call it from an event handler on the "New" menu item you added in <A HREF="ch03.html#77042">Example 3-5</A>.
   
 Example 5-10<A NAME="77030"></A>  Example 5-10<A NAME="77030"></A>
 <I>Scriptable component example</I>  <I>Scriptable component example</I>
Line 610  Example 5-11<A NAME="77032"></A> Line 616  Example 5-11<A NAME="77032"></A>
  &lt;/body&gt;   &lt;/body&gt;
  &lt;/html&gt;</PRE>   &lt;/html&gt;</PRE>
   
<P>As in <A HREF="#77030">Example 5-10</A>, the classes[ ] array on the special Mozilla <TT>Components</TT> object refers to a particular component-in this case, the <TT>sound</TT> component-by contract ID. All XPCOM objects must have a contract ID that uniquely identifies them with the domain, the component name, and a version number ["@mozilla.org/sound;1"], respectively. See the <A HREF="ch08.htm#77058">"XPCOM Identifiers</A>" section in <A HREF="ch08.htm#77048">Chapter 8</A> for more information about this.<P>As in <A HREF="#77030">Example 5-10</A>, the classes[ ] array on the special Mozilla <TT>Components</TT> object refers to a particular 
 component-in this case, the <TT>sound</TT> component-by contract ID. All XPCOM objects must have a contract ID that uniquely identifies them with 
 the domain, the component name, and a version number ["@mozilla.org/sound;1"], respectively. See the <A HREF="ch08.html#77058">"XPCOM Identifiers</A>" section in <A HREF="ch08.html#77048">Chapter 8</A> for more information about this.
 <H4><A NAME="77068"></A> Finding components and interfaces</H4>  <H4><A NAME="77068"></A> Finding components and interfaces</H4>
 <P>Most <!--INDEX XPCOM:components:locating and viewing -->  components are scripted in Mozilla. In fact, the challenge is not to find cases when this scripting occurs (which you can learn by searching LXR for the <TT>Components</TT>), but to find Mozilla components that don't use scriptable components. Finding components and interfaces in Mozilla and seeing how they are used can be useful when writing your own application.  <P>Most <!--INDEX XPCOM:components:locating and viewing -->  components are scripted in Mozilla. In fact, the challenge is not to find cases when this scripting occurs (which you can learn by searching LXR for the <TT>Components</TT>), but to find Mozilla components that don't use scriptable components. Finding components and interfaces in Mozilla and seeing how they are used can be useful when writing your own application.
<P>The Mozilla  <!--INDEX Component Viewer development tool --> Component Viewer is a great tool for discovering components and provides a convenient UI for seeing components and looking at their interfaces from within Mozilla. The Component Viewer can be built as an extension to Mozilla (see "cview" in the extensions directory of the Mozilla source), or it can be downloaded and installed as a separate  <!--INDEX web sites:Component Viewer --> XPI from <I><A HREF="http://www.hacksrus.com/~ginda/cview/">http://www.hacksrus.com/~ginda/cview/</A></I>. <A HREF="appb.htm#77021">Appendix B</A> describes the Component Viewer in more detail.<P>The Mozilla  <!--INDEX Component Viewer development tool --> Component Viewer is a great tool for discovering components and provides a 
 convenient UI for seeing components and looking at their interfaces from within Mozilla. The Component Viewer can be built as an extension to Mozilla (see "cview" in the extensions directory of the Mozilla source), or it can be downloaded and installed as a separate  <!--INDEX web sites:Component Viewer --> XPI from <I><A HREF="http://www.hacksrus.com/~ginda/cview/">http://www.hacksrus.com/~ginda/cview/</A></I>. <A HREF="appb.html#77021">Appendix B</A> describes the Component Viewer in more detail.
 <P>Commonly used XPCOM objects in the browser and other Mozilla applications include file objects, RDF services, URL objects, and category managers.  <P>Commonly used XPCOM objects in the browser and other Mozilla applications include file objects, RDF services, URL objects, and category managers.
 <H4><A NAME="77069"></A> Selecting the appropriate interface from the component</H4>  <H4><A NAME="77069"></A> Selecting the appropriate interface from the component</H4>
 <P>In all cases,  <!--INDEX XPCOM:components:interfaces, selecting -->  <!--INDEX interfaces:XPCOM:components, selecting --> the way to get the object into script is to instantiate it with the special <TT>classes</TT> object and use the <TT>createInstance( )</TT> method on the class to select the interface you want to use. These two steps are often done together, as in the following example, which gets the component with the contract ID <TT>ldap-connection;1</TT>, instantiates an object from the <I>nsILDAPConnection</I> interface, and then calls a method on that object:  <P>In all cases,  <!--INDEX XPCOM:components:interfaces, selecting -->  <!--INDEX interfaces:XPCOM:components, selecting --> the way to get the object into script is to instantiate it with the special <TT>classes</TT> object and use the <TT>createInstance( )</TT> method on the class to select the interface you want to use. These two steps are often done together, as in the following example, which gets the component with the contract ID <TT>ldap-connection;1</TT>, instantiates an object from the <I>nsILDAPConnection</I> interface, and then calls a method on that object:
Line 634  generateGetTargetsBoundCallback( ));</PR Line 643  generateGetTargetsBoundCallback( ));</PR
 <P>Mozilla constantly uses these processes. Wherever functionality is organized into XPCOM objects (and most of it is), these two statements bring that functionality into JavaScript as high-level and user-friendly JavaScript objects.  <P>Mozilla constantly uses these processes. Wherever functionality is organized into XPCOM objects (and most of it is), these two statements bring that functionality into JavaScript as high-level and user-friendly JavaScript objects.
 <H2><A NAME="77070"></A> JavaScript Application Code</H2>  <H2><A NAME="77070"></A> JavaScript Application Code</H2>
 <P>There are <!--INDEX JavaScript:application programming:overview -->  <!--INDEX application programming, JavaScript:overview -->  two ways to use JavaScript in the third, deepest level of application programming. The first is to organize your JavaScript into libraries so your functions can be reused, distributed, and perhaps collaborated upon.  <P>There are <!--INDEX JavaScript:application programming:overview -->  <!--INDEX application programming, JavaScript:overview -->  two ways to use JavaScript in the third, deepest level of application programming. The first is to organize your JavaScript into libraries so your functions can be reused, distributed, and perhaps collaborated upon.
<P>The second way is to write a JavaScript component, create a separate interface for that component, and compile it as an XPCOM component whose methods and data can be accessed from XPConnect (using JavaScript). This kind of application programming is described in <A HREF="ch08.htm#77048">Chapter 8</A>, which includes examples of creating new interfaces, implementing them in JavaScript or C++, and compiling, testing, and using the resulting component in the Mozilla interface.<P>The second way is to write a JavaScript component, create a separate interface for that component, and compile it as an XPCOM component whose 
 methods and data can be accessed from XPConnect (using JavaScript). This kind of application programming is described in <A HREF="ch08.html#77048">Chapter 8</A>, which includes examples of creating new interfaces, implementing them in JavaScript or C++, and compiling, testing, and using the resulting component in the Mozilla interface.
 <P>This section introduces the library organization method of JavaScript application programming. The JSLib code discussed here is a group of JavaScript libraries currently being developed by Mozilla contributors and is especially useful for working with the XPFE and other aspects of the Mozilla application/package programming model. When you include the right source files at the top of your JavaScript and/or XUL file, you can use the functions defined in JSLib libraries as you would use any third-party library or built-in functions. You may even want to contribute to the JSLib project yourself if you think functionality is missing and as your Mozilla programming skills grow.  <P>This section introduces the library organization method of JavaScript application programming. The JSLib code discussed here is a group of JavaScript libraries currently being developed by Mozilla contributors and is especially useful for working with the XPFE and other aspects of the Mozilla application/package programming model. When you include the right source files at the top of your JavaScript and/or XUL file, you can use the functions defined in JSLib libraries as you would use any third-party library or built-in functions. You may even want to contribute to the JSLib project yourself if you think functionality is missing and as your Mozilla programming skills grow.
 <H3><A NAME="77071"></A> JavaScript Libraries</H3>  <H3><A NAME="77071"></A> JavaScript Libraries</H3>
 <P>The open  <!--INDEX JSLib libraries -->  <!--INDEX JavaScript:application programming:JSLib -->  <!--INDEX application programming, JavaScript:JSLib --> source JSLib project makes life easier for developers. The JSLib package implements some of the key XPCOM components just discussed and wraps them in simpler, JavaScript interfaces, which means that you can use the services of common XPCOM components without having to do any of the instantiation, interface selection, or glue code yourself. Collectively, these interfaces are intended to provide a general-purpose library for Mozilla application developers. To understand what JSLib does, consider the following short snippet from the JSLib source file <I>jslib/io/file.js</I>, which implements a <TT>close( )</TT> function for open file objects and provides a handy way to clean up things when you finish editing a file in the filesystem.  <P>The open  <!--INDEX JSLib libraries -->  <!--INDEX JavaScript:application programming:JSLib -->  <!--INDEX application programming, JavaScript:JSLib --> source JSLib project makes life easier for developers. The JSLib package implements some of the key XPCOM components just discussed and wraps them in simpler, JavaScript interfaces, which means that you can use the services of common XPCOM components without having to do any of the instantiation, interface selection, or glue code yourself. Collectively, these interfaces are intended to provide a general-purpose library for Mozilla application developers. To understand what JSLib does, consider the following short snippet from the JSLib source file <I>jslib/io/file.js</I>, which implements a <TT>close( )</TT> function for open file objects and provides a handy way to clean up things when you finish editing a file in the filesystem.
Line 694  src="chrome://jslib/content/jslib.js" /& Line 704  src="chrome://jslib/content/jslib.js" /&
 <PRE>include("chrome://jslib/content/io/file.js");  <PRE>include("chrome://jslib/content/io/file.js");
 include("chrome://jslib/content/zip/zip.js");</PRE>  include("chrome://jslib/content/zip/zip.js");</PRE>
 <H4><A NAME="77072"></A> Installing JSLib</H4>  <H4><A NAME="77072"></A> Installing JSLib</H4>
<P>To use the <!--INDEX installation:JSLib -->  <!--INDEX JSLib libraries:installing -->  <!--INDEX JavaScript:application programming:installing JSLib -->  <!--INDEX application programming, JavaScript:installing JSLib -->  JavaScript libraries, install the JSLib package in Mozilla. The package is available as a tarball, a zip file, or as CVS sources. The easiest way to obtain it is to install it from the Web using Mozilla's XPInstall technology, described in <A HREF="ch06.htm#77063">Chapter 6</A>.<P>To use the <!--INDEX installation:JSLib -->  <!--INDEX JSLib libraries:installing -->  <!--INDEX JavaScript:application programming:installing 
 JSLib -->  <!--INDEX application programming, JavaScript:installing JSLib -->  JavaScript libraries, install the JSLib package in Mozilla. The package is available as a tarball, a zip file, or as CVS sources. The easiest way to obtain it is to install it from the Web using Mozilla's XPInstall technology, described in <A HREF="ch06.html#77063">Chapter 6</A>.
 <P>Using your Mozilla browser, go to <I><A HREF="http://jslib.mozdev.org/installation.html">http://jslib.mozdev.org/installation.html</A></I> and click the installation hyperlink. The link uses XPInstall to install JSLIB and make it available to you in Mozilla. To test whether it is installed properly, type the following code in your shell:  <P>Using your Mozilla browser, go to <I><A HREF="http://jslib.mozdev.org/installation.html">http://jslib.mozdev.org/installation.html</A></I> and click the installation hyperlink. The link uses XPInstall to install JSLIB and make it available to you in Mozilla. To test whether it is installed properly, type the following code in your shell:
 <PRE>./mozilla -chrome chrome://jslib/content/</PRE>  <PRE>./mozilla -chrome chrome://jslib/content/</PRE>
 <P>You should see a simple window that says "welcome to jslib."  <P>You should see a simple window that says "welcome to jslib."

Removed from v.1.1  
changed lines
  Added in v.1.2


FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>