File:  [mozdev] / books / www / chapters / appb.html
Revision 1.11: download - view: text, annotated - select for diffs - revision graph
Fri Apr 4 16:27:40 2003 UTC (16 years, 8 months ago) by cdn
Branches: MAIN
CVS tags: HEAD
ahem

    1:     <link rel="prev" href="http://books.mozdev.org/chapters/appa.html" />
    2:     <link rel="next" href="http://books.mozdev.org/chapters/appc.html" />
    3: 
    4:     <style type="text/css">
    5:       div.c4 {text-align: center}
    6:       div.c3 {font-weight: bold; text-align: center}
    7:     </style>
    8: 
    9:     <h2>Appendix B</h2>
   10:     <h1><a name="77021"></a> Development Tools</h1>
   11:     <p>This book describes how to create applications using
   12:     Mozilla. Generally, all parts that go into an application
   13:     (including XUL, CSS, XBL, and DTD files) need to be built by
   14:     hand since no complete ready-made development tools or
   15:     development applications are available that would make these
   16:     manual processes easier.</p>
   17:     <p>Creating all these files by hand is a great way to
   18:     familiarize yourself with the way Mozilla works, and becoming
   19:     more familiar with the inner workings of a Mozilla application
   20:     certainly helps you see how the various parts fit together.
   21:     Once you are comfortable creating these files by hand, using
   22:     the platform becomes much easier and Mozilla fulfills its
   23:     promise as a rich application development framework.</p>
   24:     <p>Development tools are important, though, and platforms like
   25:     Mozilla can't obtain the sort of developer base they deserve
   26:     until tools that make application creation easier are
   27:     available. Although some people want to learn everything there
   28:     is to know about creating applications with Mozilla, many
   29:     simply want to create something without a lot of fuss.</p>
   30:     <p>Mozilla does not yet have a full set of development tools,
   31:     but currently several development projects help with part of
   32:     the application creation process. These tools don't make up a
   33:     full-featured development environment, but they are useful.
   34:     They also point the way to an area in Mozilla development that
   35:     has a bright future and is worth watching.</p>
   36:     <p>This appendix describes some of the new tools--including
   37:     XULKit, Patch Maker, the DOM Inspector, the JavaScript
   38:     Debugger, and MozillaTranslator--that are already becoming a
   39:     part of the regular repertoire of Mozilla developers. By
   40:     learning about how to use these tools for your own project, you
   41:     can radically simplify the application development process,
   42:     especially when you combine these tools.</p>
   43:     <h2><a name="77022"></a> XULKit</h2>
   44:     <p>Much of the manual 
   45:     <!--INDEX STARTRANGE==XULKit development tools --> 
   46:     <!--INDEX STARTRANGE==development:tools:XULKit --> editing
   47:     described in Chapters <a href="ch06.html#15291">6</a>, <a href=
   48:     "ch07.html#70326">7</a>, and <a href="ch08.html#78382">8</a>
   49:     can be automated with special scripts and templates being
   50:     developed in the Mozilla source tree's <i>tools/wizards</i>
   51:     section (these files are referred to collectively as the XULKit
   52:     and can be found at <i><a href=
   53:     "http://www.hacksrus.com/~ginda/xulkit/doc/">http://www.hacksrus.com/~ginda/xulkit/doc/</a></i>).</p>
   54:     <p>These tools help you develop your Mozilla application by
   55:     generating as much of the basic content, structure, and
   56:     packaging of an application as possible, leaving you free to
   57:     work only on the aspects of your application that you care
   58:     about. We mention XULKit first because it can make setting up
   59:     new Mozilla applications a snap.</p>
   60:     <p>XULKit is essentially a set of two scripts:
   61:     <i>new-from-template.pl</i>, which creates a new application
   62:     framework, and <i>makexpi.pl</i>, which packages your
   63:     application once you finish developing it.</p>
   64:     <h3><a name="77023"></a> new-from-template.pl Script</h3>
   65:     <p>Though it's not named very elegantly, the <i>
   66:     <!--INDEX new-from-template.pl Perl script (XULKit) --> 
   67:     <!--INDEX scripts:new-from-template.pl -->
   68:     new-from-template.pl</i> Perl script takes information you
   69:     provide in the form of a simple text file and uses it to create
   70:     various parts of a Mozilla application. These parts include the
   71:     XUL content, which has a basic menubar you can add to; an
   72:     overlay that puts an item for your application into the Tools
   73:     menu in the Mozilla browser; CSS for your XUL; and an
   74:     installation script for the application package. You can base
   75:     your application off of a couple of different templates,
   76:     including a sophisticated one that lets you generate XPCOM
   77:     interfaces for components you wish to use in your application,
   78:     described below.</p>
   79:     <p>Using these scripts, you can add content and logic to your
   80:     application, restyle it, or build your application however you
   81:     would like. You can also register the resulting directory with
   82:     the chrome registry to see it working in your local copy of
   83:     Mozilla, and when you finish developing it, the application
   84:     directory is already structured in exactly the way it must be
   85:     to be checked into the Mozilla source tree's extensions
   86:     directory (if you want to check it into this common location
   87:     for applications that become a part of Mozilla). When you want
   88:     to distribute your application as described in <a href=
   89:     "ch06.html#77063">Chapter 6</a>, you can use the other script
   90:     in the XULKit, <i>makexpi.pl</i>, to package your application
   91:     files into a cross-platform archive that can be installed from
   92:     a regular web page.</p>
   93:     <p>To use the <i>new-from-template.pl</i> script, point it at a
   94:     template that you filled out with your own information. It then
   95:     generates the basic application code in the appropriate
   96:     subdirectory structure:</p>
   97: <pre>
   98: new-from-template.pl      -t FILE [-o DIRECTORY] [-f[d]] [-h] [-?]
   99: </pre>
  100:     <p>When you run the script, the XULKit creates a new top-level
  101:     application directory. In this directory, the script creates
  102:     the three main package directories, and it places some basic
  103:     content in each one: a CSS file called <i>mozreg.css</i> in the
  104:     <i>skins</i> subdirectory, a few XUL files in the
  105:     <i>content</i> directory (including the overlay that defines a
  106:     new menu item for the main browser that opens this new
  107:     application), and localizable data in the <i>mozref.dtd</i>
  108:     file in the <i>locale</i> subdirectory.</p>
  109:     <p>In addition to these files, the XULKit script creates
  110:     <i>contents.rdf</i> files that describe each package, some
  111:     Makefiles that instruct the Mozilla build process how to
  112:     integrate this application into the build (which is a later
  113:     step and not necessary to run the application), and an
  114:     <i>install.js</i> file that executes the installation of this
  115:     application when it appears in a XPI. (See <a href=
  116:     "ch06.html#77063">Chapter 6</a> for more information about XPI,
  117:     Mozilla's cross-platform installation file format.)</p>
  118:     <p>If you look at Example B-1-<i>xul-app.tpl</i>, which comes
  119:     with the distribution of <i>new-from-template.pl-</i>you can
  120:     see how easy it is to fill out the basic information and create
  121:     your own template.</p>
  122:     <p><i>Example B-1: <a name="77016"></a></i> <i>Sample
  123:     application template</i></p>
  124: <pre>
  125: # load default template for a XUL app
  126: include "${top_wizard_dir}templates/xul-app.tpl"
  127: # short app name (can not contain spaces.)
  128: # until <a href=
  129: "http://bugzilla.mozilla.org/show_bug.cgi?id=75670">http://bugzilla.mozilla.org/show_bug.cgi?id=75670</a> is fixed, this needs
  130: # to be all lowercase.
  131: app_name_short=xulsample
  132: # long app name (spaces are OK.)
  133: app_name_long=Sample XUL Application (generated from sample.xul-app.tpl)
  134: # name as it should appear in the menu
  135: app_name_menu=Sample XUL App
  136: # version to tell the .xpi installer
  137: app_version=1.0
  138: # author, used in various chrome and app registration calls
  139: app_author=mozilla.org
  140: # size of the package when installed, in kilobytes.
  141: # this number is used by the install.js script to check for enough disk space
  142: # before the .xpi is installed.  You can just guess for now, or put 1, and fix it
  143: # in install.js before you make your .xpi file.
  144: install_size_kilobytes=1
  145: </pre>
  146:     <p>You can adapt the <i>xul-app.tpl</i> for your own purposes
  147:     or use the <i>sample.xul-app.tpl</i> that is already filled
  148:     out. Table B-1 details different options for
  149:     <i>new-from-template.pl</i>.</p>
  150:     <p><i>Table B-1: <a name="77010"></a></i> <i>Options for the
  151:     new-from-template.pl script</i></p>
  152:     <tt>-f</tt>option.<tt>-o</tt>. The template will not be
  153:     processed. The template description is taken from the value of
  154:     the <i>template_description</i>variable in the template file.
  155:     template_description<tt>s</tt>provided by the main template
  156:     file's template file(s) are not displayed.<tt>DIRECTORY</tt>.
  157:     If this directory already exists,
  158:     <i>new-from-template.pl</i>will fail. This failure prevents you
  159:     from accidentally overwriting an existing application. Use the
  160:     <tt>-f</tt>option to continue anyway. Use <tt>-fd</tt>to force
  161:     <tt>DIRECTORY</tt>to be deleted before the template is
  162:     processed.<tt>TEMPLATE</tt>. This file is usually in the <i>my/
  163:     sub-directory</i>, ending in <i>.tpl</i>.
  164:     <table width="100%" border="1">
  165:       <tr>
  166:         <td><b>Option</b></td>
  167:         <td><b>Description</b></td>
  168:       </tr>
  169:       <tr>
  170:         <td>-d</td>
  171:         <td>Recursively deletes the output directory before
  172:         starting; requires the</td>
  173:       </tr>
  174:       <tr>
  175:         <td>-f</td>
  176:         <td>Forces file overwriting in the output directory.</td>
  177:       </tr>
  178:       <tr>
  179:         <td>-h</td>
  180:         <td>Displays a description of the specified template
  181:         with</td>
  182:       </tr>
  183:       <tr>
  184:         <td>-o DIRECTORY</td>
  185:         <td>Generates the template into the directory specified
  186:         by</td>
  187:       </tr>
  188:       <tr>
  189:         <td>-t TEMPLATE</td>
  190:         <td>Processes the template specified by</td>
  191:       </tr>
  192:       <tr>
  193:         <td>-?</td>
  194:         <td>Shows usage information and exits.</td>
  195:       </tr>
  196:     </table>
  197:     <h4><a name="77024"></a> XULKit templates</h4>
  198:     <p>Two different <!--INDEX templates:XULKit tools -->
  199:     application templates come with <i>new-from-template.tpl</i>,
  200:     each with its own empty and sample versions. Example B-1 shows
  201:     <i>sample.xul-app.tpl</i> in its entirety. The other template,
  202:     <i>xpcom-component.tpl</i>, uses information you supply to
  203:     create the framework for an XPCOM component. As with
  204:     <i>xul-app.tpl</i>, the template comes with a sample that's
  205:     already filled out.</p>
  206:     <p>This script creates an IDL file, a header file, and a
  207:     stubbed-out CPP file in an application subdirectory structure
  208:     you can use to begin coding your XPCOM component. In the
  209:     <i>xpcom-component.tpl</i>, many variables do not need to be
  210:     changed, but required fields are set aside in the template:</p>
  211: <pre>
  212: # variables the user's .tpl file MUST declare
  213: required_variables = ${component_name}, ${implementation_guid}, \
  214: ${interface_name}, ${interface_guid}
  215: </pre>
  216:     <p>Using this script, you can fill out a subset of the template
  217:     with the information XPCOM requires, and XPCOM will generate
  218:     the basic files you need, as Example B-2 shows.</p>
  219:     <p><i>Example B-2: <a name="77018"></a></i> <i>Sample XPCOM
  220:     component template</i></p>
  221: <pre>
  222:  # include default values
  223:  include "${top_wizard_dir}templates/xpcom-component.tpl"
  224:  component_name      = SampleComponent
  225:  implementation_guid = c6793b0c-1dd1-11b2-a246-92bf95c9d097
  226:  interface_name      = tstISampleComponent
  227:  interface_guid      = d03ea960-1dd1-11b2-9682-81ecad6a042a
  228: </pre>
  229:     <h3><a name="77025"></a> makexpi.pl Script</h3>
  230:     <p>In addition to the template-generating script described
  231:     above, a second script takes your working application and
  232:     creates an installable package, or XPI, out of it. This way,
  233:     you can distribute it to others in the same way the various
  234:     components of the Mozilla browser are distributed and installed
  235:     when you use the Mozilla installer.</p>
  236:     <p>This script, <i>
  237:     <!--INDEX makexpi.pl Perl script (XULKit tools) --> 
  238:     <!--INDEX scripts:makexpi.pl --> makexpi.pl</i>, takes an
  239:     application directory as input and generates an XPI archive. It
  240:     also manifests for various parts of your application, the
  241:     installation script that goes inside this archive, and even the
  242:     installation web page itself. While <i>new-from-template.pl</i>
  243:     is designed to help you start your application,
  244:     <i>makexpi.pl</i> takes your locally developed application and
  245:     makes it into a package that can be distributed to other users
  246:     and installed via the Web.</p>
  247:     <p>To use <i>makexpi.pl</i>, point it at a configuration file
  248:     that you have edited to point at your application
  249:     directory:</p>
  250: <pre>
  251: makexpi.pl      [-c &lt;config-file&gt;] [-d] [-r &lt;revision&gt;] [-?]
  252: </pre>
  253:     <p>For example, to create a XPI out of your <i>MyApp</i>
  254:     application directory, in which you created a file called
  255:     <i>MyApp.conf</i> that defines the variables <i>makexpi.pl</i>
  256:     needs, execute the script as follows:</p>
  257: <pre>
  258: perl makexpi.pl -c ~/appdev/MyApp/makexpi.conf -r 0.9.9
  259: </pre>
  260:     <p>A <i>makexpi.conf</i> file defines the variables
  261:     <i>makexpi.pl</i> needs to know about. Example B-3 shows an
  262:     example of this file.</p>
  263:     <p><i>Example B-3: <a name="77020"></a></i> <i>makexpi.conf
  264:     file</i></p>
  265: <pre>
  266:  # directory where xpi should be created
  267:  workdir     = /home/rginda/src/xulkit/sample-app/
  268:  # directory where jar.mn is
  269:  mndir       = ${workdir}/sampleapp/resources/
  270:  # location of templatized install.js file
  271:  installfile = ${xulkit_dir}/templates/xpi/install.js
  272:  # directory where mozilla's make-jars.pl and friends are
  273:  mozcfgdir   = ${xulkit_dir}/bin/
  274:  # name of resulting xpi file
  275:  xpifile = ${app_name_short}-${revision}.xpi
  276: </pre>
  277:     <p>Table B-2 lists the options that are recognized by
  278:     <i>makexpi.pl</i>.</p>
  279:     <p><i>Table B-2: <a name="77012"></a></i> <i>Options for the
  280:     makexpi.pl script</i></p>
  281:     <i>chrome/</i>directory as an XPI.<i>${revision}</i>variable.
  282:     This specification overrides any value specified in the
  283:     configuration file and defaults to ``0.01''. Typically, this
  284:     number is used in the <i>install.js</i>script and as part of
  285:     the XPI filename.
  286:     <table width="100%" border="1">
  287:       <tr>
  288:         <td><b>Options</b></td>
  289:         <td><b>Description</b></td>
  290:       </tr>
  291:       <tr>
  292:         <td>-c FILE</td>
  293:         <td>Specifies the configuration file to use.</td>
  294:       </tr>
  295:       <tr>
  296:         <td>-d</td>
  297:         <td>Doesn't remake the JAR, but packages the existing
  298:         contents of the</td>
  299:       </tr>
  300:       <tr>
  301:         <td>-r REVISION</td>
  302:         <td>Specifies the value of the</td>
  303:       </tr>
  304:       <tr>
  305:         <td>-?</td>
  306:         <td>Shows usage information and exits.</td>
  307:       </tr>
  308:     </table>
  309:     <p>When you run the script against the configuration file, you
  310:     end up with two separate pieces-the XPI in which your
  311:     application and its installation script are stored and a web
  312:     page that you can post on a server to guide the XPI's
  313:     installation. As described in <a href="ch06.html#77063">Chapter
  314:     6</a>, the web page interacts with the XPI's <i>install.js</i>
  315:     to install and register your application in Mozilla. If you
  316:     start your application with the <i>new-from-template.pl</i>
  317:     script, then a template-processed version of <i>install.js</i>
  318:     that works with your application is included as
  319:     <i>templates/xpi/install.js</i> as part of the XULKit
  320:     package.</p>
  321:     <h3><a name="77026"></a> Using XULKit</h3>
  322:     <p>Given these two scripts and the templates that go with them,
  323:     the XULKit encourages and makes the following application
  324:     development workflow possible:</p>
  325:     <ol>
  326:       <li>Fill out a <i>new-from-template.pl</i> template with your
  327:       application information.</li>
  328:       <li>Run the <i>new-from-template.pl</i> script to generate
  329:       the application directory.</li>
  330:       <li>Register your application in flat mode: as a directory in
  331:       your local copy of Mozilla.</li>
  332:       <li>Develop your application: the XUL content, the CSS, the
  333:       application code in JS, etc.</li>
  334:       <li>Test the application code.</li>
  335:       <li>Run <i>makexpi.pl</i> against your working application to
  336:       create an installable package.</li>
  337:       <li>Put the XPI and the web page up on a server to create an
  338:       install for your application.</li>
  339:     </ol>
  340:     <p>That's <!--INDEX ENDRANGE==XULKit development tools --> 
  341:     <!--INDEX ENDRANGE==development:tools:XULKit --> it!</p>
  342:     <h2><a name="77027"></a> Patch Maker 2.0</h2>
  343:     <p>Patch Maker 
  344:     <!--INDEX STARTRANGE==Patch Maker development tool --> 
  345:     <!--INDEX STARTRANGE==development:tools:Patch Maker --> is a
  346:     free software program written by Gervase Markham that lets you
  347:     change and improve Mozilla's user interface by using only a
  348:     nightly build.</p>
  349:     <p>When you don't build the Mozilla source tree yourself,
  350:     finding and getting to the files that need to be edited in
  351:     Mozilla can be difficult. However, you can use the various
  352:     Patch Maker commands in Build Mode to extract files from the
  353:     right JARs, add them to your Patch Maker project, edit them,
  354:     and create the patches, all in an integrated and easily
  355:     traceable way. These patches can then be submitted back to
  356:     mozilla.org so that developers working in the source tree can
  357:     apply and test them. See the <a href="#77029">"Build Mode</a>"
  358:     section later in this appendix for more information about using
  359:     Patch Maker in this way.</p>
  360:     <p>This process is possible because Mozilla's user interface is
  361:     written in XUL, JavaScript, and CSS, and interpreted at
  362:     runtime. Because understanding CVS or compiling code isn't
  363:     necessary, Patch Maker greatly lowers the barrier to entry for
  364:     contributing code to Mozilla. Significant patches, such as one
  365:     used for draggable toolbars, are made using this tool.</p>
  366:     <p>Patch Maker runs under Linux and Windows, and is
  367:     experimental on Mac OS X. The latest version of Patch Maker is
  368:     at <i><a href=
  369:     "http://www.gerv.net/software/patch-maker/">http://www.gerv.net/software/patch-maker/</a></i>.
  370:     This application can be used in one of two modes. CVS mode is
  371:     used by developers who develop and maintain code in a CVS tree
  372:     and make their changes in the tree. Build mode makes it
  373:     possible to produce patches that fix some bugs in Mozilla
  374:     without downloading and compiling the source.</p>
  375:     <h3><a name="77028"></a> CVS Mode</h3>
  376:     <p>In CVS mode, Patch Maker manages and tracks multiple patches
  377:     to a bit of software. It uses unique tags (patch references
  378:     such as bug numbers) to separate patches, knows what files are
  379:     in each patch, and can perform operations on them. In CVS mode,
  380:     Patch Maker can greatly speed up the process of creating,
  381:     diffing, uploading, refreshing, and checking in a patch. CVS
  382:     mode's basic commands for Patch Maker give you an idea of how
  383:     developers working in the Mozilla source tree can use it to
  384:     work more efficiently with patches and diffs. The basic CVS
  385:     mode commands are described in Table B-3.</p>
  386:     <p><i>Table B-3: <a name="77014"></a></i> <i>Patch Maker's CVS
  387:     mode commands</i></p>
  388:     &gt; <tt><i>filename</i></tt>to the file list.&gt;
  389:     <tt><i>filename</i></tt>from the file list.<tt>diff -u</tt>of
  390:     all files in the file list. Extra arguments, such as
  391:     <tt>-w</tt>, are passed through to diff. This command won't
  392:     clobber your old diff if the new one has a size of
  393:     zero.<tt>-R</tt>to back the patch out again.<tt>pmupdate(
  394:     )</tt>and a <tt>pmpatch( )</tt>(which won't have any effect if
  395:     the patch is already applied.)<tt><i>pattern</i></tt>in all of
  396:     the current patch's files. Good if you can't remember where you
  397:     put some code.<tt>-f</tt>argument to force copying of all the
  398:     files.<i>chrome</i>directory. Use
  399:     <i>/usr/src/mozilla/dist/bin/chrome/</i>if you build
  400:     yourself.<tt>&amp;</tt>, are passed through to the
  401:     executable.<tt>pmwhich</tt>, <tt>pmupdate</tt>,
  402:     <tt>pmdiff</tt>, and <tt>pmview</tt>to show what you are about
  403:     to change, and then asks you if you really want to check in.
  404:     <table width="100%" border="1">
  405:       <tr>
  406:         <td><b>Command</b></td>
  407:         <td><b>Description</b></td>
  408:       </tr>
  409:       <tr>
  410:         <td>pmlist</td>
  411:         <td>Shows the file list.</td>
  412:       </tr>
  413:       <tr>
  414:         <td>pmadd &lt;filename</td>
  415:         <td>Adds</td>
  416:       </tr>
  417:       <tr>
  418:         <td>pmremove &lt;filename</td>
  419:         <td>Removes</td>
  420:       </tr>
  421:       <tr>
  422:         <td>pmdiff</td>
  423:         <td>Does a cvs</td>
  424:       </tr>
  425:       <tr>
  426:         <td>pmview</td>
  427:         <td>Brings up your diff in an editor window.</td>
  428:       </tr>
  429:       <tr>
  430:         <td>pmupdate</td>
  431:         <td>Updates CVS on all files in the file list. Extra
  432:         arguments to this command are passed through to the CVS
  433:         update.</td>
  434:       </tr>
  435:       <tr>
  436:         <td>pmpatch</td>
  437:         <td>Patches your diff into your CVS tree. Takes a</td>
  438:       </tr>
  439:       <tr>
  440:         <td>pmedit &lt;pattern&gt;</td>
  441:         <td>Brings up files matching the pattern in your editor.
  442:         The pattern is a glob, not a regexp. If there are no
  443:         arguments supplied, then all files are opened.</td>
  444:       </tr>
  445:       <tr>
  446:         <td>pmwhich</td>
  447:         <td>Prints the current patch reference.</td>
  448:       </tr>
  449:       <tr>
  450:         <td>pmswitch &lt;patchref&gt;</td>
  451:         <td>Changes Patch Maker to work with a new patch reference.
  452:         It automatically creates a</td>
  453:       </tr>
  454:       <tr>
  455:         <td>pmgrep &lt;pattern&gt;</td>
  456:         <td>Greps for</td>
  457:       </tr>
  458:       <tr>
  459:         <td>pmcopy</td>
  460:         <td>Copies all files in the file list to their positions in
  461:         your installed Mozilla tree. Takes a</td>
  462:       </tr>
  463:       <tr>
  464:         <td>pmsetpath</td>
  465:         <td>Points Patch Maker to your current Mozilla-built
  466:         installation's</td>
  467:       </tr>
  468:       <tr>
  469:         <td>pmunjar</td>
  470:         <td>Unjars the chrome in your setpath installation.</td>
  471:       </tr>
  472:       <tr>
  473:         <td>pmexecute</td>
  474:         <td>Runs the executable in the setpath installation. Extra
  475:         arguments to this command, such as</td>
  476:       </tr>
  477:       <tr>
  478:         <td>pmcheckin</td>
  479:         <td>Runs</td>
  480:       </tr>
  481:       <tr>
  482:         <td>pmcvsadd</td>
  483:         <td>Does a CVS add of all files. Previously added files
  484:         fail with a harmless message. You need to use this command
  485:         for new files so the CVS diff will work properly.</td>
  486:       </tr>
  487:     </table>
  488:     <p>See the CVS Mode instructions at the Patch Maker web site
  489:     for instructions on how to use Patch Maker with your source
  490:     tree.</p>
  491:     <h3><a name="77029"></a> Build Mode</h3>
  492:     <p>The fact that Mozilla's user interface is interpreted at
  493:     runtime rather than compile time makes it possible to change
  494:     the interface and see your changes in the browser. In Build
  495:     mode, Patch Maker can help you make these changes and apply,
  496:     package, and send them to the developers who own the interface
  497:     modules you edit. The Patch Maker's Build mode is a boon for
  498:     Mozilla developers who do not build the CVS tree, but who want
  499:     to take part in developing the interface, in the bug-fixing
  500:     process, and in other aspects of Mozilla development.</p>
  501:     <p>In Mozilla-specific mode, which is triggered when you sit in
  502:     a Mozilla build install point's chrome directory, you can make
  503:     patches to Mozilla chrome without using a CVS tree. Patch Maker
  504:     can cope with multiple patches and has a notion of the "current
  505:     patch"-the one you are working on at the moment. Patches are
  506:     identified by a patch reference, or patchref, which is any
  507:     combination of characters that make a legal filename on your
  508:     platform. Bug numbers make very good patchrefs. You can add and
  509:     remove files from Patch Maker's internal list of files that
  510:     comprise the current patch.</p>
  511:     <h4><a name="77030"></a> Using Patch Maker in Build mode</h4>
  512:     <p>Here are the steps to use Patch Maker in Build mode (flip
  513:     the slashes in these paths if you are on Windows):</p>
  514:     <ol>
  515:       <li>Set up Patch Maker (see the installation instructions at
  516:       <i><a href=
  517:       "http://www.gerv.net/software/patch-maker/build-mode.html">http://www.gerv.net/software/patch-maker/build-mode.html</a></i>).</li>
  518:       <li>Change to the chrome directory of a Mozilla nightly
  519:       build.</li>
  520:       <li>Execute <tt>pmuj</tt> to unjar your chrome.</li>
  521:       <li>Run Mozilla (../mozilla) to see if it still works. Turn
  522:       off the XUL cache in the Debug &gt; Networking preferences
  523:       and quit Mozilla.</li>
  524:       <li>Execute pms test. Patch Maker will tell you that you are
  525:       working on patch "test."</li>
  526:       <li>Confirm this with pmw.</li>
  527:       <li>Execute pml. Note that no files are currently in your
  528:       patch.</li>
  529:       <li>Execute pma content/navigator/navigator.xul to add
  530:       <i>navigator.xul</i> to your patch.</li>
  531:       <li>Execute <tt>pml</tt> again and see if it was added.
  532:       Experiment with <tt>pma</tt> and <tt>pmr</tt> if you
  533:       like.</li>
  534:       <li>Execute <tt>pme</tt>. Notice that <i>navigator.xul</i>
  535:       appears in your editor. Try <tt>pme</tt> <tt>foo</tt> to make
  536:       sure you have no files that match "foo."</li>
  537:       <li>Change <i>navigator.xul-</i>e.g., search for
  538:       "&amp;mainWindow.title;" and replace that string with
  539:       "MyBrowser." Save this file.</li>
  540:       <li>Run Mozilla (../mozilla).</li>
  541:       <li>You should have a Mozilla titled "MyBrowser."</li>
  542:       <li>Edit the file again to make it "YourBrowser." Save the
  543:       file.</li>
  544:       <li>Press Ctrl-N in your Mozilla window. The new window
  545:       should be titled "YourBrowser."</li>
  546:       <li>Execute <tt>pmd</tt> and <tt>pmv</tt>. You should now
  547:       have an editor window with a unified diff showing the changes
  548:       you made.</li>
  549:       <li>You could attach your patch to a Bugzilla bug by fishing
  550:       the CVS version (<i>test.diff</i>) out of your Patch Maker
  551:       data <!--INDEX ENDRANGE==Patch Maker development tool --> 
  552:       <!--INDEX ENDRANGE==development:tools:Patch Maker -->
  553:       directory.</li>
  554:     </ol>
  555:     <h2><a name="77031"></a> The DOM Inspector</h2>
  556:     <p>The DOM Inspector 
  557:     <!--INDEX DOM Inspector development tool --> 
  558:     <!--INDEX development:tools:DOM Inspector --> tool, which is
  559:     now installed by default in the Mozilla browser and accessible
  560:     from Tools &gt; Web Development, displays the document object
  561:     mode of any document or part of the interface and allows you to
  562:     update that DOM dynamically by changing attribute values,
  563:     rearranging the structured content, or deleting nodes.</p>
  564:     <blockquote>
  565:       <div class="c3">
  566:         NOTE
  567:       </div>
  568:       <p>The DOM Inspector reads the DOM of the requested window or
  569:       document into memory, where you can manipulate it. However,
  570:       the DOM Inspector does not persist your changes back out to
  571:       the file from which that DOM was originally loaded.</p>
  572:     </blockquote>
  573:     <p>If you use JavaScript in the interface or to manipulate web
  574:     pages, then you will recognize what a powerful tool it can
  575:     be-particularly given how hard it can be to see the interface's
  576:     object model clearly and figure out which nodes in the DOM
  577:     correspond to which parts of the displayed interface. The DOM
  578:     Inspector also allows you to inspect local files and URLs.</p>
  579:     <p>To open a file for inspection in the DOM Inspector, choose
  580:     either File &gt; Inspect a Window or Inspect a URL . . . and
  581:     enter the URL of the web document you want to inspect in the
  582:     dialog. When the DOM Inspector loads a document, it displays
  583:     the DOM (as shown in Figure B-1 of that document) as a tree
  584:     structure on the lefthand side and the individual nodes with
  585:     their attributes and other information on the righthand
  586:     side.</p>
  587:     <div class="c4">
  588:       <img src="foo.gif">
  589:     </div>
  590:     <p><i>Figure B-1: <a name="77002"></a></i> <i>The DOM inspector
  591:     interface</i></p>
  592:     <p>As you click on the nodes in the tree in the left panel, the
  593:     DOM Inspector highlights the nodes that are part of the visible
  594:     interface by pointing them out with a blinking red border. You
  595:     can peck through the tree in the DOM Inspector and find all
  596:     parts of the interface.</p>
  597:     <p>The DOM Inspector also displays any anonymous content that
  598:     is part of the window. See <a href="ch07.html#77027">Chapter
  599:     7</a> for information about anonymous content and the way it
  600:     relates to the DOM. The anonymous content nodes that are bound
  601:     to the window you specify become part of the DOM that the
  602:     Inspector reads and can be analyzed and manipulated like any
  603:     other node.</p>
  604:     <p>The pull-down widgets to the left of the pane headers let
  605:     you select which portions of the DOM are displayed in the
  606:     panels. By default, the DOM nodes are displayed, as shown in
  607:     Figure B-1, but you can also display the associated
  608:     stylesheets, the Java-Script objects, the XBL bindings, the
  609:     document's box model, and other information.</p>
  610:     <h2><a name="77032"></a> The Component Viewer</h2>
  611:     <p>The <!--INDEX Component Viewer development tool --> 
  612:     <!--INDEX development:tools:Component Viewer --> Component
  613:     Viewer is a Mozilla application that displays all components
  614:     and interfaces available to the XPCOM developer on the Mozilla
  615:     platform. It is not installed by default in the Mozilla
  616:     browser, like the DOM Inspector, but you can get binary
  617:     installations that have it or you can build it from
  618:     <i>mozilla/extensios/cview</i> if you use CVS.</p>
  619:     <p>Discovering components and interfaces is actually one of the
  620:     trickier aspects of developing applications with Mozilla, so
  621:     this tool can help you when you are at the initial stages of
  622:     your application development and want to see which XPCOM
  623:     components and interfaces are available. As shown in Figure
  624:     B-2, the Component Viewer interface, like the DOM Inspector,
  625:     has two main panels. The left side shows all components in
  626:     Mozilla and the right side shows all interfaces.</p>
  627:     <div class="c4">
  628:       <img src="foo.gif">
  629:     </div>
  630:     <p><i>Figure B-2: <a name="77004"></a></i> <i>An interface
  631:     displayed in the Component Viewer</i></p>
  632:     <p>In XPCOM, a single component can implement more than one
  633:     interface. Thus, for example, the editor shell component
  634:     (<i>@mozilla.org/editor/editorshell;1</i>) implements
  635:     <i>nsIURIContentListener</i>, <i>nsIEditorShell</i>,
  636:     <i>nsIEditorSpellCheck</i>, and others. If you open the
  637:     interfaces, you will see the various methods those interfaces
  638:     define. You can also right-click in the component viewer and
  639:     access a context menu that lets you look up the selected item
  640:     in LXR, which is the web-based source viewer for Mozilla.</p>
  641:     <h2><a name="77033"></a> Venkman: The JavaScript Debugger</h2>
  642:     <p>Venkman is 
  643:     <!--INDEX STARTRANGE==Venkman development tool --> 
  644:     <!--INDEX STARTRANGE==development:tools:Venkman --> both a
  645:     graphical and a console debugger. It is one of the most
  646:     sophisticated examples of a Mozilla application and an
  647:     indispensable tool for the many developing applications and web
  648:     pages that rely on JavaScript. Like the DOM Inspector, you can
  649:     access the JavaScript Debugger from the Tools &gt; Web
  650:     Development menu (if it was selected during the Mozilla install
  651:     process). Figure B-3 shows Venkman in action.</p>
  652:     <div class="c4">
  653:       <img src="foo.gif">
  654:     </div>
  655:     <p><i>Figure B-3: <a name="77006"></a></i> <i>The JavaScript
  656:     Debugger</i></p>
  657:     <p>Features such as breakpoint management, call stack
  658:     inspection, and variable/object inspection are available from
  659:     both the graphic interface and the console commands. The
  660:     interactive console allows execution of arbitrary JavaScript
  661:     code in the context of the target application and in the
  662:     debugger's own context. Profiling measures the execution time
  663:     of JavaScript functions during debugging, and pretty printing
  664:     can re-indent and line wrap a poorly formatted function.</p>
  665:     <p>Keyboard shortcuts for the <tt>step</tt> commands are the
  666:     same as in other common visual debugging environments, and
  667:     console users should be familiar with Venkman's <tt>break</tt>,
  668:     <tt>step</tt>, <tt>next</tt>, <tt>finish</tt>, <tt>frame</tt>,
  669:     and <tt>where</tt> commands.</p>
  670:     <p>Venkman consists of eight main interface elements, referred
  671:     to as "views." These views display information such as local
  672:     variables, source code, and the interactive console. They can
  673:     be detached from the main window to save space on your desktop,
  674:     or they can be hidden. The Venkman project page at <i><a href=
  675:     "http://www.mozilla.org/projects/venkman/">http://www.mozilla.org/projects/venkman/</a></i>
  676:     describes these views and their modes of operation.</p>
  677:     <p>Users can use a JavaScript API to add to the set of commands
  678:     and views provided with Venkman. These add-ons can be shared
  679:     among a project team or provided to the general public. The
  680:     details of that API are not yet documented, but examples are
  681:     found in Venkman itself. If you install Venkman,
  682:     <i>chrome://venkman/content/venkman-commands.js</i> and
  683:     <i>chrome://venkman/content/venkman-views.js</i> will contain
  684:     Venkman's default commands and views.</p>
  685:     <p>The following sample session introduces you to the basic
  686:     commands and use of the JavaScript Debugger. This sample
  687:     session is based on the version of Venkman available at the
  688:     time the book was written. To find out how to use the latest
  689:     version of Venkman, read the Venkman walkthrough at <i><a href=
  690:     "http://www.mozilla.org/projects/venkman/venkman-walkthrough.html">
  691:     http://www.mozilla.org/projects/venkman/venkman-walkthrough.html</a></i>.</p>
  692:     <ol>
  693:       <li>
  694:         Invoke the <tt>-venkman</tt> command-line argument by
  695:         typing mozilla -venkman to start Mozilla.
  696:         <p>You must start the debugger before the scripts it edits
  697:         can be debugged. If you want to debug the file
  698:         <i>navigator.xul</i>, for example, then Venkman must load
  699:         before the main browser window. This limitation will either
  700:         be fixed or worked around later. For the time being, you
  701:         need to start the debugger first to debug browser
  702:         chrome.</p>
  703:         <p>Debugging JavaScript components is another example of
  704:         when scripts must be loaded before the debugger is
  705:         initialized. Because component registration occurs before
  706:         command-line processing, when a component changes, it is
  707:         reloaded at registration time and the debugger does not see
  708:         it. Currently, the only way to work around it is to start
  709:         the browser twice: once to re-register the modified
  710:         component and once to debug it.</p>
  711:       </li>
  712:       <li>Launch a browser window and select "Navigator" from the
  713:       debugger's Tasks menu.</li>
  714:       <li>
  715:         Type break ContextMenu 357 in the debugger.
  716:         <p>The console command break is set and lists breakpoints.
  717:         The first parameter is the filename that contains the
  718:         JavaScript you want to break at. The second parameter is
  719:         the line number. You don't need to specify the entire
  720:         filename. In this example, we are setting a breakpoint in
  721:         the function called when the browser wants to create a
  722:         context menu for web content.</p>
  723:         <p>Or, you could select <i>nsContextMenu.js</i> from the
  724:         Scripts View, locate line 357, and click in the left
  725:         margin. Setting breakpoints in this way is equivalent to
  726:         using the <tt>break</tt> command in the console.</p>
  727:       </li>
  728:       <li>
  729:         Type break in the debugger.
  730:         <p>If you don't provide arguments to the <tt>break</tt>
  731:         command, all breakpoints are listed.</p>
  732:       </li>
  733:       <li>
  734:         Create a context menu in the Navigator window.
  735:         <p>A right-click in the content area creates a context
  736:         menu. You should have hit the breakpoint you just set. The
  737:         debugger should have displayed "Stopped for breakpoint,"
  738:         along with the filename, line number, and snippet source
  739:         code where it stopped from.</p>
  740:       </li>
  741:       <li>
  742:         Type step in the debugger.
  743:         <p>This command executes the line of JavaScript we're
  744:         stopped on and stops again before the next line is
  745:         executed. The <tt>step</tt> command is also available via
  746:         the "Step Into" button on the toolbar and is bound to the
  747:         F11 key.</p>
  748:         <p>In addition to Step In, which executes a single line of
  749:         JavaScript and stops, Step Over steps over a impending
  750:         function call and returns control to the debugger when the
  751:         call returns. Step Out executes until the current function
  752:         call exits. At this point, you should be at line 359,
  753:         <tt>this.onTextInput</tt> <tt>=</tt>
  754:         <tt>this.isTargetATextBox(elem);</tt>.</p>
  755:       </li>
  756:       <li>
  757:         Type props this in the debugger.
  758:         <p>The <tt>props</tt> command lists an object's properties.
  759:         The letters and dashes before the values are the flags for
  760:         that value. The flags are enumerated in <a href=
  761:         "#77006">Figure B-3</a>, previously shown.</p>
  762:       </li>
  763:       <li>Step one more time.</li>
  764:       <li>You should be in the <tt>isTargetATextBox</tt> function
  765:       call now.</li>
  766:       <li>
  767:         Type frame in the debugger.
  768:         <p>When used without arguments, the <tt>frame</tt> command
  769:         shows you the source code for the current frame (with a few
  770:         lines of context).</p>
  771:       </li>
  772:       <li>
  773:         Type scope in the debugger.
  774:         <p>The <tt>scope</tt> command lists the current frame's
  775:         local variables. In this case, there are two locals: node
  776:         and attrib. The node property is an argument to the
  777:         function, while attrib is a local variable. The scope is
  778:         also visible in the Stack View. Open the [isTargetATextBox]
  779:         frame and the scope node below it.</p>
  780:       </li>
  781:       <li>
  782:         Type where in the debugger.
  783:         <p>The <tt>where</tt> command lists the current call stack.
  784:         The <tt>frame</tt> command can be used to change the
  785:         current frame to any frame listed here. For example, to
  786:         view variables in the code that called
  787:         <tt>isTargetATextBox</tt>, type frame 1, and scope. To
  788:         return to the top frame, type frame 0.</p>
  789:       </li>
  790:       <li>
  791:         Type eval window._content.
  792:         <p>The <tt>eval</tt> command evaluates arbitrary JavaScript
  793:         in the current frame. Running the <tt>eval</tt> command on
  794:         <tt>window._content</tt> itself isn't very useful, so
  795:         you'll have to think of something more creative.</p>
  796:       </li>
  797:       <li>
  798:         Type break.
  799:         <p>The <tt>break</tt> command, when used without arguments,
  800:         lists the current breakpoints by index.</p>
  801:       </li>
  802:       <li>
  803:         Type clear 0.
  804:         <p>The <tt>clear</tt> command clears breakpoints. In this
  805:         example, we clear by breakpoint number, which we got from
  806:         the <tt>break</tt> command in the previous step.</p>
  807:       </li>
  808:       <li>
  809:         Type cont.
  810:         <p>The <tt>cont</tt> command continues execution. The
  811:         context menu should pop up as it always 
  812:         <!--INDEX ENDRANGE==Venkman development tool --> 
  813:         <!--INDEX ENDRANGE==development:tools:Venkman --> does.</p>
  814:       </li>
  815:     </ol>
  816:     <h2><a name="77034"></a> MozillaTranslator</h2>
  817:     <p><a href="ch11.html#77028">Chapter 11</a> provides 
  818:     <!--INDEX MozillaTranslator development tool --> <!--INDEX 
  819:     development:tools:MozillaTranslator --> information about how
  820:     to make a Mozilla application usable in many different
  821:     languages. Localizing an application can be simple if your
  822:     application is small. For large applications, though,
  823:     localizing can be a long and complicated process. Fortunately,
  824:     interested and enthusiastic developers created a tool that
  825:     makes this process easier.</p>
  826:     <p>MozillaTranslator is a program written in Java that reads in
  827:     a package, provides an interface for changing the strings, and
  828:     when finished, repackages the files for distribution. It is
  829:     sophisticated enough to read JAR archives and output
  830:     cross-platform installers (XPI). This type of solution is ideal
  831:     for nontechnical people who translate the interface
  832:     strings.</p>
  833:     <blockquote>
  834:       <div class="c3">
  835:         NOTE
  836:       </div>
  837:       <p>MozillaTranslator is more than just a program for
  838:       inputting translated strings. The web site (<i><a href=
  839:       "http://www.MozillaTranslator.org/">http://www.MozillaTranslator.org/</a></i>)
  840:       has resources for setting up projects, uploading language
  841:       packs, and finding the latest news on localization issues
  842:       among other features.</p>
  843:     </blockquote>
  844:     <p>To get to the point at which you can input your translated
  845:     strings, you need to take some introductory steps. After
  846:     downloading and installing MozillaTranslator, follow these
  847:     steps:</p>
  848:     <ol>
  849:       <li>Select File &gt; Manage Products.</li>
  850:       <li>Press Add in the dialog to add a package.</li>
  851:       <li>In the window that comes up, give the project a label
  852:       (for your own use) and point to the <i>chrome\en-US.jar</i>
  853:       file within your Mozilla build (replace the path with your
  854:       own Mozilla application locale path).</li>
  855:       <li>Exit the dialog.</li>
  856:       <li>Select File &gt; Update Product.</li>
  857:       <li>Select Edit &gt; Chrome View once the update has
  858:       finished. You should see the component structure shown in
  859:       Figure B-4. You can then choose fields in which to view the
  860:       chrome view window.</li>
  861:     </ol>
  862:     <div class="c4">
  863:       <img src="foo.gif">
  864:     </div>
  865:     <p><i>Figure B-4: <a name="77008"></a></i> <i>Chrome view in
  866:     MozillaTranslator</i></p>
  867:     <p>At this point, you can edit the text straight from the
  868:     chrome view. Another option is to bring up an edit window for a
  869:     selected phrase, which supplies all possible editable fields in
  870:     one window. An advanced search feature exists if you look for a
  871:     piece of text in multiple files. When your strings are all
  872:     done, packaging and preparing your language pack for
  873:     distribution is as straightforward as selecting the Export &gt;
  874:     Jar File/XPI Install from the menus.</p>
  875:     <p><!--INDEX localization:tools --> MozillaTranslator has the
  876:     adaptability to handle any application locale, once you point
  877:     it at the correct resources. Make sure that your files are
  878:     packaged in the correct format-namely, a JAR file.
  879:     MozillaTranslator can handle all localizable resources: DTDs,
  880:     string bundles, HTML, and RDF files.</p>
  881:     <h2><a name="77035"></a> Missing Parts</h2>
  882:     <p>The tools highlighted so far are just some of the pieces
  883:     needed to form a full-featured Mozilla development environment.
  884:     Currently, several different areas of the application creation
  885:     process would benefit greatly from a dedicated development
  886:     tool. Some of the different types of needed tools are listed
  887:     below.</p>
  888:     <h3><a name="77036"></a> Visual XUL Editors</h3>
  889:     <p>XUL is a simple 
  890:     <!--INDEX visual editors (development tools) --> 
  891:     <!--INDEX development:tools:visual editors --> markup language
  892:     that is similar to HTML. Some people prefer to create HTML code
  893:     by hand, but others use programs that generate HTML code for
  894:     them by using a simple point-and-click interface. The creation
  895:     of a user-friendly XUL editing program would greatly simplify
  896:     the creation of Mozilla applications and would allow many more
  897:     people to start their own development projects.</p>
  898:     <p>So far, there have been at least a couple of attempts to
  899:     create such a tool. A few projects, such as Vixen (<i><a href=
  900:     "http://www.mozilla.org/projects/vixen/">http://www.mozilla.org/projects/vixen/</a></i>)
  901:     and XULMaker (<i><a href=
  902:     "http://xulmaker.mozdev.org">http://xulmaker.mozdev.org</a></i>),
  903:     have started to create a visual XUL editor. So far, however,
  904:     there isn't a tool that allows someone to quickly create a user
  905:     interface without creating XUL and CSS code by hand.</p>
  906:     <h3><a name="77037"></a> Toolkits and Libraries</h3>
  907:     <p>Mozilla applications currently have a lot of duplication due
  908:     to a lack of standard libraries and toolkits. Different types
  909:     of applications still need to do very similar things, so having
  910:     common programming routines and interface widgets would greatly
  911:     reduce the amount of time different developers spend recreating
  912:     frequently needed parts of an application.</p>
  913:     <p>In this book, we discussed the JSLib project (<i><a href=
  914:     "http://jslib.mozdev.org">http://jslib.mozdev.org</a></i>),
  915:     which is trying to create a repository of versatile functions
  916:     that any Mozilla application can reuse. For a project like this
  917:     to work, however, it needs to be widely available and accepted
  918:     by the developer community. To ensure its wide availability,
  919:     these common libraries and toolkits need to become a core part
  920:     of the standard Mozilla development tools.</p>
  921:     <h3><a name="77038"></a> Integrating the Pieces</h3>
  922:     <p>Popular development 
  923:     <!--INDEX development:tools:integration --> environments like
  924:     Microsoft's Visual Studio bring together a cohesive set of
  925:     tools; they provide the tool framework in which much of the
  926:     setup, code generation, directory structure, linking, and other
  927:     drudgery is handled automatically.</p>
  928:     <p>When used together, the tools described in this appendix can
  929:     make your application development process easier. However,
  930:     currently, all of these tools are located in different places
  931:     and none of them interact with one another to provide a
  932:     seamless development framework.</p>
  933:     <p>Even when all the tools do become available, it will be
  934:     necessary to integrate each of these together to create a
  935:     single development environment for Mozilla application
  936:     builders. This single tool will allow you to create the shell
  937:     of an application easily and fill it with XUL, CSS,
  938:     Java-Script, and all other parts of a Mozilla application that
  939:     can then be packaged easily when you are done.</p>
  940:     <!-- <hr> -->
  941:     <?php $hide_text_control=1; $post_to_list=NO; $author='reviewers@mozdev.org'; // require(NOTES); ?>

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