mozillamsu/xul-manager — pull request #3 by Schwig (2013-10-22 06:36:18+00:00)
Title: Initial rewrite of XUL Manager with detailed explanation and TODO. Expected to undergo more changes in the future. Includes simple widget example

The simple widget counts the number of button clicks.

The UI now stays consistent across multiple browser windows, while ensuring events are wired.

TODO:
- Iron out the external behavior of the "XUL Manager"
- Provide a method to change a widget's icon
- Provide additonal functionality within DOMHelper and DOMElement
- Figure out how we're going to add support for stylesheets
- Writing new module to apply styles to XUL/HTML files through setting the style attribute on elements:
- Maybe define in a JSON object (easier)
var style = {
'@fooElementID': 'background: url(...); ',
'@fooClassName': 'background-color: #0066cc;'
};
- Maybe create our own simple css-ish files (less rewriting of existing code, more new code and work)
#fooElementID {
...
...
}
.fooClassName {
...
...
}

- See if we can get stylesheets/utils working from the SDK
- Figure out how to reference relative image URL's
- I learned how to register chrome URL's, but in order for this to work we need to figure out how to unpack a jar and save it's contents into a directory
- Maybe we can just specify image URL's with the style-sheets if we define styles with JSON objects

- I'm sure there's more to do that I'm not thinking of write now
- I'm not sure if we should be considering performance at all. Maybe create an XPCOM module so WindowManager is a singleton object?

I'm not sure if these changes would change how widgets use the XUL manager. In the upcoming week or so I plan on having a final-ish version of the XUL manager completed. Any alterations after the next completed version should not make any major (if any) changes as to how widgets interact with the XUL manager. Any alterations should only add additional functional or change how things are working internally.

While writing this final-ish version I'm going to be doing some more experimentation on how to make the library clean and easy to use. Once I think I've established something good I will be asking for everyone's input. It shouldn't be too much different from how it currently is (assuming everyone's happy):

main.js
- CONFIG is defined here
- Initializes Widget object with CONFIG
- Calls CustomizableUI.createWidget(Widget.UXWidget)
- Responsible for wiring sdk/system/unload to the Widget
- Responsible for destroying widget (CustomizableUI.destroyWidget(...))

- CustomizableUI is referenced in main and not Widget because I thought it would be a good idea to not have any unecessary chrome privileges within widget
- It might be a bad idea to have chrome privileges by default in main.js though, I'm not sure.
- We might be able to get around this by creating a WidgetManager module or something

Widget: This is what developers will be coding. This is where you actually write the add-on

- Needs to return:
- UXWidget (to provide to main.js -> CustomizableUI)
- addonUnload (to provide to main.js -> sdk/system/unload)

- Creates a WindowManager object, supplies CONFIG to constructor

WindowManager: Responsible for making sure new windows are populated and have their events wired correctly
- I'm not sure how much of this responsibility should be left to the DOMHelper
- Currently the DOMHelper maintains a panelview object to copy into newly created windows, and a list of events to wire up into new windows
- DOMElements are passed a function to call when they have made any alterations to the UI.

DOMHelper: WindowManager has a function to return a "XUL Document" that provides much of the functionality you would expect from a regular HTML document, like:
- getElementById
- TODO: getElementsByClassName
- Not sure if this should just return an array of DOMElements (simple), or some sort of new DOMElementCollection?
- etc, tbd.

DOMElement: Returned to the Widget when they call functions such as document.getElementById(...) or document.getElementsByClassName(...)
- Provide common functions that you would use on HTML elements:
- addEventListener
- setAttribute
- etc, tbd.