Summary

DreamFace DataWidget API

Author: DreamFace Interactive, Copyright 2007-2008, all rights reserved.
Version: Outsider rev.5

/*	This notice must be untouched at all times.

	DreamFace DataWidget API
	The latest version is available at http://www.dreamface-interactive.com
	Copyright (c) 2007 - 2008 DreamFace Interactive, all rights reserved.
	
	LICENSE: Mozilla Public License Version 1.1, http://www.mozilla.org/MPL/MPL-1.1.html
*/	
/** 
 * @fileoverview DreamFace DataWidget API
 * @author DreamFace Interactive, Copyright 2007-2008, all rights reserved.
 * @version Outsider rev.5
 */

/**
 * Construct a new DataWidget object.
 * @class This is the basic class that represents a DataWidget.
 * This class exposes main functions to manipulate a DataWidget from a custom DataWidget renderer
 * or any API function called by the DreamFace Engine when a DataWidget needs to be displayed or
 * personalized.
 * @constructor
 * @param {Document} dataWidgetDefinition. The DataWidget Definition.
 * @return A new DataWidget instance
 */
function DataWidget( dataWidgetDefinition ) {
	this.name = null;					// Name of the DataWidget Instance
	this.title = null;					// Title of the DataWidget Instance
	this.titleVisibility = null;		// Title Visibility of the DataWidget Instance
	this.widgetClass = null;			// DataWidget Class name
	this.template = null;				// DataWidget Template name
	this.directory = null;				// Name of the directory to which the DataWidget is attached to
	this.parameters = null;				// DataWidget parameters
	this.preferences = null;			// DataWidget preferences
	this.dataSourceName = null;			// DataSource associated to the DataWidget
	this.dataSource = null;				// DataSource Document object
	this.dataSourceParameters = null;	// DataSource parameters used by the DataWidget
	this.data = null;					// Data resulting from the DataSource execution
	this.dataAsText = null;				// Data resulting from the DataSource execution as Text
	this.construct( dataWidgetDefinition );
	return this;
}

DataWidget.prototype.type="DataWidget";

/** 
    * Internal Function. Initialize the DataWidget instance from the Document that represents the DataWidget.
    * @param {Document} dataWidgetDefinition. The DataWidget Definition.
    */
DataWidget.prototype.construct=function( dataWidgetDefinition ) {
	if (dataWidgetDefinition != null) {
		this.name = $(dataWidgetDefinition).find("name").text();
	  	this.widgetClass = $(dataWidgetDefinition).find("class").text();
	  	this.title = $(dataWidgetDefinition).find("title").text();
		this.titleVisibility = $(dataWidgetDefinition).find("titleBarVisible").text();
	}
}

/**
    * Return the name (i.e the identifier) of the DataWidget instance. The name is unique on each screen.
    * @type String
    */
DataWidget.prototype.getName=function() {
	return this.name;
}

/**
 * Set the DataWidget name.
 * @param {String} name. The new name of the DataWidget instance.
 */
DataWidget.prototype.setName=function( name ) {
	this.name = name;
}

/**
    * Return the title of the DataWidget instance.
    * @type String
    */
DataWidget.prototype.getTitle=function() {
	return this.title;
}

/**
 * Set the DataWidget title.
 * @param {String} title. The new title of the DataWidget instance.
 */
DataWidget.prototype.setTitle=function( title ) {
	this.title = title;
}

/**
    * Return a String value ("true" or "false") that defines if the DataWidget's title bar is visible.
    * @type String
    */
DataWidget.prototype.getTitleVisibility=function() {
	return this.titleVisibility;
}

/**
 * Define if the DataWidget title bar is visible.
 * @param {String} titleVisibility. The new visibility status of the DataWidget title bar.
 */
DataWidget.prototype.setTitleVisibility=function( titleVisibility ) {
	this.titleVisibility = titleVisibility;
}

/**
    * Return the DataWidget width
    * @type int
    */
DataWidget.prototype.getWidth=function() {
	var aWidth = $("div[@id=wincontent_"+this.name+"]").width();
	return aWidth;
}

