# XULMaker
Users Manual

## Summary

XULMaker is a XUL application used to design and construct XUL based applications and web pages.

A XUL based application consists of `content`, `skin` and `locale` data. `content` consists of `xul` and `overlay` files for presentation layout and javascript files for presentation behaviour. `skin` consists of `.css` and image files organized into "themes". `locale` contains the static text that makes up the application, organized into "locales" or languages. XULMaker is a visual and interactive editor of `xul` files. (It is intended to evolve XULMaker over time into a full blown IDE - covering all development aspects of a XUL application.)

XULMaker visually and interactively creates and edits a XUL document by interacting with both an XML DOM (document object model) and an XML text representation of the XUL document. (In version 0.40 XML text is read-only.) The XUL document is a typical XML document consisting of various elements with various attributes and attribute values. The user builds a XUL document in XULMaker by visually and interactively adding/deleting/moving XUL elements, adding/deleting element attributes, and setting attribute values. A XULMaker user is able to see the results of his work as he builds the XUL document - as it would appear in a Mozilla browser (or any browser that supports the display of `xul` files.)

The XULMaker application includes a user manual and the book "Creating Applications with Mozilla" as a help document. Access to the DOM Inspector is available from the `Tools` menu. Operating in "developer mode" (selected by pressing `ctrl-D`) gives access to a number of ways of exploring the XULMaker application itself including extensive project documentation presented as a help document.

## Features

XULMaker version 0.40 has the following features:

