mozdev.org

xulapp

resources:

Extension Mechanism


XulApp extensions will use standard Mozilla overlays to implement menu, toolbar and content area additions.

Extensions Config File

Loading of extensions into the shell will be controlled by extension configuration files. These contain simple lists of chrome url's of the extensions to be loaded. The url's will typically reference an  <extension name>Overlay.xul  file.
A command line parameter will determine  the particular configuration file. This allows the creation of task specific versions of the shell for different phases in development. A utility to build configuration files will be developed. It will ensure that declared dependencies between  extensions are resolved into a correct load order.

Well Known Shell Id's

The xulapp.xul file defines a number of well known id's which can be used as overlay targets. Currently these include:

    <scriptset id="scriptset">        
    <broadcasterset id="broadcasterset"/>
    <commandset id="commandset"/>
    <keyset id="keyset"/>
    <menubar id="menubar">
    <toolbox id="toolbox"/>
    <deck id="content" flex="1"/>

Additional id's will be added as necessary.

Extension Loading

XalApp uses the new document.loadOverlay function to process the configuration file. Each overlay is loaded in turn, and can assume that the xul elements installed by previous overlays are available as overlay targets.
As each overlay is loaded, any global code is executed. Special needs aside, this is strongly discouraged as inter-extension code dependencies may not  have been resolved at this time.

However, an optional registration and callback mechanism is defined:
If the <extension name>Overlay.xul file references a script file <extension name>Overlay.js then this script may call the register function specifying a callback function. This function name must be universally unique. Once all overlays are loaded, the callbacks are invoked in overlay order.

For example:
projectOverlay.xul

<overlay id="Project"    xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <overlaytarget id="scriptset">
        <script type="application/x-javascript" src="projectOverlay.js"/>
    </overlaytarget>
    ...
</overlay>

projectOverlay.js

// Register overlay load callback.
registerOverlay(onload_projectOverlay);

function onload_projectOverlay(xulapp) {
    //Console.log("project loaded");
}

Tool Extensions

Tool Extensions will load using this same mechanism. However, they should provide an<extension name>Overlay.xul file which  contains just sufficient code to activate the extension. Every configured tool extension overlay will be loaded at startup,  so they should be designed to install shell UI and code hooks - and not much else.


Context Menu's

When a context menu is displayed for a file (or directory) in the Project Explorer only the relevant items for that file type should be displayed.

The xulapp-explorer extension will install a  <fileassociations  id="fileAssociations"/> element. Other tools may use this element as an overlaytarget.
 Hence we are using the overlay system to produce a mini-database in the xul. The xulapp-explorer extension will use this database to dynamically build the context menu for a particular file.

An added item should take the form:

<fileassociation
    id="?"  ext="?space separated file extension list"
    
dir="?true or false"
    default="?true or false"

    oncommand="?extensionOverlay.loadFile('fileURI')"/>

The ext attribute should contain a space separated list of the extensions that the tool supports.
An "*" indicates all types are supported.

The dir attribute indicates that the tool is available for directories.

The default attribute indicates that this is the default tool for the indicated extensions. The default tool can be invoked by double clicking the file. It would be unwise to indicate default="true" for ext="*".
If multiple tools claim to be the default for a given extension, only one will be selected.

The oncommand attribute indicates the function to execute when a context menu item is selected. The function should be coded as shown. The fileURI parameter will be replaced with the actual fileURI string when the function is called. The declared function should accept this parameter. The function should noormally be just a hook to launch the tool or to join with an existing instance.



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