/**
    * Return the DataWidget height
    * @type int
    */
DataWidget.prototype.getHeight=function() {
	var aWidth = $("div[@id=wincontent_"+this.name+"]").height();
	return aWidth;
}

/**
    * Return the name of the DataWidget class associated to the DataWidget instance.
    * @type String
    */
DataWidget.prototype.getWidgetClassName=function() {
	return this.widgetClass;
}

/**
 * Set the DataWidget class name associated to the DataWidget instance.
 * @param {String} widgetClassName. The DataWidget class name.
 */
DataWidget.prototype.setWidgetClassName=function( widgetClassName ) {
	this.widgetClass = widgetClassName;
}

/**
    * Return the DataWidget class associated to the DataWidget instance.
    * @type Document
    */
DataWidget.prototype.getWidgetClass=function() {
	return dfGetClassDef( this.widgetClass );
}

/**
    * Return the name of the DataWidget template used to cratethe DataWidget instance.
    * @type String
    */
DataWidget.prototype.getTemplateName=function() {
	return this.template;
}

/**
    * Return the DataWidget template used to cratethe DataWidget instance.
    * @type Document
    */
DataWidget.prototype.getTemplate=function() {
	return dfGetTemplate( this.template );
}

/**
 * Set the DataWidget template.
 * @param {String} template. The DataWidget template name.
 */
DataWidget.prototype.setTemplate=function( template ) {
	this.template = template;
}

/**
 * Load the DataWidget template.
 * @param {String} template. The DataWidget template name.
 * @type Document
 */
DataWidget.prototype.loadTemplate=function( template ) {
	if (template != null)
		this.template = template;
	var aTemplate = dfGetTemplate( this.template );
	this.directory = $("directory", aTemplate).text();
	return aTemplate;
}

/**
 * Retrieve the DataWidget JavaScript renderer associated to the template.
 * @type Document
 */
DataWidget.prototype.getRenderer=function() {
	return dfGetRenderer( this.template );
}

/**
    * Return the DataSource name associated to the DataWidget instance.
    * @type String
    */
DataWidget.prototype.getDataSourceName=function() {
	return this.dataSourceName;
}

/**
 * Set the DataSource name.
 * @param {String} dataSourceName. The DataSource name.
 */
DataWidget.prototype.setDataSourceName=function( dataSourceName ) {
	this.dataSourceName = dataSourceName;
}

/**
    * Return the DataSource parameters used by the DataWidget when executing the DataSource.
    * @type Document
    */
DataWidget.prototype.getDataSourceParameters=function() {
	return this.dataSourceParameters;
}

/**
 * Set the DataSource parameters used by the DataWidget when executing the DataSource.
 * @param {Document} parameters. The DataSource parameters document object.
 */
DataWidget.prototype.setDataSourceParameters=function( parameters ) {
	this.dataSourceParameters = parameters;
}

/**
 * Set the value of one of the DataSource parameters used by the DataWidget when executing the DataSource.
 * @param {String} paramName. The DataSource parameter name.
 * @param {String} paramValue. The DataSource parameter value.
 */
DataWidget.prototype.setDataSourceParameter=function( paramName, paramValue ) {
	if ($("parameter[@name="+paramName+"]", this.dataSourceParameters).size() > 0) {
		$("parameter[@name="+paramName+"]", this.dataSourceParameters).text( paramValue );
	} else {
		var elemParam = document.createElement("<parameter>");
		elemParam.setAttribute("name",paramName);
		$(this.dataSourceParameters)[0].appendChild( elemParam );
		$("parameter[@name="+paramName+"]", this.dataSourceParameters).text( paramValue );
	}
}

/**
 * Set the DataSource Request.
 * @param {String} request. The DataSource request (the request is added to the DataSource location+port).
 */
DataWidget.prototype.setDataSourceRequest=function( request ) {
	var reg = new RegExp("( )", "g");
	var anEncodedRequest = request.replace( reg, "%20" );
	if (this.dataSource != null) {
		$("request", this.dataSource).text( anEncodedRequest );
	}
}

/**
 * Execute the DataSource associated with the DataWidget.
 */