(See the project's roadmap to see where we intend to take this project.)

- XUL based applications/web page development
- XUL elements supported include :
  - box, hbox, vbox
  - label
  - textbox
  - button
  - toolbox
  - menubar, menu, menupopup, menuitem
  - toolbar, toolbarbutton
  - tabbox, tabs, tab, tabpanels, tabpanel
  - grid, rows, row
  - (any "write-in" element)
- Add or remove XUL elements
- Add or remove XUL element attributes
- View XUL document as:

- web page (design view)
- text document (code view)
- hierarchical tree of XUL elements(Element Explorer - tree view)
- flat list of XUL Elements (Element Explorer - list view)

- Select the active element from:
  - the design view
  - the Element Explorer - tree view
  - the Element Explorer - list view
- Save XUL document (serialized text) as a local file using a directory/file dialog
- Open (load) XUL document (serialized text) as a local file using a directory/file dialog
- New XUL document to clear current document and create a new empty document
- Window debug mode - elaborate display of box layout
- On-line users manual - presented as a help document
  (i.e. includes a table of content, index, glossary and search)
- On-line project documentation - presented as a help document
- On-line version of the book "Creating Applications with Mozilla" - presented as a help document

## Introduction

The XULMaker project is essentially a research project. It is used to explore the functionality of Mozilla XUL as used by the Gecko Rendering Engine - a component of the Mozilla browser.

### Mozilla XUL History

Netscape gave its browser software to the open source community in 1996. This then became the start of the Mozilla project. Mozilla is an open source project for the continued development of the Internet browser.

The Mozilla project proceeded with a major rewrite of the rendering engine which was code named Gecko.

Netscape continued to distribute new releases of its browser as repackaged versions of the browser from Mozilla. The first release of Netscape based on the Gecko rendering engine was Netscape 6.0 - it being a repackaged version of Mozilla 0.?? (The Gecko rendering engine used in Netscape v6.0/Mozilla v0.?? uses an older version of the XUL file format which we label here as XUL v0.6, whereas Netscape v6.1 uses the published version 1.0 of the XUL file format.) The first major release of Mozilla is Mozilla 1.0 which occurred in January 2002. Netscape 7.0 is based on Mozilla 1.0.1. These are the versions that XULMaker version 0.40 has been developed for and tested on.

### XULMaker History

The XULMaker project was started by Michael Hearn in March 2001. Michael was a bright young sixteen year old student from the UK when he published the first version of XULMaker on mozdev.org. XULMaker version 0.10 was developed for Mozilla version 0.80 that used the earlier version of the XUL file format - it does not work with Mozilla v1.0/Netscape v7.0. It was a great first effort. Michael abandoned the project for some time until it was adopted by Franklin de Graaf in November 2002. Franklin is a software engineer/programmer living in Toronto, Canada. The next version, version 0.40, was published before Christmas in 2002. Version 0.40 works with Mozilla v1.0/Netscape v7.0.

## Overview of the User Interface

XULMaker is based on the MVC (Model-View-Controller) pattern which is reflected in the user interface. The controller consists of a toolbox, containing a menubar and two toolbars, and a statusbar. The view consists of the Element Explorer, Attribute Inspector, the document view and a support view.

### Visual Layout

The visual layout of the application has the following structure:

    IDE
     |
     +-Toolbox
     |   +-Menubar
     |   +-PaletteToolbar
     |   +-ElementToolbar
     +-View
     |   +-ElementExplorer
     |   |   +-ElementTree
     |   |   +-ElementList
     |   +-AttributeInspector
     |   +-DocumentFrame
     |   |   +-DesignDocument
     |   |   +-TextDocument
     |   |   +-BrowserDocument
     |   +-SupportFrame
     |       +-ConsoleOutput
     |       +-SourceView
     |       +-ProjectDocumentation
     |       +-Resources
     +-Statusbar

The application window (IDE) consists of a toolbox, containing the menubar and two toolbars, a statusbar and the application view in between. The application view consists of four major views - the Element Explorer, the Attribute Inspector, the Document View and the Support View.

The ElementExplorer and the AttributeInspector may be used to create and view elements and their attributes.

The document under construction is displayed in the document view as either a design document, text document or a browser document - these are three different views of the same document model. The design document is a browser view decorated in a way that assists construction. The text document is an editable text view of the document model. The browser view is a view of the document as it would appear in a Mozilla browser.

The support view is used to provide various support information. This includes trace and logging information when running in development mode (activated by pressing `ctrl-D`), reference documents form XULPlanet, etc.

The following is a screenshot of the application showing the various components of the user interface.

## Building a XUL Document

### Opening and Saving Files

### Adding and Removing XUL Elements

An element may be added to the "active" element (as it's container) by:

- In the Palette Toolbar, clicking on one of the XUL Element toolbar buttons
- In the Element Toolbar, selecting the XUL Element in the drop-down list and clicking on the `Add Element` button

The "active" element may be deleted by:

- pressing the `Delete` key
- clicking on the `Edit | Delete element` menuitem

The following is a simple tutorial exercise.

1. Using the Palette Toolbar add some elements

   - check the tree view, list view and design view to see that the element was added or deleted

   - check that the selected element, (not the added element) was identified as the active element

   - check that the attributes in the Attribute Inspector reflect the selected (active) element.

   1. click on "hbox" in toolbar
   2. select "hbox0" in treelist ("hbox0" becomes active)
   3. click on "label" in toolbar
   4. click on "textbox" in toolbar
   5. click on "label" in toolbar
   6. select "label1" in treelist ("label1" becomes active)
   7. press delete key ("hbox0" becomes active)
   8. select each element in the treelist and check the corresponding attributes in the Attributes Inspector
2. Using the Element Toolbar add and delete some more elements

   - check the tree view, list view and design view to see that the element was added or deleted

   - check that the selected element, (not the added element) was identified as the active element

   - check that the attributes in the Attribute Inspector reflect the selected (active) element.

   1. select "window" in treelist
   2. select "hbox" in toolbar element list
   3. check "select as active" in toolbar
   4. click on "add element" button in toolbar (hbox1 becomes active)
   5. select "label" in toolbar
   6. click on "add element" button in toolbar (label2 becomes active)
   7. select "value" in toolbar attribute list
   8. type "name" in toolbar attribute value list
   9. click on "add attribute" button in toolbar
   10. select each element in the treelist and check the corresponding attributes in the Attributes Inspector

### Adding and Removing XUL Element Attributes

## Displaying a XUL Document

### Window Debug Mode

The `View | Window debug mode` menuitem is a checked item that turns the window debug mode on or off. This feature is deeply imbedded in the XUL technology and is not implemented by XULMaker. Unfortunately, changing this mode does not take immediate effect - it only affects the start of a new or newly opened document.

## Running XULMaker in Development Mode

### Enabling/Disabling Development Mode

You may enable the development mode by pressing `ctrl-D`. Enabling development mode results in additions to the menubar. The menubar gets a `Debug` and `Trace` menu added, and a `Project Documentation` menuitem gets added to the `Help` menu.

You may disable the development mode by pressing `shift-ctrl-D`. Disabling development mode results in deletions to the menubar. The `Debug` and `Trace` menu in the menubar gets deleted (hidden), and the `Project Documentation` menuitem gets deleted from the `Help` menu.

### Debug Menu

The `Debug` menu offers the following capability:

- disable development mode.
- update views from the design document
- serialize idlist - displays a serialized (text) view of the Element Explorer flat list
- serialize idtree - displays a serialized (text) view of the Element Explorer tree
- serialize ddoc - displays a serialized (text) view of the Design Document
- XUL Schema
  - Element Types - lists the elements defined in the XUL Schema
  - Element Attributes - lists the element attributes defined in the XUL Schema

### Tracing Execution

The `Trace` menu displays a list of the various functions in xulmaker. These are "checked" menuitems. When a function is "checked" it is traced when executed. Some functions are disabled (greyed out) because they are only executed during initialization and can only be "checked" by changing the JavaScript code. (Set the `TRACE_INITIALIZING` constant in the `xmSettings.js` file to `true`. The `trace.js` file identifies the functions that are executed and traced during intialization.)

Copyright © 2002 by X-Power Computing Group Inc.