[fusion-commits] r2081 - sandbox/adsk/2.2gp/lib
svn_fusion at osgeo.org
svn_fusion at osgeo.org
Fri Feb 19 13:31:17 EST 2010
Author: madair
Date: 2010-02-19 13:31:17 -0500 (Fri, 19 Feb 2010)
New Revision: 2081
Modified:
sandbox/adsk/2.2gp/lib/fusion.js
Log:
documentation update
Modified: sandbox/adsk/2.2gp/lib/fusion.js
===================================================================
--- sandbox/adsk/2.2gp/lib/fusion.js 2010-02-19 18:28:39 UTC (rev 2080)
+++ sandbox/adsk/2.2gp/lib/fusion.js 2010-02-19 18:31:17 UTC (rev 2081)
@@ -98,7 +98,7 @@
Lib: {},
/***************************************************************************
- * Class: Fusion.Maps
+ * Class: Fusion.Layers
*
* A set of classes that implement layer functionality for various server
* technologies.
@@ -112,21 +112,40 @@
***************************************************************************/
Constant: {},
+ /**
+ * Pointer to the Application Definition, parsed into all the Fusion
+ * objects: MapGroups, WidgetSets
+ */
applicationDefinition: null,
/**
- * URL to the configuration file to use for this application. The
- * configuration file must be located on the same domain as the
- * application template.
+ * URL of a proxy script if the map server is on a different domain/port
+ * that the application template to get around the same-origin policy
*/
- sConfigFileURL : "",
-
- sWebAgentURL : "",
- sWebTierURL : "",
- sRedirectScript : "",
- bForceRedirect : false,
- sScriptLang : "",
- locale : 'en',
+ sRedirectScript: "",
+
+ /**
+ * A flag to force XHR calls through the proxy, defaults to false
+ */
+ bForceRedirect: false,
+
+ /**
+ * the script programming language for server-side programming.
+ * Typically set to 'php' but other server languages may be used.
+ */
+ sScriptLang: "php",
+
+ /**
+ * the locale setting for the browser and for localization of Fusion.
+ * This is the same as the locale setting in OpenLayers and is used as
+ * the file name for localization files in the /text subdirectory
+ */
+ locale: 'en',
+
+ /**
+ * the hash of strings used for localization of Fusion. Strings are
+ * indexed by a key which is used in calls to OpenLayers.i18n()
+ */
Strings: {}, //locale specific strings
/** URL to the directory from which fusion.js was loaded */
@@ -134,18 +153,25 @@
/**
* configuration object that holds the server configuration as
- * loaded from fusion/config.xml
+ * loaded from fusion/config.json
*/
configuration: null,
- /* broker instance for communicating with the mapagent */
+ /**
+ * broker instance for communicating with the mapagent, typically only
+ * used with MapGuide
+ */
oBroker: null,
/** An array of scripts that are queued to be loaded */
- aScripts : [],
+ aScripts: [],
/** An array of scripts that are currently being loaded */
aLoadingScripts: [],
- /** The current state during initialization of the application */
+
+ /**
+ * The current state during initialization of the application. Valid
+ * states are enumerated below
+ */
loadState: null,
/** API loading has not begun */
@@ -157,7 +183,11 @@
/** Loading is complete */
LOAD_COMPLETE: 3,
- /** unit related stuff */
+ /**
+ * unit related stuff - the following values are the keys into the
+ * unit related arrays below: aUnitPerMeter, aMeterPerUnit, aUnitNames
+ * and aUnitAbbr
+ */
UNKNOWN: 0,
INCHES: 1,
FEET: 2,
@@ -172,6 +202,9 @@
DECIMALDEGREES: 11,
DMS: 12,
PIXELS: 13,
+ /**
+ * conversion factors to go from the specified units to meters
+ */
aUnitPerMeter: [1.0, /* 0 - UNKNOWN */
39.37, /* 1 - INCHES */
3.2808, /* 2 - FEET */
@@ -187,6 +220,9 @@
0.000009044, /* 12 - DMS */
1.0 /* 13 - PIXELS */
],
+ /**
+ * conversion factors to go from meters to the specified units
+ */
aMeterPerUnit: [1.0, /* 0 - UNKNOWN */
0.0254, /* 1 - INCHES */
0.3048, /* 2 - FEET */
@@ -201,9 +237,17 @@
111061.75033, /* 11 - DECIMALDEGREES */
111061.75033, /* 12 - DMS */
1.0 /* 13 - PIXELS */],
+
+ /**
+ * the units names spelled out fully
+ */
aUnitNames: ['Unknown','Inches', 'Feet', 'Yards', 'Miles', 'Nautical Miles',
'Millimeters', 'Centimeters', 'Meters', 'Kilometers',
'Degrees', 'Decimal Degrees', 'Degrees Minutes Seconds', 'Pixels'],
+
+ /**
+ * unit names abbreviations
+ */
aUnitAbbr: ['unk', 'in', 'ft', 'yd', 'mi', 'nm',
'mm', 'cm', 'm', 'km',
'°', '°', '°', 'px'],
@@ -211,24 +255,28 @@
/**
* Function: initialize
*
- * Initialize the Fusion application.
+ * Initialize the Fusion application. This method must be called from
+ * the template's onload method once all script files have been loaded.
+ * Applications can register for the event Fusion.Event.FUSION_INITIALIZED
+ * to carry out further application initialization when all the Fusion
+ * objects have been created and are available.
*
* @param {Object} options
*
* Optional paramters that can be passed to initialize are:
*
- * {String} applicationDefinition - a URL or resource ID
+ * {String} applicationDefinitionURL - a URL or resource ID
* for an ApplicationDefinition file
* {String} sessionId - a session id to start the application
* with. Normally, applications are started without
* a session id and create one. However, sometimes
* it is desirable to use an existing session.
*/
- initialize : function(options) {
+ initialize: function(options) {
options = options || {};
var sessionIdParam = this.getQueryParam('Session');
- // Override the pre-created sessionId by user specified sessionId(if exist)
- this.sessionId = sessionIdParam || options.sessionId || this.sessionId;
+ // Override the pre-created sessionId by user specified sessionId(if exist)
+ this.sessionId = sessionIdParam || options.sessionId || this.sessionId;
if (options.applicationDefinitionURL) {
this.applicationDefinitionURL = options.applicationDefinitionURL;
@@ -249,15 +297,12 @@
}
this.initializeLocale();
- this.sWebagentURL = "";
- this.sScriptLang = "";
-
/*
- * if the application has been loaded from the same host as
- * fusion is installed in, then technically we don't need to
- * use the redirect script because we conform to the
- * Same Origin Policy for XmlHttpRequest to work.
- */
+ * if the application has been loaded from the same host as
+ * fusion is installed in, then technically we don't need to
+ * use the redirect script because we conform to the
+ * Same Origin Policy for XmlHttpRequest to work.
+ */
var test = window.location.protocol+'//'+window.location.host;
var configUrl = 'config.json';
//if (this.fusionURL.indexOf(test,0) == 0) {
@@ -268,9 +313,6 @@
configUrl += '&method=get';
}
- /*script language*/
- this.sScriptLang = 'php';
-
if (Fusion.configuration) {
//config.json loaded via single file build
this.serverSet();
@@ -284,6 +326,19 @@
}
},
+ /**
+ * Function: initializeLocale
+ *
+ * Initialize the Strings hash with the requested locale. This method
+ * simply extends the OpenLayers strings hash with strings specific
+ * to Fusion. Add strings to the files in fusion/text/[locale].json.
+ * This method can be called before Fusion.initialize() if localized
+ * strings are required in the template initialization.
+ *
+ * @param {String} locale - the locale value e.g. 'en-CA' or simply 'en'
+ * for English
+ *
+ */
initializeLocale: function(locale) {
OpenLayers.Lang.setCode(locale ? locale : window._FusionLocale);
this.locale = OpenLayers.Lang.code;
@@ -333,6 +388,7 @@
break;
}
},
+
/**
* Function: loadQueuedScripts
*
@@ -379,7 +435,7 @@
*
* The url of the script.
*/
- queueScript : function(url) {
+ queueScript: function(url) {
if(!document.getElementById(url) && !this.aScripts[url]) {
var script = document.createElement('script');
script.defer = false;
@@ -393,6 +449,7 @@
this.aScripts.push(script);
}
},
+
/**
* Function: scriptFailed
*
@@ -438,11 +495,12 @@
}
}
},
+
/**
* Function: checkLoadingScripts
*
- * check if scripts have loaded. In IE, scripts don't seem to fire the onload
- * event. Safari also seems to have some problems.
+ * check if scripts have loaded. In IE, scripts don't seem to fire the
+ * onload event. Safari also seems to have some problems.
*/
checkLoadingScripts: function() {
var agt=navigator.userAgent.toLowerCase();
@@ -461,13 +519,15 @@
}
}
},
+
/**
* Function: loadConfig
*
- * asynchronously load the application definition through the broker and config
- * manager.
+ * asynchronously load the application definition. For MapGuide, also
+ * set up the broker object. Once the AppDef is loaded/created advance
+ * the laod state.
*/
- loadConfig : function() {
+ loadConfig: function() {
var mapAgentUrl = this.getConfigurationItem('mapguide', 'mapAgentUrl');
if (mapAgentUrl) {
this.oBroker = new Fusion.Lib.MGBroker();
@@ -495,7 +555,7 @@
* Parameter {Object} r
* an XMLHttpRequest object
*/
- getConfigCB : function(r) {
+ getConfigCB: function(r) {
if (r.responseText) {
eval("this.configuration="+r.responseText);
this.serverSet();
@@ -514,11 +574,11 @@
* Parameter {Object} r
* an XMLHttpRequest object
*/
- serverSet : function() {
+ serverSet: function() {
var s = this.configuration.mapguide.webTierUrl;
/* if it is set, use it ... otherwise assume fusion is installed in
- * the default location and compute the web tier url from that
- */
+ * the default location and compute the web tier url from that
+ */
if (s) {
var nLength = s.length;
var slastChar = s.charAt((nLength-1));
@@ -570,8 +630,8 @@
*
* Parameter: {Object} options
*
- * optional parameters to send with the request, passed directly to
- * Prototype's Ajax.Request function
+ * optional parameters to send with the request, passed directly to the
+ * OpenLayers Ajax.Request function
*/
ajaxRequest: function(scriptURL, options) {
//console.log('options.parameters='+options.parameters);
@@ -613,22 +673,18 @@
},
/**
- * Function: convertXML
+ * Function: getXmlAsJson
*
- * Optionally convert XML to JSON using a server-side script
+ * Convert XML to JSON using a server-side script
* for requests that aren't available in JSON.
*
- * Parameter: {XmlHttpRequest} r
+ * Parameter: {String} url - the URL of the XML object to be converted;
+ * this can be any URL and is not prepended with the Fusion URL
*
- * the XmlHttpRequest object
+ * Parameter: {Function} callback - a callback function to be called if
+ * the request is successful
*
- * Parameter: json
- *
* boolean indicator if the content is JSON or not.
- *
- * Parameter: callback
- *
- * callback method to be executed on success and will be passed a parsed json object
*/
getXmlAsJson: function(url, callback) {
var options = {
@@ -639,6 +695,25 @@
var temp = new OpenLayers.Ajax.Request(url, options);
},
+ /**
+ * Function: xml2json
+ *
+ * Callback method to convert the XNR response into an actual json object
+ * and triggers the call to the callback method
+ *
+ * Parameter: callback
+ *
+ * callback method to be executed on success and will be passed a parsed json object
+ *
+ * Parameter: {XmlHttpRequest} r
+ *
+ * the XmlHttpRequest object
+ *
+ * Parameter: json
+ *
+ * boolean indicator if the content is JSON or not (set by OpenLayers)
+ *
+ */
xml2json: function(callback, r, json) {
if (json) {
var o;
@@ -676,7 +751,7 @@
*
* Returns: {Object} a map object or null if not found.
*/
- getMapByName : function(name) {
+ getMapByName: function(name) {
var map = null;
if (this.applicationDefinition) {
map = this.applicationDefinition.getMapByName(name);
@@ -687,7 +762,7 @@
/**
* Function: getMapById
*
- * return a map widget that is associated with the given dom element
+ * return a map widget that is associated with the given DOM element
* by id.
*
* Parameter: {String} id
@@ -696,7 +771,7 @@
*
* Returns: {Object} a map object or null if not found.
*/
- getMapById : function(id) {
+ getMapById: function(id) {
var map = null;
if (this.applicationDefinition) {
map = this.applicationDefinition.getMapById(id);
@@ -707,7 +782,8 @@
/**
* Function: getMapByIndice
*
- * return the map widget at the given index
+ * return the map widget at the given index if there are more than one
+ * map elements specified in the AppDef
*
* Parameter: {String} indice
*
@@ -715,7 +791,7 @@
*
* Returns: {Object} a map object or null if not found.
*/
- getMapByIndice : function(indice) {
+ getMapByIndice: function(indice) {
var map = null;
if (this.applicationDefinition) {
map = this.applicationDefinition.getMapByIndice(indice);
@@ -770,6 +846,13 @@
return widgets;
},
+ /**
+ * Function getSearchDefinitions
+ *
+ * returns the SearchDefinition objects as defined in the AppDef.
+ *
+ * Returns: {Array} an array of searchDefinitions, which may be empty
+ */
getSearchDefinitions: function() {
if (this.applicationDefinition) {
return this.applicationDefinition.searchDefinitions;
@@ -778,6 +861,13 @@
}
},
+ /**
+ * Function getSearchCategories
+ *
+ * returns the SearchCategory objects as defined in the AppDef.
+ *
+ * Returns: {Array} an array of searchCategories, which may be empty
+ */
getSearchCategories: function() {
if (this.applicationDefinition) {
return this.applicationDefinition.searchCategories;
@@ -786,12 +876,21 @@
}
},
+ /**
+ * Function getApplicationDefinitionURL
+ *
+ * returns the URL of the Application Definition
+ *
+ * Returns: {String} a URL
+ */
getApplicationDefinitionURL: function() { return this.applicationDefinitionURL; },
- /**
+ /**
* Function: getApplicationURL
*
* returns the applicaiton's absolute URL minus the filename.html part
+ *
+ * Returns: {String} a URL
*/
getApplicationURL: function() {
var path = window.location.pathname;
@@ -802,8 +901,26 @@
return window.location.protocol + "//" + window.location.host + path;
},
+ /**
+ * Function: getFusionURL
+ *
+ * returns the application's absolute URL minus the filename.html part
+ *
+ * Returns: {String} a URL
+ */
getFusionURL: function() {return this.fusionURL;},
+ /**
+ * Function: getConfigurationItem
+ *
+ * returns individual elements out of the Fusion config.json file
+ *
+ * Parameter: {String} arch - the server architecture (mapguide or mapserver)
+ *
+ * Parameter: {String} key - the config item to be returned
+ *
+ * Returns: {String} a the value for the key of null if not found
+ */
getConfigurationItem: function(arch, key) {
if (this.configuration[arch] && (this.configuration[arch][key]!='undefined')) {
return this.configuration[arch][key];
@@ -811,16 +928,73 @@
return null;
},
+ /**
+ * Function: getScriptLanguage
+ *
+ * Accessor to return the server-side script language
+ *
+ * Returns: {String} the script language e.g. 'php'
+ */
getScriptLanguage: function() { return this.configuration.general.scriptLanguage; },
+ /**
+ * Function: getRedirectScript
+ *
+ * Accessor to return the URL of the redirect script
+ *
+ * Returns: {String} a URL
+ */
getRedirectScript: function() { return this.sRedirectScript; },
+ /**
+ * Function: getBroker
+ *
+ * Accessor to return the broker object (for MapGuide only). The broker
+ * is used to prepare various queries to the MapGuide server.
+ *
+ * Returns: {Object} the broker object
+ */
getBroker: function() { return this.oBroker; },
+ /**
+ * Function: require
+ *
+ * Marks a JavaScript file as required which puts it into the queue for
+ * loading during Fusion initialization. Widget code is included
+ * through this mecahnism
+ *
+ * Parameter: {String} url - the URL of the JS file to be loaded
+ *
+ * Returns: none
+ */
require: function(url) { this.queueScript(url); },
+ /**
+ * Function: reportError
+ *
+ * Triggers the Fusion.Event.FUSION_ERROR and passes along the error
+ * object to the callback functions registered for this event. Widgets
+ * call Fusion.reportError(o) to inform the system of errors.
+ * Applications will typically register an event listener for the error
+ * event and do something to report the error to the user.
+ * By default, errors are not reported since there is no listener
+ *
+ * Parameter: {Object} o - the error object which is typically a string
+ *
+ * Returns: none
+ */
reportError: function(o) { this.triggerEvent(Fusion.Event.FUSION_ERROR, o); },
+ /**
+ * Function: unitFromName
+ *
+ * returns index into the units array for the given unit name or
+ * abbreviation
+ *
+ * Parameter: {String} unit - the units name to look up
+ *
+ * Returns: {Integer} index into the units array
+ */
unitFromName: function(unit) {
switch(unit.toLowerCase()) {
case 'unknown':
@@ -879,6 +1053,16 @@
}
},
+ /**
+ * Function: unitFromName
+ *
+ * Given a unit, this method returns if the units system is one of:
+ * imperial, metric, degrees or device units
+ *
+ * Parameter: {Integer} unit - the units array index
+ *
+ * Returns: {String} the units system
+ */
unitSystem: function(unit) {
switch(unit) {
@@ -904,12 +1088,31 @@
}
},
+ /**
+ * Function: unitName
+ *
+ * Given a unit, this method returns the units name
+ *
+ * Parameter: {Integer} unit - the units array index
+ *
+ * Returns: {String} the units name
+ */
unitName: function(unit) {
if (unit >= Fusion.UNKNOWN && unit <= Fusion.PIXELS) {
return (Fusion.aUnitNames[unit]);
}
return 'Unknown';
},
+
+ /**
+ * Function: unitAbbr
+ *
+ * Given a unit, this method returns the units abbreviation
+ *
+ * Parameter: {Integer} unit - the units array index
+ *
+ * Returns: {String} the units abbreviation
+ */
unitAbbr: function(unit) {
if (unit >= Fusion.UNKNOWN && unit <= Fusion.PIXELS) {
return (Fusion.aUnitAbbr[unit]);
@@ -917,6 +1120,17 @@
return 'Unk';
},
+ /**
+ * Function: toMeter
+ *
+ * Converts a length value from native units into meters. This is the
+ * identity transform if the input units are meters
+ *
+ * Parameter: {Integer} unit - the units array index
+ * Parameter: {Float} value - the value to be converted
+ *
+ * Returns: {Float} the value in meters
+ */
toMeter: function(unit, value) {
if (unit == Fusion.UNKNOWN) {
return value;
@@ -926,6 +1140,18 @@
}
return false;
},
+
+ /**
+ * Function: fromMeter
+ *
+ * Converts a length value from meters into native units. This is the
+ * identity transform if the native units are meters
+ *
+ * Parameter: {Integer} unit - the units array index
+ * Parameter: {Float} value - the value to be converted
+ *
+ * Returns: {Float} the value in native units
+ */
fromMeter: function(unit, value) {
if (unit == Fusion.UNKNOWN) {
return value;
@@ -935,6 +1161,18 @@
}
return false;
},
+
+ /**
+ * Function: convert
+ *
+ * Converts a length value from one unit system into another.
+ *
+ * Parameter: {Integer} unitsIn - the units array index of the input
+ * Parameter: {Integer} unitsOut - the units array index of the output
+ * Parameter: {Float} value - the value to be converted
+ *
+ * Returns: {Float} the value in output units
+ */
convert: function(unitsIn, unitsOut, value) {
if (unitsIn >= Fusion.UNKNOWN && unitsIn < Fusion.PIXELS &&
unitsOut >= Fusion.UNKNOWN && unitsOut < Fusion.PIXELS) {
@@ -944,11 +1182,15 @@
},
/**
- * initializes the meters per unit values when a new map is loaded. Some systems make different
- * assumptions for the conversion of degrees to meters so this makes sure both Fusion and
- * OpenLayers are using the same value.
+ * Function: initUnits
*
- * @param metersPerUnit the value returned by LoadMap.php for meters per unit
+ * initializes the meters per unit values when a new map is loaded.
+ * Some systems make different assumptions for the conversion of degrees
+ * to meters so this makes sure both Fusion and OpenLayers are using
+ * the same value.
+ *
+ * Parameter: {Float} metersPerUnit - the value returned by LoadMap.php
+ * for meters per unit
*/
initUnits: function(metersPerUnit) {
var eps = 1000;
@@ -967,11 +1209,13 @@
}
},
- /**
- * find the OpenLayers units identifier given the Fusion metersPerUnit value
- *
- * @param metersPerUnit the value returned by LoadMap.php for meters per unit
- */
+ /**
+ * Function: getClosestUnits
+ *
+ * find the OpenLayers units identifier given the Fusion metersPerUnit value
+ *
+ * @param metersPerUnit the value returned by LoadMap.php for meters per unit
+ */
getClosestUnits: function(metersPerUnit) {
var units = "degrees";
var minDiff = 100000000;
@@ -986,6 +1230,16 @@
return units;
},
+ /**
+ * Function: addWidgetStyleSheet
+ *
+ * Dynamically load a CSS stylesheet. The url will be prepended with
+ * the Fusion URL.
+ *
+ * Parameter: {String} url - the URL of the CSS file to be loaded
+ *
+ * Returns: none
+ */
addWidgetStyleSheet: function(url) {
var lnk = document.createElement('link');
var hd = document.getElementsByTagName('HEAD')[0];
@@ -995,6 +1249,15 @@
lnk.href = Fusion.getFusionURL()+url;
},
+ /**
+ * Function: parseQueryString
+ *
+ * An initialization time function to parse the application URL parameters
+ * and stores them in an array. They can be retrieved using
+ * Fusion.getQueryParam(key).
+ *
+ * Returns: {Array} an array of the query params from when the page was loaded
+ */
parseQueryString: function() {
this.queryParams = [];
var s=window.location.search;
@@ -1009,6 +1272,15 @@
return this.queryParams;
},
+ /**
+ * Function: getQueryParam
+ *
+ * Returns the query parameter value for a given parameter name
+ *
+ * Parameter: {String} p - the parameter to lookup
+ *
+ * Returns: parameter value or the empty string '' if not found
+ */
getQueryParam: function(p) {
if (!this.queryParams) {
this.parseQueryString();
@@ -1029,7 +1301,7 @@
/**
* Function: _getScriptLocation
- * Return the path to this script.
+ * Return the path to this script for bootstrapping Fusion.
*
* Returns:
* {String} Path to this script
More information about the fusion-commits
mailing list