DataWidget.prototype.executeDataSource=function() {
	var aDataWidgetInstance = this;
	if (aDataWidgetInstance.dataSourceName != null && aDataWidgetInstance.dataSourceName != "") {
		if (aDataWidgetInstance.dataSource == null) {
			$.ajax({
				type: "GET",
				url: "dfe/interface?entity=datasources",
				async: false,
				data: "identifierName=FieldName&identifierValue="+aDataWidgetInstance.dataSourceName,
				success: function(xml) {
					var oDom = XML.parse(xml);
					aDataWidgetInstance.dataSourceText = xml;
					aDataWidgetInstance.dataSource = $("datasource[@name=" + aDataWidgetInstance.dataSourceName + "]:first", oDom);
				}
			});
		}
		aDataWidgetInstance.loadData();
	} else {
		var aRenderer = aDataWidgetInstance.getRenderer();
		$("TemplateFunction:first", aRenderer).each( function(i) {
			var aTemplateFunction = new Function( "pDataWidget", $(this).text() );
			aTemplateFunction( aDataWidgetInstance );
		});
	}
}

/**
 * Retrieve Data according to a DataSource definition.
 * Note: This function calls automatically the DataWidget renderer after data retrieval.
 */
DataWidget.prototype.loadData=function() {
	var aDataWidgetInstance = this;
	var sConnector = $(aDataWidgetInstance.dataSource).find("connector").text() ;
	var sLocation = $(aDataWidgetInstance.dataSource).find("location").text() ;
	var sPort = $(aDataWidgetInstance.dataSource).find("port").text() ;
	var sRequest = $(aDataWidgetInstance.dataSource).find("request").text() ;
	var oParameters = $(aDataWidgetInstance.dataSource).find("parameters") ;
	dfDataSourceParamSubstitution( oParameters, aDataWidgetInstance.dataSourceParameters );
	var sParameters = (oParameters==null) ? "" : XML.serialize(oParameters[0]);
	$.get("dfe/interface/data", {
		connector: sConnector,
		location: sLocation,
		port: sPort,
		request: sRequest,
		parameters: sParameters
		}, function(xml) {
			aDataWidgetInstance.dataAsText = xml;
			var oDom = XML.parse(xml);
			aDataWidgetInstance.data = oDom;
			var aRenderer = aDataWidgetInstance.getRenderer();
			$("TemplateFunction:first", aRenderer).each( function(i) {
				var aTemplateFunction = new Function( "pDataWidget", $(this).text() );
				aTemplateFunction( aDataWidgetInstance );
			});
		}
	);
}

/**
 * Retrieve Data according to a DataSource definition.
 * Note: This function does NOT call automatically the DataWidget renderer after data retrieval but calls a callback function.
 */
DataWidget.prototype.refreshData=function( callbackFunction ) {
	var aDataWidgetInstance = this;
	var sConnector = $(aDataWidgetInstance.dataSource).find("connector").text() ;
	var sLocation = $(aDataWidgetInstance.dataSource).find("location").text() ;
	var sPort = $(aDataWidgetInstance.dataSource).find("port").text() ;
	var sRequest = $(aDataWidgetInstance.dataSource).find("request").text() ;
	var oParameters = $(aDataWidgetInstance.dataSource).find("parameters") ;
	dfDataSourceParamSubstitution( oParameters, aDataWidgetInstance.dataSourceParameters );
	var sParameters = (oParameters==null) ? "" : XML.serialize(oParameters[0]);
	$.get("dfe/interface/data", {
		connector: sConnector,
		location: sLocation,
		port: sPort,
		request: sRequest,
		parameters: sParameters
		}, function(xml) {
			aDataWidgetInstance.dataAsText = xml;
			var oDom = XML.parse(xml);
			aDataWidgetInstance.data = oDom;
			aCallbackFunction = new Function( callbackFunction );
			aCallbackFunction();
		}
	);
}
			
/**
    * Return the Data resulting from the DataSource execution.
    * @type Document
    */
DataWidget.prototype.getData=function() {
	return this.data;
}

