File:  [mozdev] / books / www / docbook / appb.xml
Revision 1.4: download - view: text, annotated - select for diffs - revision graph
Wed Apr 16 11:54:27 2003 UTC (16 years, 7 months ago) by halter
Branches: MAIN
CVS tags: HEAD
replaced all occurences of:
        <graphic align="center" fileref="figs/U2192.gif"/>
with:
        &gt;

should fix: http://mozdev.org/bugs/show_bug.cgi?id=3557

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

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