Home | Mailing List | Installation | Source Code | Themes | Screenshots | Bugs | Documentation | FAQ

Chameleon Dev Map (a method to the madness)

Pavol Vaskovic aka Mondo

  1. Introduction
  2. Basic Design
  3. UI
  4. File and Directory Structure
  5. Javascript Classes
  6. Edit Area


The purpose of this document is a feeble attempt to explain some of  the "design" and functionality of Chameleon.  I am doing this for two reasons. I would like to maybe get other developers involved or interested in the project (you can't really help out on something without some minimal documentation).  I am also doing this for myself while things are still somewhat fresh in my head. A week from now i will be totally lost in my own code because i would have forgotten just about everything by then.

Basic Design
Chamelon started out very simply. It was just a sketch on a piece of  paper, which was revised a few times and then i stared coding. I knew the app needed a menubar, toolbar, edit area, preview area, palate/toolarea and a status bar. All of the basics found in many client apps these days.  So the UI frame was created first based on boxes drawn on a piece of paper. I have later come to learn that this method is know as "top down  design". What ever it's called, you have to frame the house before you put up the sheet rock.

This is the parent xul file. All of the application overlays are referenced from this file.
This is the file used when the app is launched.


menubar -> menus.xul 
toolbar -> toolbar.xul
editbar -> browser.xul
tool palate  -> palate.xul
statusbar -> statusbar.xul

These overlays are named and grouped based on the UI. The css style sheets are grouped the same way.
menus.css, toolbar.css, palate.css etc . . .

keyset.xul and broadcasterset.xul are overlays that contain the keyset and broadcaster elements.
So they to can be found in one logical place.

There is a browser (iframe) element that has browser.xul   as it's initial source file.
This is so other component bars can be loaded in later by just changing the location of the frame.
For example mail-news.xul, aim.xul etc . . . 
These files are also parent files containing their own overlays.
This part of the UI content is where the toolbar editable templates are displayed. 
When you click on an element in a template it will then be displayed in the preview box.

File and Directory Structure
I tried to lay out the files and directory structure for Chameleon as logical as i could.
First you have the cvs source directories and then the actual application file structure.
The cvs source is really only a few extra folders up.

It looks like this:
   www    <- This is the web site.
   scripts    <- This is where build and other usefull shell script are kept for Chameleon.
   theme_builder    <- This is where install.js and the top level dir for xpinstall.
       theme_builder    <- This is the application root.  This folder is installed into the mozilla chrome dir.

So starting from the 2nd theme_builder dir we begin the root files bundled w/ Chameleon.

Chameleon Directory Structure

this is the main xul and js directory. There is also other content such as xml, html and txt files.
this is where the xul files are stored for the dialogs used in the app.
this is where html and txt files used in the "info" menu are stored.
this is where the main xul overlays are stored. These overlays are first children.
this is where overlays used by first child overlays are stored. These are 2nd child include/overlay files.
this is where all of the main application javascript files are located. Separate template js files are not stored here.
this is where the main template files used for preview go. Right now there is only the browser template file.
this is where the edit templates overlays live. The directories in this one are no longer used.
this is where the main xul files for the main edit object bars live. Right now it is just the browser.
this is where the js classes are for the toolbars states normal, hover, active and disabled. This is a major workaround which will be changed.
this is where xbl files for bound ui widgets live such as the colorpicker.
this is where the localization dtd files are stored for various language translations.
this is where the english strings used in the xul files are abstracted out into entities.
this is where all of the css, images and templates files are stored for the tool.
this is where the css and images for the default gray theme of the app live.
this is where the images to Chameleon's toolbars are.
this is where the css files for Chameleon's UI live.
this is where the bg grid images and toolbar images for Chameleon live. It is supposed to be toolkit type of images that other skins can use.
this is where the source css files used in preview mode are kept.
this is where the css preview files for the navigator component are stored.
this directory i don't think is used any more.
this is where the generated navigator.css file is stored for preview.
this is not used anymore.
this is where the toolbar template css files are stored.
this is where the browser module css files are kept.
template specific images.
browser template css files.
old stuff need to get rid of.
need to remove old stuff.
this is old. I think i can get rid of this also.
widgit toolkit stuff
grippy and color picker style images are in here.
widgit css style sheets

Javascript Classes
The main js file for Chameleon is palate.js .
This file is pretty much the meat and potatoes of the app. It is broken down into a number of javascript classes or objects. Most of these objects are also based on the UI as well.

palate.js classes

JS Class
Preview -> PreviewControl
General -> General
Size Tab -> Size
Font Tab -> Font
Color Tab -> Color
Padding Tab -> Padding
Margin Tab -> Margin
Border -> Border
IO -> IO

So very simply the idea is this.
The preview area has a js class w/ methods and member vars related to preview specific tasks.
General covers generilized tasks, arrays etc . . .
The various css tool control tabs have grouped classes relating to specific functionality from that part of the tool.
IO class handles all of the io for the app.

PreviewControl Class
This js class handles all of the functionality related to the Preview section of the tool. This section in the UI is broken down in subsections.
  1. Object Preview
  2. Object Layers
  3. Background Image
  4. Foreground Image
  5. State
  6. Reset
  7. Clear
  8. Attributes

So all of these UI pieces have specific relational functionality associated with them.  There is functionality specific to this area of the tool as well as other areas. All of the classes depend on each other to makeup the whole of the tool.

General Class
This class takes care of generized functionality that is shared by all of the other classes. Again there are member vars, arrays and functions in this class.

Size Class

This class handles all of the functionality for the size tab in the palate section of the tool. This is where the css size style rules are stored.The actual rules (width:, max-width:, etc) are stored in a member array and the settings (1px, 2px, etc) are dynamically drawn from a hidden attribute pool in the drop down menus.

Font Class

This class handles all of the functionality for the font tab.

This class handles all of the functionality for the color tab.

Padding Class

This class handles all of the functionality for the padding tab.

Margin Class

This class handles all of the functionality for the margin tab.

Border Class

This class handles all of the functionality for the border tab.

IO Class

This class handles all I/O for the app. Things like "Save theme", "Preview", "Load" etc . . . 
This class relies heavily on io.js lib.

Top Level Functions
There are a number of top level or global functions here.

A lot of these classes are big and need to be broken down some more into sub classes. This is on my todo list.
Perhaps these classes should be in their own files as well.

Global Consts
contains most of the reuseable string consts used by palate.js.
I use the js const type like a #define.
Both of these js files are included in the overlay file palate.xul which is an overlay for theme_builder.xul .

Edit Area

The edit area is the part of the app where the editable templates are displayed. This idea is this. You prep a xul file stripping out all of the event handlers and attributes accept for class and id. If the element is anonymous content (xbl) then you need to bring that content into the templateas well. Thisis really all a work around and needs a better implementation.This was also not part of the scope for the first generation of the application. It would be nice to parse a xul file get the content tree and the associated  attributes that Chameleon needs and generate a new editable xul template file.The only problem i can see doing this is dealing w/ anonymous content. This needs looking into in the future. I think this can be a seperate module of the tool and part of an import or transpose feature.

After you have preped a template file, you need to place an event handler  on the container of this file that points to the main edit API method for  the app. It is called parseElement( . This method takes the dom element object from the template xul file and  creates a duplicate of that element (using the dom call createElement) in  the preview area for editing. There are associated hidden attributes and attribute flags used as well. The template files for the browser component are toolbar.xul, menubar.xul , personalbar.xul, etc . . .  and they live in the templates/browser dir. toolbar.xul is the actual file that displays the navigator toolbar in the edit area of the tool. These files have specific css files as well. You guesed it, these files are called toolbar.css, menubar.css, personalbar.css, etc . . . you get the idea. They live in the skin/templates/browser/style.

So when you use the tool, you are applying css style rules to the newly created element that is in the preview window by using the palate widgits to the right. Then you apply these changes back to the original element in the edit area. This is done with a simple dom call to setAttribute. 

This is a very basic overview here. The rules are all stored depending  on what state you are editing in (normal, hover, etc) as js arrays hidden  in  attributes of the element being edited. The default style rules of these templates are also stored in js arrrays in classes named to reflect  the state you are in. Ex: normal.js has a Normal class, hover.js has aHover  class. These classes are created and initialized when you startup the app. These "default"  style objects hang out and are calledon when youshift through modes.
So for when example you choose hover as a mode to edit, the defaultstyle  in the the toolbar will come from the Hover object which isin   hover.js. The style attributesfor all of the editable elements in  the template toolbar will beset with the predefined style rules stored in  the js array. This would be the modern theme in this case.

So now since any of the edits you have made are all stored in js arrays  we can do whatever we want with this data like save it to a css file. Which  is the whole purpose of the tool. Generating css files.

Browser Component Classes

This file is the main js file for all of the browser component templates. The dir is named poorly and i will change it. It should be toolbars/browser/js or something along those lines. Anyway, here is where all of the specific functionality for the editable templates live. Most of the functions aretop level. I probably should create a general class, because these functionsare generic and will be resused. That is providing all of the other template xul files are based on this stucture.
This i am waiting until i implement an entirely new component just to be sure.

Toolbar Class

This class has an array of id's used in the toolbar xul template. These id's are cycled through in loops in many functions. If you want to reset the toolbar back to it's defalut style for example, you need to loop through the elements that have style attributes set and unset them. Or if you want to hightlight the borders of each element in the toolbar, same thing.

Menubar Class

This class is the same as the Toolbar class it holds an array of id's for the menubar template xul file.

Personalbar Class

This class is the same as the Toolbar class it holds an array of id's for the personalbr template xul file.

Statusbar Class

This class is the same as the Toolbar class it holds an array of id's for the statusbar template xul file.

Taskbar Class

This class is the same as the Toolbar class it holds an array of id's for the taskbar template xul file.


The chameleon project can be contacted through the mailing list or the member list.
Copyright © 2000-2020. All rights reserved. Terms of Use & Privacy Policy.