View source for Labs/Ubiquity/Ubiquity 0.1.3 Architecture

Back to [[Labs/Ubiquity]].

This is a description of the high-level design of Ubiquity 0.1.3.  Its intended use is as a historical document, as opposed to a constantly-maintained accurate representation of the current Ubiquity architecture.

This document assumes that you have basic working knowledge of Firefox 3 extension development.  For more information on this, see the [https://developer.mozilla.org/en/Building_an_Extension Building an Extension] tutorial on MDC, as well as their section on [https://developer.mozilla.org/en/Using_JavaScript_code_modules JavaScript code modules].  It also assumes that you've used Ubiquity and read through the [[Labs/Ubiquity/Latest_Ubiquity_User_Tutorial|User Tutorial]] and the [[Labs/Ubiquity/Ubiquity_0.1_Author_Tutorial|Author Tutorial]].

[[Image:Ubiquity_0.1.3_Architecture.png]]

== Per-window Objects ==

The objects described in this section are instantiated separately for each window, generally because they encapsulate information about Ubiquity's user interface (and each window has its own Ubiquity UI).  The objects described in this section are created in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/chrome/content/browser.js chrome/content/browser.js].

* '''Command Manager''' is defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/cmdmanager.js ubiquity/modules/cmdmanager.js]; it's essentially a mediator between Ubiquity's UI elements, its natural-language parser, and the commands themselves.

* '''Context Popup Menu UI''' is the user interface for the "Ubiquity" submenu that shows up when the user right-clicks on a selection in Ubiquity.  It's contained in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/chrome/content/popupmenu.js chrome/content/popupmenu.js].

* '''Command Entry UI''' is the user interface for the command entry mode that's displayed when the user presses a hotkey (usually Ctrl+Space or Apple+Space).  It's defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/chrome/content/ubiquity.js chrome/content/ubiquity.js] and contained in the class <tt>Ubiquity</tt>, though it should really be renamed to <tt>CommandEntryUi</tt> or something similar.

* '''Parser''' is the natural language parser that is responsible both for interpreting what the user types in the command entry UI, as well as analyzing the user's current selection and mapping it to potential noun types, and combining these two elements to come up with potential "sentences"&mdash;verbs with direct and indirect objects&mdash;for Ubiquity to execute.  It's defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/parser/parser.js ubiquity/modules/parser/parser.js].

== Application-wide Objects ==

The objects described in this section are shared by the entire XULRunner application; many of them are singletons.  The construction of most of these objects begins in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/setup.js ubiquity/modules/setup.js].

* '''Mixed Code Source Collection''' and '''Code Source''' classes are defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/codesource.js ubiquity/modules/codesource.js].  A better name for <tt>MixedCodeSourceCollection</tt> would probably be <tt>DecoratedCodeSourceCollection</tt>, since the general idea is to take a single piece of code&mdash;what's commonly referred to as a "command feed" in Ubiquity&mdash;and add a header or preamble that contains common utilities, such as the <tt>Utils</tt> and <tt>CmdUtils</tt> namespaces, and a footer that contains finalization and post-processing logic.  The headers, footers, and built-in (non-unsubscribable) command feeds are contained in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/feed-parts/ ubiquity/feed-parts/], while most the standard (and unsubscribable) feeds are in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/standard-feeds/ ubiquity/standard-feeds/].  Iterating over a <tt>MixedCodeSourceCollection</tt> yields Code Sources that are full representations of all code that ultimately gets executed in a command feed's sandbox.

* '''LINK REL Code Service''' is defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/linkrel_codesvc.js ubiquity/modules/linkrel_codesvc.js] and is responsible for detecting <tt><nowiki><LINK REL="commands"></nowiki></tt> tags on web pages, displaying notification box messages to the user, and managing command feed subscriptions.  When iterated over, it yields a Code Source object for each subscribed-to command feed, each of which are subsequently decorated by <tt>MixedCodeSourceCollection</tt>.  A better name for this object might be <tt>CommandFeedSubscriptionService</tt>.

* '''Command Source''' is defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/cmdsource.js ubiquity/modules/cmdsource.js] and is responsible for executing command feed code in sandboxes and retrieving commands, noun types, and page load functions from them.  It's also responsible for re-loading command feeds when they've changed.

* '''Sandbox Factory''' is a simple abstraction for the creation of JavaScript sandboxes and the evaluation of code within them.  It's defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/sandboxfactory.js ubiquity/modules/sandboxfactory.js].  It always uses a <tt>Components.utils.Sandbox</tt> object, but on some platforms and Firefox versions an optional <tt>nsUbiquity</tt> XPCOM binary component is used to evaluate JS code instead of <tt>Components.utils.evalInSandbox()</tt>; this is done to make it easier to debug command feeds and provide access to JavaScript 1.7 and above.  This XPCOM component is contained in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/components/ components/].

* '''Globals Maker''' is a factory that sets up global variables, such as <tt>Application</tt> and <tt>XMLHttpRequest</tt>, in a new sandbox object.  It's defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/setup.js ubiquity/modules/setup.js].

* '''Message Service''' is a simple abstraction that encapsulates the display of messages and the reporting of errors to the end-user; it's defined in [http://hg.toolness.com/ubiquity-firefox/file/9a629fab9402/ubiquity/modules/msgservice.js ubiquity/modules/msgservice.js].