/**
 * Set the Data to be displayed by the DataWidget. Usually, the data results from the DataSource execution.
 * @param {Document} data. The document object related to the data.
 */
DataWidget.prototype.setData=function( data ) {
	this.data = data;
}

/**
    * Return the Data resulting from the DataSource execution as Text.
    * @type String
    */
DataWidget.prototype.getDataAsText=function() {
	return this.dataAsText;
}

/**
 * Set the Data  as Text to be displayed by the DataWidget. Usually, the data results from the DataSource execution.
 * @param {String} dataAsText. The text related to the data.
 */
DataWidget.prototype.setDataAsText=function( dataAsText ) {
	this.dataAsText = dataAsText;
}

/**
 * Return the parameters of the DataWidget instance.
 * @type Document
 */
DataWidget.prototype.getParameters=function() {
	if (this.parameters == null) {
		var aClassNode = this.getWidgetClass();
		this.parameters = $("parameters:first", aClassNode);
	}
	return this.parameters;
}

/**
 * Return the parameters of the DataWidget instance as Text.
 * @type String
 */
DataWidget.prototype.getParametersAsText=function() {
	if (this.parameters == null) {
		var aClassNode = this.getWidgetClass();
		this.parameters = $("parameters:first", aClassNode);
	}
	return XML.serialize(this.parameters);
}

/**
 * Return the parameter value of the DataWidget instance.
 * @param {String} paramName. The parameter name.
 * @type String
 */
DataWidget.prototype.getParameter=function(paramName) {
	if (this.parameters == null) {
		var aClassNode = this.getWidgetClass();
		this.parameters = $("parameters:first", aClassNode);
	}
	var aParamValue = $(this.parameters).find("parameter[@name="+paramName+"]").text();
	return aParamValue;
}

/**
 * Return the preferences of the DataWidget instance.
 * @type Document
 */
DataWidget.prototype.getPreferences=function() {
	if (this.preferences == null) {
		this.preferences = dfGetViewPreference( this.name );
	}
	return this.preferences
}

/**
 * Return the preferences of the DataWidget instance as Text.
 * @type String
 */
DataWidget.prototype.getPreferencesAsText=function() {
	var aReturnValue = "";
	if (this.preferences == null) {
		this.preferences = dfGetViewPreference( this.name );
		if (this.preferences != null) {
			aReturnValue = XML.serialize( this.preferences );		
		}
	}
	return aReturnValue;
}

/**
 * Set a DataWidget preference.
 * @param {String} name. The property name.
 * @param {String} value. The property value.
 */
DataWidget.prototype.setPreference=function(name, value) {
	if (this.preferences == null) {
		$(name, this.preferences).text( "<![CDATA["+value+"]]>" );
	}
}

/**
 * Save preferences of the DataWidget.
 * @param {String} callback. A Callback function.
 */
DataWidget.prototype.savePreferences=function(callback) {
	if (this.preferences == null) {
		var sXML = XML.serialize( this.preferences );
		$.post( "dfe/interface/add/preference", {
			FieldUserID: ( dfCurrentDesignPage != "undefined" && dfProducerID == "undefined" ) ? "*" : dfUserID,
			FieldType: "view",
			FieldName: dfGetCurrentPage()+"/"+this.name,
			FieldValue: sXML
		}, function(xml){
			if (callback != null) {
				var aCallbackFunction = new Function( callbackFunction+"()" );
				aCallbackFunction();
			}
  		});
	}
}


/**
 * Clear the DataWidget preferences and reload the DataWidget content (implies a reload of preferences).
 */
DataWidget.prototype.reload=function() {
	this.preferences = null;
	this.clearContent();
	dfLoadViewContent( this );
}

/**
 * Clear the DataWidget and recall the renderer.
 */
DataWidget.prototype.redraw=function() {
	var aDataWidgetInstance = this;
	aDataWidgetInstance.clearContent();
	var aRenderer = aDataWidgetInstance.getRenderer();
	$("TemplateFunction:first", aRenderer).each( function(i) {
		var aTemplateFunction = new Function( "pDataWidget", $(this).text() );
		aTemplateFunction( aDataWidgetInstance );
	});
}

