Summary

Allows Mozile code in a web page to take advantage of Mozile's Firefox extension.

Version: 0.8 $Id: overview-summary-enhance.js.html,v 1.1 2008/02/20 18:47:09 jameso Exp $

Author: James A. Overton

/* ***** BEGIN LICENSE BLOCK *****
 * Licensed under Version: MPL 1.1/GPL 2.0/LGPL 2.1
 * Full Terms at http://mozile.mozdev.org/0.8/LICENSE
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * The Original Code is James A. Overton's code (james@overton.ca).
 *
 * The Initial Developer of the Original Code is James A. Overton.
 * Portions created by the Initial Developer are Copyright (C) 2005-2006
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *	James A. Overton <james@overton.ca>
 *
 * ***** END LICENSE BLOCK ***** */

/**
 * @fileoverview Allows Mozile code in a web page to take advantage of Mozile's Firefox extension.
 * @link http://mozile.mozdev.org 
 * @author James A. Overton <james@overton.ca>
 * @version 0.8
 * $Id: overview-summary-enhance.js.html,v 1.1 2008/02/20 18:47:09 jameso Exp $
 */

mozile.provide("mozile.enhance");

/**
 * Mozilla enhancement tools.
 * @type Object
 */
mozile.enhance = new Object();
// JSDoc hack
mozile.enhance.prototype = new mozile.Module;


/** 
 * Listen for changes to the @mozileServerRequest and @mozileServerResponse attributes of the documentElement. If they change, execute the appropriate code.
 * @param {Event} event The event to listen to.
 * @type Void
 */
mozile.enhance.listen = function(event) {
	// Only respond to particular attribute changes.
	if(!event || !event.target || 
		event.target != document.documentElement) return;
	var attr = event.attrName.toLowerCase();
	if(attr != "mozileserverrequest" && 
		attr != "mozileserverresponse") return;
	if(!event.newValue) return;
	var value = event.newValue;

	// Listen for a server request and execute it.
	if(attr == "mozileserverrequest") {
		try {
			eval(value);
		} catch(e) {
			mozile.debug.debug("mozile.enhance.listen", 
				"Failed to execute serverRequest: "+ e);
		}
		document.documentElement.setAttribute("mozileServerRequest", "");
	}
	
	// If there's code in _serverResponse, listen for the attribute and execute the code.
	if(attr == "mozileserverresponse" && 
		mozile.enhance._serverResponse) {
		if(value) {
			try {
				eval(mozile.enhance._serverResponse);
			} catch(e) {
				mozile.debug.debug("mozile.enhance.listen", 
					"Failed to execute serverResponse: "+ e);
			}
			mozile.enhance._serverResponse = null;
			document.documentElement.setAttribute("mozileServerResponse", "");
		}
	}
}

/** 
 * Send a request to the Mozile extension. Will only work properly if the page has been "enhanced".
 * @param {String} requestCode The name of the "enhancement" (code fragment) to execute. Only enhancements listed in the documentElement's @mozileEnhancements attribute will be made available.
 * @param {String} evalOnChange Optional. Code to evaluate after the server has replied.
 * @type Void
 */
mozile.enhance.clientRequest = function(requestCode, evalOnChange) {
	document.documentElement.setAttribute("mozileServerResponse", "");
	document.documentElement.setAttribute("mozileClientRequest", requestCode);
	mozile.enhance._serverResponse = evalOnChange;
}

/** 
 * Check to see if Mozile has been enhanced by the Mozile Extension. Look at the  @mozileStatus and @mozileEnhancements attributes.
 * @param String enhancementName Optional. If given, the method will check to see if the Mozile Extension provides an enhancement with a matching name. Otherwise it checks to see if the page has been enhanced (in general).
 * @type Boolean
 */
mozile.enhance.isEnhanced = function(enhancementName) {
	var status = document.documentElement.getAttribute("mozileStatus");
	if(status != "enhanced") return false;
	if(!enhancementName) return true;
	
	var enhancements = document.documentElement.getAttribute("mozileEnhancements");
	if(!enhancements) return false;
	var re = new RegExp("\\b"+enhancementName+"\\b");
	return re.test(enhancements);
}


// Final configuration.

// Add a listener for changes to attributes.
document.addEventListener("DOMAttrModified", mozile.enhance.listen, false);