/**
 * Add an xHTML fragment (DIV, IFRAME, TABLE, ...) to the DataWidget's content.
 * @param {String} fragment. The XHTML fragment to be added.
 */
DataWidget.prototype.addContent=function( fragment ) {
	$( "div[@id=wincontent_"+this.name+"]" ).append( fragment );
}

/**
 * Clear the DataWidget's content.
 */
DataWidget.prototype.clearContent=function() {
	$("div[@id=wincontent_"+this.name+"]").empty();
}


/**
 * Attach a directory to the DataWidget
 * @param {String} directory. The directory name.
 */
DataWidget.prototype.setDirectory=function( directory ) {
	this.directory = directory;
}

/**
 * Return the directory attached to the DataWidget
 * @type String
 */
DataWidget.prototype.getDirectory=function() {
	return this.directory;
}

/**
 * Attach a directory component (Flex or XForms) to the DataWidget
 * @param {String} component. The component's reference.
 */
DataWidget.prototype.setDirectoryComponent=function( component ) {
	$("div[@itemID="+this.getName()+"]").attr( "directorycomponent", component );
}

/**
 * Return the directory component (Flex or XForms) attached to the DataWidget
 * @type String
 */
DataWidget.prototype.getDirectoryComponent=function() {
	return $("div[@itemID="+this.getName()+"]").attr( "directorycomponent" );
}

/**
 * Return the directory component (Flex or XForms) binding source
 * @type String
 */
DataWidget.prototype.getDirectoryComponentBinding=function() {
	var returnValue = "";
	var aDirectoryComponent = this.getDirectoryComponent();
	if (aDirectoryComponent != null && aDirectoryComponent != "") {
		$.ajax({
			type: "GET",
			url: dfRootDomain+"/df/dfe/interface/directory",
			async: false,
			data: "name="+this.getDirectory()+"&component="+aDirectoryComponent,
			success: function(xml) {
				var componentDom = XML.parse( xml );
				returnValue = $("source", componentDom).attr("binding");
			}
		});
	}
	return returnValue;
}

/*
	InteractionEvent
*/
/**
 * Construct a new InteractionEvent object.
 * @class This is the basic class that represents a interaction event.
 * This class exposes main functions used to initialize and retrieve information when an interaction occurs and a command is executed.
 * @constructor
  * @param {Document} interactionName. The interaction event definition.
 * @return A new InteractionEvent instance
 */
function InteractionEvent( interactionName ) {
	this.name = null;
	this.action = null;
	this.source = null;
	this.target = null;
	this.construct( interactionName );
	return this;
}

InteractionEvent.prototype.type="InteractionEvent";

/**
 * Internal Function. Initialize the interaction event.
   * @param {Document} interactionName. The interaction event definition.
 */
InteractionEvent.prototype.construct=function( interactionName ) {
	this.name = interactionName;
}

/**
    * Return the name of the interaction.
    * @type String
    */
InteractionEvent.prototype.getName=function() {
	return this.name;
}

/**
 * Set the object from which the interaction has been triggered.
 * @param {Object} source. The object that represents the source of the interaction.
 */
InteractionEvent.prototype.setSource=function( source ) {
	this.source = source;
}

/**
    * Returnsthe object that triggered the interaction. In many cases, this function returns a {DataWidget}  instance.
    * @type Object
    */
InteractionEvent.prototype.getSource=function() {
	return this.source;
}

/**
 * Set the object for which the interaction called the action.
 * @param {Object} target. The object that represents the target of the interaction.
 */
InteractionEvent.prototype.setTarget=function( target ) {
	this.target = target;
}

/**
    * Return the object for which the interaction action has been called. In many cases, this function returns a {DataWidget}  instance.
    * @type Object
    */
InteractionEvent.prototype.getTarget=function() {
	return this.target;
}

/**
 * Set the action that has been called.
 * @param {String} action. The name of the action.
 */
InteractionEvent.prototype.setAction=function( action ) {
	this.action = action;
}

/**
    * Return the name of the action that has been called by the interaction.
    * @type String
    */
InteractionEvent.prototype.getAction=function() {
	return this.action;
}