      1 /**
      2  * @ignore
      3  */
      4 var Ozone = Ozone ? Ozone : {};
      5
      6 /**
      7  * @namespace
      8  * @since OWF 5.0
      9  */
     10 OWF = window.OWF ? window.OWF : {};
     11
     12 (function(window, document, undefined) {
     13
     14 	var WIDGET_READY_SERVICE_NAME = '_widgetReady',
     15
     16         isReady = false,
     17 		readyList = [],
     18 		widget = Ozone.util.parseWindowNameData(),
     19 		eventingController,
     20 		dragAndDropController,
     21 		launchingController,
     22 		chromeController;
     23
     24 	owfdojo.mixin(OWF, /** @lends OWF */ {
     25
     26 		/**
     27 		 * The OWF.Eventing object manages the eventing for an individual widget
     28 		 *
     29 		 * @namespace
     30 		 * @name OWF.Eventing
     31 		 */
     32 		Eventing: {},
     33
     34 		/**
     35 		 * @namespace
     36 		 * @name OWF.RPC
     37 		 */
     38 		RPC: {},
     39
     40 		/**
     41 		 * This object is used to create, retrieve, update and delete user preferences.
     42 		 *
     43 		 * @namespace
     44 		 * @name OWF.Preferences
     45 		 */
     46 		Preferences: {},
     47
     48 		/**
     49 		 * This object is used launch other widgets.
     50 		 *
     51 		 * @namespace
     52 		 * @name OWF.Launcher
     53 		 */
     54 		Launcher: {},
     55
     56 		/**
     57 		 * The OWF.DragAndDrop object manages the drag and drop for an individual widget.
     58 		 *
     59 		 * @namespace
     60 		 * @name OWF.DragAndDrop
     61 		 */
     62 		DragAndDrop: {},
     63
     64 		/**
     65 		 * This object allows a widget to modify the button contained in the widget header (the chrome).
     66 		 *
     67 		 * @namespace
     68 		 * @name OWF.Chrome
     69 		 */
     70 		Chrome: {},
     71
     72 		/**
     73 		 * Provides OWF utility methods for the widget developer
     74 		 *
     75 		 * @namespace
     76 		 * @name OWF.Util
     77 		 */
     78 		Util: Ozone.util,
     79
     80 		/**
     81 		 *
     82 		 *
     83 		 * @namespace
     84 		 * @name OWF.Metrics
     85 		 */
     86 		Metrics: Ozone.metrics,
     87
     88 		/**
     89 		 * Provides functions to log messages and objects
     90 		 *
     91 		 * @namespace
     92 		 * @name OWF.Log
     93 		 */
     94 		Log: Ozone.log,
     95
     96 		/**
     97 		 * Provides utility methods for localization
     98 		 *
     99 		 * @namespace
    100 		 * @name OWF.Lang
    101 		 */
    102 		Lang: Ozone.lang,
    103
    104 		Version: Ozone.version,
    105
    106 		/**
    107 			Accepts a function that is executed when Ozone APIs are ready for use
    108 			@param {Function} handler Function to execute when OWF APIs are ready
    109 			@param {Object} scope The scope (this reference) in which the function is executed. If omitted, defaults to the browser window.
    110 		*/
    111 		ready: function(handler, scope) {
    112
    113 			if(handler === undefined) {
    114 				throw 'Error: no arguments passed';
    115 				return;
    116 			}
    117
    118 			if(typeof handler !== 'function') {
    119 				throw 'Error: handler must be a function';
    120 				return;
    121 			}
    122
    123 			isReady === true ? handler.call(scope) : readyList.push( {fn: handler, scope: scope} );
    124
    125 		},
    126
    127       /**
    128        * This function should be called once the widget is ready and all initialization is completed.  This will send a
    129        * message to the container which in turn may notify other widgets
    130        */
    131         notifyWidgetReady: function() {
    132           //send a message to container that this widget is ready
    133           gadgets.rpc.call('..', WIDGET_READY_SERVICE_NAME, null, OWF.getInstanceId());
    134         },
    135
    136 		/**
    137 			Returns definition GUID of the widget. This is auto generated by OWF when the widget was brought in an OWF instance.
    138 		*/
    139 		getWidgetGuid : function() {
    140 			return widget.guid;
    141 		},
    142
    143 		/**
    144 			Returns instance GUID of the widget.
    145 		*/
    146 		getInstanceId : function() {
    147 			return widget.id;
    148 		},
    149
    150         /**
    151          * @description Returns the Widget Id
    152          * @returns {String} The widgetId is a complex JSON encoded string which identifies a widget for Eventing.
    153          *   Embedded in this string is the widget's uniqueId as the 'id' attribute.  There is other data is in the string
    154          *   which is needed for Eventing and other APIs to function properly. This complex widgetId string may be used in
    155          *   the <a href="./OWF.Eventing.html#.publish">OWF.Eventing.publish</a> function to designate a specific recipient for a message.
    156          *   Additionally, once subscribed to a channel via <a href="./OWF.Eventing.html#.subscribe">OWF.Eventing.subscribe</a> during the
    157          *   receipt of a message, the sender's widgetId is made available as the first argument to the handler function.
    158          * @example
    159          * //decode and retrieve the widget's unique id
    160          * var complexIdString = OWF.getIframeId();
    161          * var complexIdObj = owfdojo.toJson(complexIdString);
    162          *
    163          * //complexIdObj will look like
    164          * // {
    165          * //  //widget's uniqueId
    166          * //  id:"49cd21f0-3110-8121-d905-18ffa81b442e"
    167          * // }
    168          *
    169          * //get Widget's uniqueId
    170          * alert('widget id = ' + complexIdObj.id);
    171          */
    172 		getIframeId : function() {
    173 			return '{\"id\":\"' + widget.id + '\"}';
    174 		},
    175
    176 		/**
    177 			Returns type of dashboard in which the widget is opened. [portal, desktop, accordion, tabbed]
    178 		*/
    179 		getDashboardLayout : function() {
    180 			return widget.layout;
    181 		},
    182
    183 		/**
    184 			Returns version of the widget.
    185 		*/
    186 		getVersion : function() {
    187 			return widget.version;
    188 		},
    189
    190 		/**
    191 			Returns URL of the widget.
    192 		*/
    193 		getUrl : function() {
    194 			return widget.url;
    195 		},
    196
    197 		/**
    198 			Returns an object containing information on the current OWF theme
    199 			@returns {Object} Returns an object below: <br>
    200 			{ <br>
    201 				//name of the theme <br>
    202 				themeName: 'theme-name', <br>
    203 				<br>
    204 				//describes color contrast of the theme.  This may be one of 3 values: <br>
    205 				// 'standard' (colors provide no special contrast) <br>
    206 				// 'black-on-white' (black on white color contrast) <br>
    207 				// 'white-on-black' (white on black color contrast) <br>
    208 				themeContrast: 'black-on-white', <br>
    209 				<br>
    210 				//this field is a number of the fontSize in pixels <br>
    211 				themeFontSize: 12 <br>
    212 			}
    213 			@example
    214 			var themeObj = OWF.getCurrentTheme();
    215 		*/
    216 		getCurrentTheme : function() {
    217 			return widget.currentTheme;
    218 		},
    219
    220 		/**
    221 			Returns the name of the Container the Widget is in
    222 		*/
    223 		getContainerName: function() {
    224 			return widget.containerName;
    225 		},
    226
    227 		/**
    228 			Returns the version of the Container the Widget is in
    229 		*/
    230 		getContainerVersion: function() {
    231 			return widget.containerVersion;
    232 		},
    233
    234 		/**
    235 			Returns whether or not the dashboard in which the widget is opened is locked.
    236 		*/
    237 		isDashboardLocked : function() {
    238 			return widget.locked;
    239 		},
    240
    241 		/**
    242 		Returns the URL of the Container the Widget is in
    243 		*/
    244 		getContainerUrl: function() {
    245             //figure out from preference location
    246 			var pref = widget.preferenceLocation;
    247             return pref.substring(0, pref.length - 6);
    248 		},
    249
    250 		/**
    251 			Gets all opened widgets on the current dashboard.
    252
    253 			@param {Function} callback function to execute when opened widgets are retrieved from OWF. Function is passed an array of objects with the structure below: <br>
    254 			{<br>
    255 				id: 'instance guid of widget',<br>
    256 				frameId: 'iframe id of widget',<br>
    257 				widgetGuid: 'widget guid of the widget',<br>
    258 				url: 'url of the widget',<br>
    259 				name: 'name of the widget'<br>
    260                 universalName: 'universal name of the widget'<br>
    261 			}<br>
    262 			@example
    263 			OWF.getOpenedWidgets(function(openedWidgets) {
    264
    265 			});
    266 		*/
    267 		getOpenedWidgets: function(fn) {
    268
    269 			if(fn === undefined) {
    270 				throw 'Error: no arguments passed';
    271 				return;
    272 			}
    273
    274 			if(typeof fn !== 'function') {
    275 				throw 'Error: fn must be a function';
    276 				return;
    277 			}
    278
    279 			Ozone.eventing.getAllWidgets(fn);
    280 		}
    281 	});
    282
    283 	// for backwards compatibility
    284 	Ozone.Widget = OWF;
    285
    286 	OWF._init = function(window, document, undefined) {
    287
    288         if (OWF.relayFile != null) {
    289           Ozone.eventing.Widget.widgetRelayURL = OWF.relayFile;
    290         }
    291
    292 		// Eventing API
    293 		function initEventing() {
    294 			for(var i = 0, methods = ['publish', 'subscribe', 'unsubscribe'] ; i < methods.length ; i++) {
    295 				OWF.Eventing[ methods[i] ] = this[ methods[i] ];
    296 			}
    297 		}
    298
    299 		// RPC/Directed Eventing API
    300 		function initRPC() {
    301 			OWF.RPC.registerFunctions = Ozone.eventing.registerFunctions;
    302 			OWF.RPC.getWidgetProxy = Ozone.eventing.importWidget;
    303 			OWF.RPC.handleDirectMessage = function(fn) {
    304 				if(typeof fn !== 'function') {
    305 					throw 'Error: fn must be a function';
    306 					return;
    307 				}
    308 				Ozone.eventing.handleDirectMessage = fn;
    309 			};
    310 		}
    311
    312 		// Preferences API
    313 		function initPreferences() {
    314 			for(var i in Ozone.pref.PrefServer) {
    315 				if(typeof Ozone.pref.PrefServer[ i ] === 'function')
    316 					OWF.Preferences[ i ] = Ozone.pref.PrefServer[ i ];
    317 			}
    318 		}
    319
    320 		// Launching API
    321 		function initLauncher() {
    322 			OWF.Launcher.launch = launchingController.launchWidget;
    323 			OWF.Launcher.getLaunchData = Ozone.launcher.WidgetLauncherUtils.getLaunchConfigData;
    324 		}
    325
    326 		// Drag and Drop API
    327 		function initDragAndDrop() {
    328 			OWF.DragAndDrop = {
    329 				onDragStart: function(callback, scope) {
    330 					dragAndDropController.addCallback('dragStart', owfdojo.hitch(scope, callback));
    331 					return this;
    332 				},
    333
    334 				onDragStop: function(callback, scope) {
    335 					dragAndDropController.addCallback('dragStop', owfdojo.hitch(scope, callback));
    336 					return this;
    337 				},
    338
    339 				onDrop: function(callback, scope) {
    340 					dragAndDropController.addCallback('dropReceive', owfdojo.hitch(scope, callback));
    341 					return this;
    342 				},
    343
    344 				startDrag: function(cfg) {
    345 					dragAndDropController.doStartDrag(cfg);
    346 					return this;
    347 				}
    348 			};
    349
    350 			for(var i = 0, methods = ['addDropZoneHandler', 'getDragStartData', 'getDropEnabled', 'setDropEnabled', 'isDragging', 'getFlashWidgetId', 'setFlashWidgetId'] ; i < methods.length ; i++) {
    351
    352 				OWF.DragAndDrop[ methods[i] ] = function( methodName ) {
    353
    354 					return function() {
    355 						return dragAndDropController[methodName].apply(dragAndDropController, arguments);
    356 					};
    357
    358 				}( methods[i] );
    359
    360 			}
    361 		}
    362
    363 		// Chrome API
    364 		function initChrome() {
    365 			for(var i = 0,
    366 				methods = ['addHeaderButtons', 'addHeaderMenus', 'insertHeaderButtons', 'insertHeaderMenus',
    367                     'isModified', 'listHeaderButtons', 'listHeaderMenus', 'removeHeaderButtons', 'removeHeaderMenus',
    368                     'updateHeaderButtons', 'updateHeaderMenus', 'getTitle', 'setTitle'] ; i < methods.length ; i++) {
    369 				OWF.Chrome[ methods[i] ] = chromeController[ methods[i] ];
    370 			}
    371 		}
    372
    373 		eventingController = Ozone.eventing.Widget.getInstance(function() {
    374
    375 			dragAndDropController = Ozone.dragAndDrop.WidgetDragAndDrop.getInstance({
    376 				widgetEventingController: this
    377 			});
    378 			launchingController = Ozone.launcher.WidgetLauncher.getInstance();
    379 			chromeController = Ozone.chrome.WidgetChrome.getInstance({
    380 				widgetEventingController: this
    381 			});
    382
    383 			initEventing.call(this);
    384 			initRPC();
    385 			initPreferences();
    386 			initLauncher();
    387 			initDragAndDrop();
    388 			initChrome();
    389
    390 			Ozone.components.keys.createKeyEventSender(this);
    391
    392 			// execute ready listeners
    393 			isReady = true;
    394 			for(var i = 0, len = readyList.length ; i < len ; i++) {
    395 				readyList[i].fn.call(readyList[i].scope);
    396 			}
    397
    398 		});
    399
    400 	};
    401
    402 }(window, document));
    403
    404 // --------------------------------------------------------------------------------------------------
    405 // ------------------- Eventing ---------------------------------------------------------------------
    406 // --------------------------------------------------------------------------------------------------
    407 /**
    408  * @name relayFile
    409  * @memberOf OWF
    410  * @description The location of the widget relay file.  The relay file should be defined
    411  *   globally for the entire widget by setting OWF.relayFile to the relay file url, immediately after
    412  *   including the widget bundle javascript.  If the relay is not defined at all it is assumed to be at
    413  *   /[context]/js/eventing/rpc_relay.uncompressed.html. The relay file must be specified with full location details, but without a fully
    414  *   qualified path. In the case where the relay is residing @ http://server/path/relay.html, the path used must be from the context root of the local
    415  *   widget. In this case, it would be /path/relay.html.  Do not include the protocol.
    416  * @since OWF 5.0.0
    417  * @example
    418  * <script type="text/javascript" src="../../js-min/owf-widget-min.js"></script>
    419  * <script>
    420  *       //The location is assumed to be at /[context]/js/eventing/rpc_relay.uncompressed.html if it is not
    421  *       //set the path correctly below
    422  *       OWF.relayFile = '/owf/js/eventing/rpc_relay.uncompressed.html';
    423  *       //...
    424  * </script>
    425  *
    426  */
    427
    428 /**
    429 	Subscribe to a named channel for a given function.
    430 	@name subscribe
    431 	@methodOf OWF.Eventing
    432
    433 	@param {String} channelName The channel to subscribe to.
    434 	@param {Function} handler The function you wish to subscribe.  This function will be called with three
    435 		arguments: sender, msg, channel.
    436 	@param {String} [handler.sender] The first argument passed to the handler function is the id of the sender of the message. See <a href="OWF.html#.getIframeId">OWF.getIframeId</a> for a description of this id.
    437 	@param {Object} [handler.msg] The second argument passed to the handler function is the message itself.
    438 	@param {String} [handler.channel] The third argument passed to the handler function is the channel the message was published on.
    439
    440 	@example
    441 OWF.Eventing.subscribe("ClockChannel", this.update);
    442 var update = function(sender, msg, channel) {
    443 	document.getElementById('currentTime').innerHTML = msg;
    444 }
    445  */
    446
    447 /**
    448 	Unsubscribe to a named channel.
    449 	@name unsubscribe
    450 	@methodOf OWF.Eventing
    451
    452 	@param {String} channelName The channel to unsubscribe to.
    453
    454 	@example
    455 OWF.Eventing.unsubscribe("ClockChannel");
    456  */
    457
    458 /**
    459 	Publishes a message to a given channel.
    460 	@name publish
    461 	@methodOf OWF.Eventing
    462
    463 	@param {String} channelName The name of the channel to publish to
    464 	@param {Object} message The message to publish to the channel.
    465 	@param {String} [dest] The id of a particular destination.  Defaults to null which sends to all
    466 		subscribers on the channel.  See <a href="OWF.html#.getIframeId">OWF.getIframeId</a>
    467 		for a description of the id.
    468
    469 	@example
    470 OWF.Eventing.publish("ClockChannel", currentTimeString);
    471 */
    472
    473 // --------------------------------------------------------------------------------------------------
    474 // ------------------- RPC --------------------------------------------------------------------------
    475 // --------------------------------------------------------------------------------------------------
    476
    477 /**
    478 	Register one or more functions to OWF to expose to other widgets.
    479 	@name registerFunctions
    480 	@methodOf OWF.RPC
    481
    482 	@param {Object/Array} objs Object or an array of objects of following structure.<br />
    483 		{<br />
    484 			name: 'name of the function', <br />
    485 			fn: function() {}, <br />
    486 			scope: window //The scope (this reference) in which the function is executed. If omitted, defaults to the browser window.<br />
    487 		}<br />
    488
    489 	@example
    490 Calculator = {
    491 	add: function() {
    492 		var args = arguments,
    493 			val = 0;
    494 		for(var i = 0, len = args.length; i < len; i++) {
    495 			val += parseFloat(args[i]);
    496 		}
    497 		return val;
    498 	},
    499 	multiply: function() {
    500 		var args = arguments,
    501 			val = 1;
    502 		for(var i = 0, len = args.length; i < len; i++) {
    503 			val *= parseFloat(args[i]);
    504 		}
    505 		return val;
    506 	}
    507 };
    508 OWF.RPC.registerFunctions([
    509 	{
    510 		name: 'add'
    511 		fn: Calculator.add,
    512 		scope: Calculator
    513 	},
    514 	{
    515 		name: 'multiply'
    516 		fn: Calculator.multiply,
    517 		scope: Calculator
    518 	}
    519 ]);
    520 */
    521
    522 /**
    523 	Gets a proxy object that contains methods exposed by other widget.
    524 	@name getWidgetProxy
    525 	@methodOf OWF.RPC
    526
    527 	@param {String} instanceGuid instance guid of the widget to import
    528 	@param {Function} callback function that will be executed if the widget is found opened on the current dashboard. The function is passed a proxy object as the first argument which will contain methods that were exposed by the widget. In addition, the proxy abject also has sendMessage method to send a direct message to the widget.
    529
    530 	@example
    531 OWF.RPC.getWidgetProxy('instanceGuid of widgetA', function(widgetA) {
    532
    533 	widgetA.add(1,2,3, function(result) {
    534 		console.log(result); // log the result
    535 	})
    536
    537 	widgetA.sendMessage('some secret message');
    538
    539 });
    540 */
    541
    542 /**
    543 	Register a function to be executed when a direct message is received from another widget.
    544 	@name handleDirectMessage
    545 	@methodOf OWF.RPC
    546
    547 	@param {Function} fn function that will be executed when a direct message is received from another widget.
    548
    549 	@example
    550 OWF.RPC.handleDirectMessage(function(msg) {
    551 	// do something with the message
    552 });
    553 */
    554
    555 // --------------------------------------------------------------------------------------------------
    556 // ------------------- Drag and Drop ----------------------------------------------------------------
    557 // --------------------------------------------------------------------------------------------------
    558 /**
    559 	Use this method to set flex dom element id, so that drag and drop can be enabled in flex widgets.
    560 	@name setFlashWidgetId
    561 	@methodOf OWF.DragAndDrop
    562
    563 	@param {String} id dom element id of flex widget
    564 */
    565
    566 /**
    567 	Starts a drag.  The config object passed in describes the drag and contains the data to be passed to the drop.
    568 	@name startDrag
    569 	@methodOf OWF.DragAndDrop
    570
    571 	@param {Object} cfg config object see below
    572 	@param {String} cfg.dragDropLabel Name to be used as text for the dragDrop indicator
    573 	@param {Object} cfg.dragDropData Data to be sent on a successful drag and drop.  This property is only sent to the
    574 	successful recipient of the drag (the dropReceive event).  It will not be sent for other events.
    575 	@param {Object} cfg.dragZone dom node which presents a dragZone which is associated with this drag.  This property is
    576 	only saved and used locally to the widget to identify whether a dragZone is in fact the node as a dropZone.  It will not be
    577 	sent to other events callbacks.
    578 	@param {Object} cfg.* other custom properties may be specified, these will be passed along to event handlers
    579
    580 	@example
    581 //add handler to text field for dragging
    582 owfdojo.connect(document.getElementById('dragSource'), 'onmousedown', this, function(e) {
    583 	e.preventDefault();
    584 	var data = document.getElementById('InputChannel').value;
    585 	if (data) {
    586 		OWF.DragAndDrop.startDrag({
    587 			dragDropLabel: data,
    588 			dragDropData: data,
    589 			dragZone:  document.getElementById('dragZone'),
    590 			dragDropGroup: 'location'  //extra property to pass along
    591 		});
    592 	}
    593 });
    594 */
    595
    596
    597 /**
    598 	Adds a new drop zone to be managed.  The handler function defined in the cfg object will be called when
    599 	a drop occurs over a dom node which matches the id or the className or is equal to or a child of the dropTarget node
    600 	@name addDropZoneHandler
    601 	@methodOf OWF.DragAndDrop
    602
    603 	@param {Object} cfg config object see below
    604 	@param {className} cfg.class class of the dropZone
    605 	@param {String} cfg.id Id of the dropZone
    606 	@param {Node} cfg.dropZone HTML node which represents the dropZone
    607 	@param {Function} cfg.handler function to be called when a drop occurs over the dropZone.  A msg object will be passed in
    608
    609 	@example
    610 //Example cfg Object
    611 {
    612 	id: 'mygrid-1',
    613 	className: 'mygridClass',
    614 	dropZone: document.getElementById('dropZone'),
    615 	handler: function(msg) {
    616 		//some code here to handle the msg and respond
    617 	}
    618 }
    619
    620 //Example usage of addDropZoneHandler which handles a drop that occurs over an Ext Grid and inserts new data into
    621 //that grid based on the dragged data
    622 OWF.DragAndDrop.addDropZoneHandler({
    623 	//dom node of an Ext grid
    624 	dropZone:grid.getView().scroller.dom,
    625
    626 	//this function is called only when a drop occurs over the grid (i.e. the mouse was released over the grid)
    627 	handler: (function(msg){
    628
    629 		var store = grid.getStore();
    630 		var processedSelections = [];
    631 		var errorMsg = null;
    632
    633 		//loop through msg.dragDropData which is an array and check for dupes versus the destination store
    634 		for (var i = 0; i < msg.dragDropData.length; i++) {
    635 			//get data for one possible new record in the dragDropData
    636 			var recData = msg.dragDropData[i];
    637
    638 			//is it already in the dest Ext Store?
    639 			if (store.findExact('id',recData.id) >= 0) {
    640 				//found the record already in the store
    641 			}
    642 			else {
    643 				//add new record based on the dragDropData
    644 				var newRec = new store.recordType(recData);
    645 				//calling an external function to decide whether to add the new rec
    646 				var rs = displayPanel.validateRecordOnAdd(newRec);
    647 				if (rs.success) {
    648 					processedSelections.push(newRec);
    649 				}
    650 				else {
    651 					errorMsg = rs.msg;
    652 				}
    653 			}
    654 		}
    655
    656 		if (errorMsg) {
    657 			Ext.Msg.alert('Error', errorMsg);
    658 		}
    659
    660 		//actually insert into the store which adds it the new recs to the grid
    661 		if (processedSelections.length > 0) {
    662 			store.insert(0, processedSelections);
    663 		}
    664
    665 }).createDelegate(grid)});   //createDelegate is an Ext function which sets the scope of the callback
    666
    667 */
    668
    669
    670 /**
    671 	Returns whether the a drop is enabled (this is only true when the mouse is over a drop zone)
    672 	@name getDropEnabled
    673 	@methodOf OWF.DragAndDrop
    674 */
    675
    676 /**
    677 	Returns whether a drag is in progress
    678 	@name isDragging
    679 	@methodOf OWF.DragAndDrop
    680 */
    681
    682 /**
    683 	Returns data sent when a drag was started
    684 	@name getDragStartData
    685 	@methodOf OWF.DragAndDrop
    686 */
    687
    688 /**
    689 	Toggles the dragIndicator to indicate successful or unsuccessful drop
    690 	@name setDropEnabled
    691 	@methodOf OWF.DragAndDrop
    692
    693 	@param {Boolean} dropEnabled true to enable a drop, false to indicate a unsuccessful drop
    694
    695 	@example
    696 //attach mouseover callback to a particular area. If the mouse is here allow a drop
    697 cmp.getView().scroller.on('mouseover',function(e,t,o) {
    698 	if (cmp.dragging) {
    699 		OWF.DragAndDrop.setDropEnabled(true);
    700 	}
    701 },this);
    702
    703 //attach a mouse out callback to a particular area. If the mouse leaves disable drop
    704 cmp.getView().scroller.on('mouseout',function(e,t,o) {
    705 	if (cmp.dragging) {
    706 		OWF.DragAndDrop.setDropEnabled(false);
    707 	}
    708 },this);
    709    */
    710
    711
    712 /**
    713 	Executes the callback passed when a drag starts in any widget.
    714 	@name onDragStart
    715 	@methodOf OWF.DragAndDrop
    716
    717 	@param {Function} callback The function to execute as a callback.
    718 	@param {Object} scope The scope (this reference) in which the function is executed. If omitted, defaults to the browser window.
    719
    720 	@example
    721 //example callback, highlights an Ext Grid when a drag occurs
    722 OWF.DragAndDrop.onDragStart(function(sender, msg) {
    723 	//get the Ext Grid
    724 	var grid = this.getComponent(this.gridId);
    725
    726 	//check custom dragDropGroup property to see if the drag is meant for this grid
    727 	//if so highlight the grid by adding the ddOver class
    728 	if (grid && msg != null && msg.dragDropGroup == 'users') {
    729 		grid.getView().scroller.addClass('ddOver');
    730 	}
    731 }, this);
    732 */
    733
    734 /**
    735 	Executes the callback passed when a drag stops in any widget.
    736 	@name onDragStop
    737 	@methodOf OWF.DragAndDrop
    738
    739 	@param {Function} callback The function to execute as a callback.
    740 	@param {Object} scope The scope (this reference) in which the function is executed. If omitted, defaults to the browser window.
    741
    742 	@example
    743
    744 OWF.DragAndDrop.onDragStop(function(sender, msg) {
    745 	// do something here
    746 }, this);
    747 */
    748
    749 /**
    750 	Executes the callback passed when a drop occurs in the widget. If one has multiple dropZones in a widget it is easier to use <a href="#addDropZoneHandler">addDropZoneHandler</a>
    751 	@name onDrop
    752 	@methodOf OWF.DragAndDrop
    753
    754 	@param {Function} callback The function to execute as a callback.
    755 	@param {Object} scope The scope (this reference) in which the function is executed. If omitted, defaults to the browser window.
    756
    757 	@example
    758
    759 OWF.DragAndDrop.onDrop(function(sender, msg) {
    760 	var data = msg.dragDropData;
    761
    762 	// do something with the data here
    763 }, this);
    764 	*/
    765
    766 // --------------------------------------------------------------------------------------------------
    767 // ------------------- Launcher ---------------------------------------------------------------------
    768 // --------------------------------------------------------------------------------------------------
    769
    770 /**
    771 	Launches a Widget based on the config.
    772 	@name launch
    773 	@methodOf OWF.Launcher
    774
    775 	@param {Object} config object see example for structure
    776 	@param {Function} callback a function to be called once after the launchWidget is executed
    777
    778 	@example
    779 OWF.Launcher.launch({
    780     universalName: 'universal name of widget to launch',  //universalName or guid maybe identify the widget to be launched
    781     guid: 'guid_of_widget_to_launch',
    782     title: 'title to replace the widget title' the title will only be changed if the widget is opened.
    783     titleRegex: optional regex used to replace the previous title with the new value of title
    784     launchOnlyIfClosed: true,   //if true will only launch the widget if it is not already opened.
    785                                 //if it is opened then the widget will be brought to focus
    786     data: dataString            //initial launch data to be passed to a widget only if the widget is opened. This must be a string.
    787 }, callback);
    788  */
    789
    790 /**
    791 	Retrieves initial launch data for this widget if it is opened by another widget.  If launched via an intent, it will return the JSON string { intents: true }.
    792 	@name getLaunchData
    793 	@methodOf OWF.Launcher
    794
    795 	@returns {Object} data object which contains initial launch data for the widget
    796
    797 	@example
    798 var launchData = OWF.Launcher.getLaunchData();
    799 if (launchData != null) {
    800 	var data = Ozone.util.parseJson(launchData);  //in this example the data object has two fields: channel and message
    801 	if (data != null) {
    802 		//do something with the data
    803 		OWF.Eventing.subscribe(data.channel, function() {});
    804 	}
    805 }
    806 */
    807
    808 // --------------------------------------------------------------------------------------------------
    809 // ------------------- Chrome -----------------------------------------------------------------------
    810 // --------------------------------------------------------------------------------------------------
    811
    812 /**
    813 	Checks to see if the Widget Chrome has already been modified.  This is useful when the widget iframe is reloaded.
    814 	@name isModified
    815 	@methodOf OWF.Chrome
    816
    817 	@param {Object} cfg config object see below for properties
    818 	@param {Function} cfg.callback The function which receives the results.
    819 	This method will be passed an object which has following properties. <br>
    820 	<br>
    821 		{Boolean} success: true if the widget is currently opened on the dashboard, or else false. <br>
    822 		{Boolean} modified: true if the widget chrome(header) is modified, or else false. <br>
    823 	*
    824 	@example
    825 OWF.Chrome.isModified({
    826 	callback: function(msg) {
    827 		//msg will always be a json string
    828 		var res = Ozone.util.parseJson(msg);
    829 		if (res.success) {
    830 			//if the chrome was never modified
    831 			if (!res.modified) {
    832 			   //do something, perhaps add buttons
    833 			}
    834 			//if we already modified the chrome
    835 			else {
    836 			  //do something or perhaps nothing if the buttons are already added
    837 			}
    838 		}
    839 	}
    840 });
    841 */
    842
    843
    844 /**
    845 	Adds buttons to the Widget Chrome. Buttons are added after existing buttons.
    846 	@name addHeaderButtons
    847 	@methodOf OWF.Chrome
    848
    849 	@param {Object} cfg config object see below for properties
    850 	@param {Object[]} cfg.items an array of buttons configurations to add to the chrome.  See example for button configs
    851 	@param {String} cfg.items[*].itemId itemId is a unique id among all buttons that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.  If itemId is not unique this may result in duplicate buttons which may not be able to be removed properly.
    852 	@param {String} cfg.items[*].xtype xtype is ExtJS-like property used to determine the component to create.  Currently the Widget Chrome API only supports two xtype values: ‘button’ and ‘widgettool’.  xtype is an optional field, if it is omitted ‘widgettool’ is used.
    853 	@param {String} cfg.items[*].type Used only for ‘widgettool’ buttons.  It determines the standard icon to be used.  For a complete list of types please see the ExtJS 4.x API documentation, <a href='http://docs.sencha.com/ext-js/4-0/#/api/Ext.panel.Tool-cfg-type'>http://docs.sencha.com/ext-js/4-0/#/api/Ext.panel.Tool-cfg-type</a>
    854 	@param {String} cfg.items[*].icon This property defines the URL of the image to be used for the button.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    855 	@param {String} cfg.items[*].text This property defines text to appear alongside the button.  This property is only used if the xtype is ‘button.’  ‘widgettool’ will not show text.
    856 	@param {Object} cfg.items[*].tooltip This property defines a tooltip.  It has two important sub properties, title and text.  tooltip is only used when the xtype is ‘button’
    857 	@param {Function} cfg.items[*].handler The handler attribute defines a function to be executed when the button is pressed. This function is executed using Widget Eventing API from inside the widget.  The internal channel name used is the itemId attribute. This function’s parameter list contains the standard parameters for an Eventing callback function.
    858
    859 	@example
    860 OWF.Chrome.addHeaderButtons({
    861 	items: [
    862 		{
    863 			xtype: 'button',
    864 			//path to an image to use. this path should either be fully qualified or relative to the /owf context
    865 			icon: './themes/common/images/skin/exclamation.png',
    866 			text: 'Alert',
    867 			itemId:'alert',
    868 			tooltip:  {
    869 			  text: 'Alert!'
    870 			},
    871 			handler: function(sender, data) {
    872 				//widgetState is an already instantiated WidgetState Obj
    873 				if (widgetState) {
    874 					widgetState.getWidgetState({
    875 						callback: function(state) {
    876 							//check if the widget is visible
    877 							if (!state.collapsed && !state.minimized && state.active) {
    878 								//only render visual content, perhaps popup a message box if the widget is visible
    879 								//otherwise it may not render correctly
    880 							}
    881 						}
    882 					});
    883 				}
    884 			}
    885 		},
    886 		{
    887 			xtype: 'widgettool',
    888 			//path to an image to use. this path should either be fully qualified or relative to the /owf context
    889 			icon: './themes/common/images/skin/information.png',
    890 			itemId:'help',
    891 			handler: function(sender, data) {
    892 				alert('About Button Pressed');
    893 			}
    894 		},
    895 		{
    896 			//gear is a standard ext tool type
    897 			type: 'gear',
    898 			itemId:'gear',
    899 			handler: function(sender, data) {
    900 				alert('Utility Button Pressed');
    901 			}
    902 		}
    903 	]
    904 });
    905    */
    906
    907 /**
    908 	Updates any existing buttons in the Widget Chrome based on the itemId.
    909 	@name updateHeaderButtons
    910 	@methodOf OWF.Chrome
    911
    912 	@param {Object} cfg config object see below for properties
    913 	@param {Object[]} cfg.items an array of buttons configurations to add to the chrome.  See example below for button configs
    914 	@param {String} cfg.items[*].itemId itemId is a unique id among all buttons that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.  If itemId is not unique this may result in duplicate buttons which may not be able to be removed properly.
    915 	@param {String} cfg.items[*].xtype xtype is ExtJS-like property used to determine the component to create.  Currently the Widget Chrome API only supports two xtype values: ‘button’ and ‘widgettool’.  xtype is an optional field, if it is omitted ‘widgettool’ is used.
    916 	@param {String} cfg.items[*].type Used only for ‘widgettool’ buttons.  It determines the standard icon to be used.  For a complete list of types please see the ExtJS 4.x API documentation, <a href='http://docs.sencha.com/ext-js/4-0/#/api/Ext.panel.Tool-cfg-type'>http://docs.sencha.com/ext-js/4-0/#/api/Ext.panel.Tool-cfg-type</a>
    917 	@param {String} cfg.items[*].icon This property defines the URL of the image to be used for the button.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    918 	@param {String} cfg.items[*].text This property defines text to appear alongside the button.  This property is only used if the xtype is ‘button.’  ‘widgettool’ will not show text.
    919 	@param {Object} cfg.items[*].tooltip This property defines a tooltip.  It has two important sub properties, title and text.  tooltip is only used when the xtype is ‘button’
    920 	@param {Function} cfg.items[*].handler The handler attribute defines a function to be executed when the button is pressed. This function is executed using Widget Eventing API from inside the widget.  The internal channel name used is the itemId attribute. This function’s parameter list contains the standard parameters for an Eventing callback function.
    921
    922 	@example
    923 OWF.Chrome.updateHeaderButtons({
    924 	items: [
    925 		{
    926 			xtype: 'button',
    927 			//path to an image to use. this path should either be fully qualified or relative to the /owf context
    928 			icon: './themes/common/images/skin/exclamation.png',
    929 			text: 'Alert',
    930 			itemId:'alert',
    931 			tooltip:  {
    932 			  text: 'Alert!'
    933 			},
    934 			handler: function(sender, data) {
    935 				//widgetState is an already instantiated WidgetState Obj
    936 				if (widgetState) {
    937 					widgetState.getWidgetState({
    938 						callback: function(state) {
    939 							//check if the widget is visible
    940 							if (!state.collapsed && !state.minimized && state.active) {
    941 								//only render visual content, perhaps popup a message box if the widget is visible
    942 								//otherwise it may not render correctly
    943 							}
    944 						}
    945 					});
    946 				}
    947 			}
    948 		},
    949 		{
    950 			xtype: 'widgettool',
    951 			//path to an image to use. this path should either be fully qualified or relative to the /owf context
    952 			icon: './themes/common/images/skin/information.png',
    953 			itemId:'help',
    954 			handler: function(sender, data) {
    955 				alert('About Button Pressed');
    956 			}
    957 		},
    958 		{
    959 			//gear is a standard ext tool type
    960 			type: 'gear',
    961 			itemId:'gear',
    962 			handler: function(sender, data) {
    963 				alert('Utility Button Pressed');
    964 			}
    965 		}
    966 	]
    967 });
    968 */
    969
    970 /**
    971 	Inserts new buttons to the Widget Chrome.  Buttons are added to the same area as existing buttons.
    972 	@name insertHeaderButtons
    973 	@methodOf OWF.Chrome
    974
    975 	@param {Object} cfg config object see below for properties
    976 	@param {Number} [cfg.pos=0] 0-based index of where buttons will be added, among any pre-existing buttons.
    977 	@param {Object[]} cfg.items an array of buttons configurations to insert to the chrome.  See example below for button configs
    978 	@param {String} cfg.items[*].itemId itemId is a unique id among all buttons that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.  If itemId is not unique this may result in duplicate buttons which may not be able to be removed properly.
    979 	@param {String} cfg.items[*].xtype xtype is ExtJS-like property used to determine the component to create.  Currently the Widget Chrome API only supports two xtype values: ‘button’ and ‘widgettool’.  xtype is an optional field, if it is omitted ‘widgettool’ is used.
    980 	@param {String} cfg.items[*].type Used only for ‘widgettool’ buttons.  It determines the standard icon to be used.  For a complete list of types please see the ExtJS 4.x API documentation, <a href='http://docs.sencha.com/ext-js/4-0/#/api/Ext.panel.Tool-cfg-type'>http://docs.sencha.com/ext-js/4-0/#/api/Ext.panel.Tool-cfg-type</a>
    981 	@param {String} cfg.items[*].icon This property defines the URL of the image to be used for the button.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    982 	@param {String} cfg.items[*].text This property defines text to appear alongside the button.  This property is only used if the xtype is ‘button.’  ‘widgettool’ will not show text.
    983 	@param {Object} cfg.items[*].tooltip This property defines a tooltip.  It has two important sub properties, title and text.  tooltip is only used when the xtype is ‘button’
    984 	@param {Function} cfg.items[*].handler The handler attribute defines a function to be executed when the button is pressed. This function is executed using Widget Eventing API from inside the widget.  The internal channel name used is the itemId attribute. This function’s parameter list contains the standard parameters for an Eventing callback function.
    985
    986 	@example
    987 OWF.Chrome.insertHeaderButtons({
    988 	pos: 0,
    989 	items: [
    990 		{
    991 			xtype: 'button',
    992 			//path to an image to use. this path should either be fully qualified or relative to the /owf context
    993 			icon: './themes/common/images/skin/exclamation.png',
    994 			text: 'Alert',
    995 			itemId:'alert',
    996 			tooltip:  {
    997 				text: 'Alert!'
    998 			},
    999 			handler: function(sender, data) {
    1000 				//widgetState is an already instantiated WidgetState Obj
    1001 				if (widgetState) {
    1002 					widgetState.getWidgetState({
    1003 						callback: function(state) {
    1004 							//check if the widget is visible
    1005 							if (!state.collapsed && !state.minimized && state.active) {
    1006 								//only render visual content, perhaps popup a message box if the widget is visible
    1007 								//otherwise it may not render correctly
    1008 							}
    1009 						}
    1010 					});
    1011 				}
    1012 			}
    1013 		},
    1014 		{
    1015 			xtype: 'widgettool',
    1016 			//path to an image to use. this path should either be fully qualified or relative to the /owf context
    1017 			icon: './themes/common/images/skin/information.png',
    1018 			itemId:'help',
    1019 			handler: function(sender, data) {
    1020 				alert('About Button Pressed');
    1021 			}
    1022 		},
    1023 			{
    1024 			//gear is a standard ext tool type
    1025 			type: 'gear',
    1026 			itemId:'gear',
    1027 			handler: function(sender, data) {
    1028 				alert('Utility Button Pressed');
    1029 			}
    1030 		}
    1031 	]
    1032 });
    1033 */
    1034
    1035 /**
    1036 	Removes existing buttons on the Widget Chrome based on itemId.
    1037 	@name removeHeaderButtons
    1038 	@methodOf OWF.Chrome
    1039
    1040 	@param {Object} cfg config object see below for properties
    1041 	@param {Object[]} cfg.items an array of buttons configurations to remove to the chrome.  Only itemId is required.
    1042 	See example below for button configs
    1043 	@param {String} cfg.items[*].itemId itemId is a unique id among all buttons that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.  If itemId is not unique this may result in duplicate buttons which may not be able to be removed properly.
    1044
    1045 	@example
    1046 OWF.Chrome.removeHeaderButtons({
    1047 		items:[
    1048 			{
    1049 				itemId:'alert'
    1050 			},
    1051 			{
    1052 				itemId:'help'
    1053 			},
    1054 			{
    1055 				itemId:'gear'
    1056 			}
    1057 		]
    1058 });
    1059 */
    1060
    1061 /**
    1062 	Lists all buttons that have been added to the widget chrome.
    1063 	@name listHeaderButtons
    1064 	@methodOf OWF.Chrome
    1065
    1066 	@param {Object} cfg config object see below for properties
    1067 	@param {Function} cfg.callback The function which receives the results.
    1068
    1069 	@example
    1070 OWF.Chrome.listHeaderButtons({
    1071 	callback: function(msg) {
    1072 		//msg will always be a json string
    1073 		var res = Ozone.util.parseJson(msg);
    1074 		if (res.success) {
    1075 			for (var i = 0; i < res.items.length; i++) {
    1076 				// do something with the buttons
    1077 			}
    1078 		}
    1079 	}
    1080 });
    1081 */
    1082
    1083 /**
    1084 	Adds menus to the Widget Chrome.  Menus are added after existing menus.
    1085 	@name addHeaderMenus
    1086 	@methodOf OWF.Chrome
    1087
    1088 	@param {Object} cfg config object see below for properties
    1089 	@param {Object[]} cfg.items an array of menu configurations to add to the chrome.  See example for menu configs
    1090 	@param {String} cfg.items[*].parentId itemId is the itemId of the menu to which this configuration should be added as a sub-menu.  If omitted, the configuration will be added as a main menu on the menu toolbar.
    1091 	@param {String} cfg.items[*].itemId itemId is a unique id among all menus that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.  If itemId is not unique this may result in duplicate menus which may not be able to be removed properly.
    1092 	@param {String} cfg.items[*].icon This property defines the URL of the image to be used for the menu.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    1093 	@param {String} cfg.items[*].text This property defines text to appear alongside the menu.
    1094 	@param {Object} cfg.items[*].menu menu configuration object
    1095 	@param {Object[]} cfg.items[*].menu.items an array of menu item configurations to add to the chrome.  See example for menu item configs
    1096 	@param {String} cfg.items[*].menu.items[*].itemId itemId is a unique id among all menu items that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.
    1097 	@param {String} cfg.items[*].menu.items[*].xtype xtype is used to specify the type of menu item to add.  This attribute should be omitted unless specifying a menuseparator. Setting this value to "menuseparator" adds a separator bar to a menu, used to divide logical groups of menu items. If specified, only xtype should be specified.  Generally you will add one of these by using "-" in your items config rather than creating one directly using xtype.  See example below for usage.
    1098 	@param {String} cfg.items[*].menu.items[*].icon This property defines the URL of the image to be used for the menu item.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    1099 	@param {String} cfg.items[*].menu.items[*].text This property defines text to appear for the menu item.
    1100 	@param {Function} cfg.items[*].menu.items[*].handler The handler attribute defines a function to be executed when the menu item is clicked. This function is executed using Widget Eventing API from inside the widget.  The internal channel name used is the itemId attribute. This function's parameter list contains the standard parameters for an Eventing callback function.
    1101 	@param {Object} cfg.items[*].menu.items[*].menu sub-menu configuration object.  See example for sub-menu config.
    1102
    1103 	@example
    1104 OWF.Chrome.addHeaderMenus({
    1105 	items: [
    1106 		{
    1107 			itemId:'regularMenu',
    1108 			icon: './themes/common/images/skin/exclamation.png',
    1109 			text: 'Regular Menu',
    1110 			menu: {
    1111 				items: [
    1112 					{
    1113 						itemId:'regularMenuItem1',
    1114 						icon: './themes/common/images/skin/exclamation.png',
    1115 						text: 'Regular Menu Item 1',
    1116 						handler: function(sender, data) {
    1117 							alert('You clicked the Regular Menu menu item.');
    1118 						}
    1119 					}
    1120 				]
    1121 			}
    1122 		},
    1123 		{
    1124 			itemId:'snacks',
    1125 			icon: './themes/common/images/skin/exclamation.png',
    1126 			text: 'Menu with Sub-Menu',
    1127 			menu: {
    1128 				items: [
    1129 					{
    1130 						itemId:'fruits',
    1131 						icon: './themes/common/images/skin/exclamation.png',
    1132 						text: 'Fruits',
    1133 						menu: {
    1134 							items: [
    1135 								{
    1136 									itemId:'apple',
    1137 									icon: './themes/common/images/skin/exclamation.png',
    1138 									text: 'Apple',
    1139 									handler: function(sender, data) {
    1140 										alert('Your snack will be an Apple.');
    1141 									}
    1142 								},
    1143 							   {
    1144 								   xtype: 'menuseparator'
    1145 							   },
    1146 								{
    1147 									itemId:'banana',
    1148 									icon: './themes/common/images/skin/exclamation.png',
    1149 									text: 'Banana',
    1150 									handler: function(sender, data) {
    1151 										alert('Your snack will be a Banana.');
    1152 									}
    1153 								}, {
    1154 									itemId:'cherry',
    1155 									icon: './themes/common/images/skin/exclamation.png',
    1156 									text: 'Cherries',
    1157 									handler: function(sender, data) {
    1158 										alert('Your snack will be Cherries.');
    1159 									}
    1160 								}
    1161 							]
    1162 						}
    1163 					},
    1164 					'-', // another way to add a menu separator
    1165 					{
    1166 						itemId:'cupcake',
    1167 						icon: './themes/common/images/skin/exclamation.png',
    1168 						text: 'Cupcake',
    1169 						handler: function(sender, data) {
    1170 							alert('Your snack will be a Cupcake.');
    1171 						}
    1172 					},
    1173 					{
    1174 						itemId:'chips',
    1175 						icon: './themes/common/images/skin/exclamation.png',
    1176 						text: 'Potato Chips',
    1177 						handler: function(sender, data) {
    1178 							alert('Your snack will be a Potato Chips.');
    1179 						}
    1180 					}
    1181 				]
    1182 			}
    1183 		}
    1184 	]
    1185 });
    1186 */
    1187
    1188 /**
    1189 	Updates any existing menus in the Widget Chrome based on the itemId.
    1190 	@name updateHeaderMenus
    1191 	@methodOf OWF.Chrome
    1192
    1193 	@param {Object} cfg config object see below for properties
    1194 	@param {Object[]} cfg.items an array of menu configurations to add to the chrome.  See example for menu configs
    1195 	@param {String} cfg.items[*].itemId itemId is a unique id among all menus that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.  If itemId is not unique this may result in duplicate menus which may not be able to be removed properly.
    1196 	@param {String} cfg.items[*].icon This property defines the URL of the image to be used for the menu.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    1197 	@param {String} cfg.items[*].text This property defines text to appear alongside the menu.
    1198 	@param {Object} cfg.items[*].menu menu configuration object
    1199 	@param {Object[]} cfg.items[*].menu.items an array of menu item configurations to add to the chrome.  See example for menu item configs
    1200 	@param {String} cfg.items[*].menu.items[*].itemId itemId is a unique id among all menu items that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.
    1201 	@param {String} cfg.items[*].menu.items[*].xtype xtype is used to specify the type of menu item to add.  This attribute should be omitted unless specifying a menuseparator. Setting this value to "menuseparator" adds a separator bar to a menu, used to divide logical groups of menu items. If specified, only xtype should be specified.  See example below for usage.
    1202 	@param {String} cfg.items[*].menu.items[*].icon This property defines the URL of the image to be used for the menu item.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    1203 	@param {String} cfg.items[*].menu.items[*].text This property defines text to appear for the menu item.
    1204 	@param {Function} cfg.items[*].menu.items[*].handler The handler attribute defines a function to be executed when the menu item is clicked. This function is executed using Widget Eventing API from inside the widget.  The internal channel name used is the itemId attribute. This function's parameter list contains the standard parameters for an Eventing callback function.
    1205 	@param {Object} cfg.items[*].menu.items[*].menu sub-menu configuration object.  See example for sub-menu config.
    1206
    1207 	@example
    1208 OWF.Chrome.updateHeaderMenus({
    1209 	items:[
    1210 		{
    1211 			itemId:'regularMenu',
    1212 			icon: './themes/common/images/skin/exclamation.png',
    1213 			text: 'Regular Menu',
    1214 			menu: {
    1215 				items: [
    1216 					{
    1217 						itemId:'regularMenuItem1',
    1218 						icon: './themes/common/images/skin/exclamation.png',
    1219 						text: 'Regular Menu Item 1',
    1220 						handler: function(sender, data) {
    1221 							alert('You clicked the Regular Menu menu item.');
    1222 						}
    1223 					}
    1224 				]
    1225 			}
    1226 		},
    1227 		{
    1228 			itemId:'snacks',
    1229 			icon: './themes/common/images/skin/exclamation.png',
    1230 			text: 'Menu with Sub-Menu',
    1231 			menu: {
    1232 				items: [
    1233 					{
    1234 						itemId:'fruits',
    1235 						icon: './themes/common/images/skin/exclamation.png',
    1236 						text: 'Fruits',
    1237 						menu: {
    1238 							items: [
    1239 								{
    1240 									itemId:'apple',
    1241 									icon: './themes/common/images/skin/exclamation.png',
    1242 									text: 'Apple',
    1243 									handler: function(sender, data) {
    1244 										alert('Your snack will be an Apple.');
    1245 									}
    1246 								},
    1247 							   {
    1248 								   xtype: 'menuseparator'
    1249 							   },
    1250 								{
    1251 									itemId:'banana',
    1252 									icon: './themes/common/images/skin/exclamation.png',
    1253 									text: 'Banana',
    1254 									handler: function(sender, data) {
    1255 										alert('Your snack will be a Banana.');
    1256 									}
    1257 								}, {
    1258 									itemId:'cherry',
    1259 									icon: './themes/common/images/skin/exclamation.png',
    1260 									text: 'Cherries',
    1261 									handler: function(sender, data) {
    1262 										alert('Your snack will be Cherries.');
    1263 									}
    1264 								}
    1265 							]
    1266 						}
    1267 					},
    1268 					'-', // another way to add a menu separator
    1269 					{
    1270 						itemId:'cupcake',
    1271 						icon: './themes/common/images/skin/exclamation.png',
    1272 						text: 'Cupcake',
    1273 						handler: function(sender, data) {
    1274 							alert('Your snack will be a Cupcake.');
    1275 						}
    1276 					},
    1277 					{
    1278 						itemId:'chips',
    1279 						icon: './themes/common/images/skin/exclamation.png',
    1280 						text: 'Potato Chips',
    1281 						handler: function(sender, data) {
    1282 							alert('Your snack will be a Potato Chips.');
    1283 						}
    1284 					}
    1285 				]
    1286 			}
    1287 		}
    1288 	]
    1289 });
    1290 */
    1291
    1292 /**
    1293 	Inserts new menus into the Widget Chrome. Menus are added to the same area as existing menus.
    1294 	@name insertHeaderMenus
    1295 	@methodOf OWF.Chrome
    1296
    1297 	@param {Object} cfg config object see below for properties
    1298 	@param {Number} [cfg.pos=0] 0-based index of where menus will be added, among any pre-existing menus.
    1299 	@param {Object[]} cfg.items an array of menu configurations to add to the chrome.  See example for menu configs
    1300 	@param {String} cfg.items[*].parentId itemId is the itemId of the menu to which this configuration should be added as a sub-menu.  If omitted, the configuration will be added as a main menu on the menu toolbar.
    1301 	@param {String} cfg.items[*].itemId itemId is a unique id among all menus that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.  If itemId is not unique this may result in duplicate menus which may not be able to be removed properly.
    1302 	@param {String} cfg.items[*].icon This property defines the URL of the image to be used for the menu.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    1303 	@param {String} cfg.items[*].text This property defines text to appear alongside the menu.  This property is only used if the xtype is ‘menu.’  ‘widgettool’ will not show text.
    1304 	@param {Object} cfg.items[*].menu menu configuration object
    1305 	@param {Object[]} cfg.items[*].menu.items an array of menu item configurations to add to the chrome.  See example for menu item configs
    1306 	@param {String} cfg.items[*].menu.items[*].itemId itemId is a unique id among all menu items that are added.  It is a required property.  It is used for identification and defines the internal Eventing channel which is used to execute the handler function.
    1307 	@param {String} cfg.items[*].menu.items[*].xtype xtype is used to specify the type of menu item to add.  This attribute should be omitted unless specifying a menuseparator. Setting this value to "menuseparator" adds a separator bar to a menu, used to divide logical groups of menu items. If specified, only xtype should be specified.  See example below for usage.
    1308 	@param {String} cfg.items[*].menu.items[*].icon This property defines the URL of the image to be used for the menu item.  If the URL is a relative path, it will be relative to the /owf context.  This is useful if the desired image is hosted by the OWF web server.  Otherwise a fully qualified URL should be used.  If type is being used to determine the image, the icon property is optional
    1309 	@param {String} cfg.items[*].menu.items[*].text This property defines text to appear for the menu item.
    1310 	@param {Function} cfg.items[*].menu.items[*].handler The handler attribute defines a function to be executed when the menu item is clicked. This function is executed using Widget Eventing API from inside the widget.  The internal channel name used is the itemId attribute. This function's parameter list contains the standard parameters for an Eventing callback function.
    1311 	@param {Object} cfg.items[*].menu.items[*].menu sub-menu configuration object.  See example for sub-menu config.
    1312
    1313 	@example
    1314 OWF.Chrome.insertHeaderMenus({
    1315 		pos: 0,
    1316 		items: [{
    1317 		 itemId:'insertedMenu',
    1318 			icon: './themes/common/images/skin/exclamation.png',
    1319 			text: 'Inserted Menu',
    1320 			menu: {
    1321 				items: [
    1322 					{
    1323 						itemId:'insertedMenuItem1',
    1324 						icon: './themes/common/images/skin/exclamation.png',
    1325 						text: 'Inserted Menu Item 1',
    1326 						handler: function(sender, data) {
    1327 							alert('You clicked the Inserted Menu menu item.');
    1328 						}
    1329 					},
    1330 					{
    1331 						xtype: 'menuseparator'
    1332 					},
    1333 					{
    1334 						itemId:'insertedMenuItem2',
    1335 						icon: './themes/common/images/skin/exclamation.png',
    1336 						text: 'Inserted Menu Item 2',
    1337 						handler: function(sender, data) {
    1338 							alert('You clicked the Inserted Menu menu item.');
    1339 						}
    1340 					},
    1341 					'-', // another way to add a menu separator
    1342 					{
    1343 						itemId:'insertedMenuItem3',
    1344 						icon: './themes/common/images/skin/exclamation.png',
    1345 						text: 'Inserted Menu Item 3',
    1346 						handler: function(sender, data) {
    1347 							alert('You clicked the Inserted Menu menu item.');
    1348 						}
    1349 					}
    1350 				]
    1351 			}
    1352 		}]
    1353 });
    1354 */
    1355
    1356 /**
    1357 	Removes existing menus on the Widget Chrome based on itemId.
    1358 	@name removeHeaderMenus
    1359 	@methodOf OWF.Chrome
    1360
    1361 	@param {Object} cfg config object see below for properties
    1362 	@param {Object[]} cfg.items an array of objects containing itemIds for the menus to remove from the chrome.
    1363 	  See example below for button configs
    1364
    1365 	@example
    1366 OWF.Chrome.removeHeaderMenus({
    1367 	items: [{
    1368 		itemId: 'regularMenu'
    1369 	}]
    1370 });
    1371 */
    1372
    1373 /**
    1374 	Lists all menus that have been added to the widget chrome.
    1375 	@name listHeaderMenus
    1376 	@methodOf OWF.Chrome
    1377
    1378 	@param {Object} cfg config object see below for properties
    1379 	@param {Function} cfg.callback The function which receives the results.
    1380
    1381 	@example
    1382 OWF.Chrome.listHeaderMenus({
    1383 	callback: function(msg) {
    1384 		//msg will always be a json string
    1385 		var res = Ozone.util.parseJson(msg);
    1386 		if (res.success) {
    1387 			for (var i = 0; i < res.items.length; i++) {
    1388 				// do something with the menus
    1389 			}
    1390 		}
    1391 	}
    1392 });
    1393 	*/
    1394
    1395 /**
    1396   *
    1397   *	@name getTitle
    1398   * @methodOf OWF.Chrome
    1399   * @description Gets the Widget's Title from the Chrome
    1400   * @param {Object} cfg config object see below for properties
    1401   * @param {Function} cfg.callback The function which receives the results.
    1402   *
    1403   * @example
    1404   *    OWF.Chrome.getTitle({
    1405   *     callback: function(msg) {
    1406   *         //msg will always be a json string
    1407   *         var res = Ozone.util.parseJson(msg);
    1408   *         if (res.success) {
    1409   *
    1410   *           //do something with title
    1411   *           // res.title
    1412   *         }
    1413   *     }
    1414   *   });
    1415   */
    1416
    1417 /**
    1418   *	@name setTitle
    1419   * @methodOf OWF.Chrome
    1420   * @description Sets the Widget's Title in the Chrome
    1421   * @param {Object} cfg config object see below for properties
    1422   * @param {String} cfg.title The string which will replace the widget title
    1423   * @param {Function} cfg.callback The function which receives the results.
    1424   *
    1425   * @example
    1426   *    OWF.Chrome.setTitle({
    1427   *     title: 'new title',
    1428   *     callback: function(msg) {
    1429   *         //msg will always be a json string
    1430   *         var res = Ozone.util.parseJson(msg);
    1431   *         if (res.success) {
    1432   *           //get title back for confirmation
    1433   *           // res.title
    1434   *
    1435   *         }
    1436   *     }
    1437   *   });
    1438   */
    1439
    1440 // --------------------------------------------------------------------------------------------------
    1441 // ------------------- Preferences ------------------------------------------------------------------
    1442 // --------------------------------------------------------------------------------------------------
    1443
    1444 /**
    1445 	Get the url for the Preference Server
    1446 	@name getUrl
    1447 	@methodOf OWF.Preferences
    1448
    1449 	@returns {String} url
    1450  */
    1451
    1452 /**
    1453 	Sets the url for the Preference Server
    1454 	@name setUrl
    1455 	@methodOf OWF.Preferences
    1456
    1457 	@param {String} url
    1458 	@returns void
    1459  */
    1460
    1461 /**
    1462  * @name getDashboard
    1463  * @methodOf OWF.Preferences
    1464  * @description Gets the dashboard with the specified id
    1465  * @param {Object} cfg config object see below for properties
    1466  * @param {String} cfg.dashboardId Unigue dashbard identifier
    1467  * @param {Function} cfg.onSuccess Callback function to capture the success result. Callback parameter is json representation of a dashboard.
    1468  * This method will be passed the dashboard object which has the following properties:<br>
    1469  * <br>
    1470  *     {Boolean} alteredByAdmin: true if altered by an administrator<br>
    1471  *     {Date} createdDate: date dashboard was created<br>
    1472  *     {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    1473  *     {Boolean} isdefault: true if this is a default dashboard<br>
    1474  *     {String} name: name of dashboard<br>
    1475  *     {Object} user: the dashoard owner.  Has the following properties:<br>
    1476  *         {String} userId: unique user identifier<br>
    1477  *     {Object} createdBy: dashboard creator.  Has the following properties:<br>
    1478  *         {String} userId: unique user identifier<br>
    1479  *         {String} userRealName: user's name<br>
    1480  *     {Date} editedDate: date dashboard was last edited<br>
    1481  *     {Array} groups:  groups dashboard is assigned to<br>
    1482  *     {String} description: description of dashboard<br>
    1483  *     {String} guid: uniqued dashboard identifier<br>
    1484  *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    1485  *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    1486  *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    1487  *     Panes can have the following parameters:<br>
    1488  *     <ul style="list-style-type:none">
    1489  *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    1490  *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    1491  *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    1492  *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    1493  *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    1494  *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    1495  *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    1496  *        <ul style="list-style-type:none">
    1497  *           <li>{String} type: vbox|hbox</li>
    1498  *           <li>{String} align: stretch</li>
    1499  *        </ul>
    1500  *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    1501  *        <ul style="list-style-type:none">
    1502  *           <li>{String} widgetGuid: unique widget identifier</li>
    1503  *           <li>{Number} width: width of widget in pixels</li>
    1504  *           <li>{Number} zIndex: in pixels</li>
    1505  *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    1506  *           <li>{Boolean} pinned: true if widget is pinned open</li>
    1507  *           <li>{String} buttonId: identifier of button that opens widget</li>
    1508  *           <li>{Number} height: height of widget in pixels</li>
    1509  *           <li>{Number} columnPos: position of widget in a column</li>
    1510  *           <li>{String} name: widget name</li>
    1511  *           <li>{Number} statePosition</li>
    1512  *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    1513  *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    1514  *           <li>{Boolean} minimized: true if widget is minimized</li>
    1515  *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    1516  *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    1517  *           <li>{Number} y: y-axis position in pixels</li>
    1518  *           <li>{Number} x: x-axis position in pixels</li>
    1519  *           <li>{Boolean} maximized: true if widget is maximized</li>
    1520  *        </ul>
    1521  *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    1522  *     </ul>
    1523  * <br>
    1524  * @param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    1525  * @example
    1526  *
    1527  * var onSuccess = function(dashboard) {
    1528  *     alert(dashboard.name);
    1529  * };
    1530  *
    1531  * var onFailure = function(error) {
    1532      *     alert(error);
    1533  * };
    1534  *
    1535  * Ozone.Preferences.getDashboard({
    1536  *     dashboardId:'917b4cd0-ecbd-410b-afd9-42d150c26426',
    1537  *     onSuccess:onSuccess,
    1538  *     onFailure:onFailure
    1539  * });
    1540  */
    1541
    1542
    1543  /**
    1544    * @name getDefaultDashboard
    1545    * @methodOf OWF.Preferences
    1546    * @description Gets the user's default dashboard
    1547    * @param {Object} cfg config object see below for properties
    1548    * @param {Function} cfg.onSuccess Callback function to capture the success result. Callback parameter is json representation of a Dashboard.
    1549    * This method will be passed the dashboard object which has the following properties:<br>
    1550    * <br>
    1551    *     {Boolean} alteredByAdmin: true if altered by an administrator<br>
    1552    *     {Date} createdDate: date dashboard was created<br>
    1553    *     {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    1554    *     {Boolean} isdefault: true if this is a default dashboard<br>
    1555    *     {String} name: name of dashboard<br>
    1556    *     {Object} user: the dashoard owner.  Has the following properties:<br>
    1557    *         {String} userId: unique user identifier<br>
    1558    *     {Object} createdBy: dashboard creator.  Has the following properties:<br>
    1559    *         {String} userId: unique user identifier<br>
    1560    *         {String} userRealName: user's name<br>
    1561    *     {Date} editedDate: date dashboard was last edited<br>
    1562    *     {Array} groups:  groups dashboard is assigned to<br>
    1563    *     {String} description: description of dashboard<br>
    1564    *     {String} guid: uniqued dashboard identifier<br>
    1565    *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    1566    *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    1567    *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    1568    *     Panes can have the following parameters:<br>
    1569    *     <ul style="list-style-type:none">
    1570    *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    1571    *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    1572    *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    1573    *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    1574    *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    1575    *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    1576    *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    1577    *        <ul style="list-style-type:none">
    1578    *           <li>{String} type: vbox|hbox</li>
    1579    *           <li>{String} align: stretch</li>
    1580    *        </ul>
    1581    *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    1582    *        <ul style="list-style-type:none">
    1583    *           <li>{String} widgetGuid: unique widget identifier</li>
    1584    *           <li>{Number} width: width of widget in pixels</li>
    1585    *           <li>{Number} zIndex: in pixels</li>
    1586    *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    1587    *           <li>{Boolean} pinned: true if widget is pinned open</li>
    1588    *           <li>{String} buttonId: identifier of button that opens widget</li>
    1589    *           <li>{Number} height: height of widget in pixels</li>
    1590    *           <li>{Number} columnPos: position of widget in a column</li>
    1591    *           <li>{String} name: widget name</li>
    1592    *           <li>{Number} statePosition</li>
    1593    *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    1594    *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    1595    *           <li>{Boolean} minimized: true if widget is minimized</li>
    1596    *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    1597    *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    1598    *           <li>{Number} y: y-axis position in pixels</li>
    1599    *           <li>{Number} x: x-axis position in pixels</li>
    1600    *           <li>{Boolean} maximized: true if widget is maximized</li>
    1601    *        </ul>
    1602    *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    1603    *     </ul>
    1604    * <br>
    1605    * @param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    1606    * @example
    1607    *
    1608    * var onSuccess = function(dashboard) {
    1609    *     alert(dashboard.name);
    1610    * };
    1611    *
    1612    * var onFailure = function(error) {
    1613        *     alert(error);
    1614    * };
    1615    *
    1616    * Ozone.Preferences.getDashboard({
    1617    *     onSuccess:onSuccess,
    1618    *     onFailure:onFailure
    1619    * });
    1620    */
    1621 /**
    1622  * @name setDefaultDashboard
    1623  * @methodOf OWF.Preferences
    1624  * @description Sets the user's default dashboard
    1625  * @param {Object} cfg config object see below for properties
    1626  * @param {String} cfg.dashboardId Unigue dashbard identifier
    1627  * @param {Boolean} cfg.isDefault true to set as default dashboard
    1628  * @param {Function} cfg.onSuccess Callback function to capture the success result. Callback parameter is json representation of a Dashboard.
    1629  * This method will be passed the dashboard object which has the following properties:<br>
    1630  * <br>
    1631  *     {Boolean} alteredByAdmin: true if altered by an administrator<br>
    1632  *     {Date} createdDate: date dashboard was created<br>
    1633  *     {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    1634  *     {Boolean} isdefault: true if this is a default dashboard<br>
    1635  *     {String} name: name of dashboard<br>
    1636  *     {Object} user: the dashoard owner.  Has the following properties:<br>
    1637  *         {String} userId: unique user identifier<br>
    1638  *     {Object} createdBy: dashboard creator.  Has the following properties:<br>
    1639  *         {String} userId: unique user identifier<br>
    1640  *         {String} userRealName: user's name<br>
    1641  *     {Date} editedDate: date dashboard was last edited<br>
    1642  *     {Array} groups:  groups dashboard is assigned to<br>
    1643  *     {String} description: description of dashboard<br>
    1644  *     {String} guid: uniqued dashboard identifier<br>
    1645  *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    1646  *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    1647  *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    1648  *     Panes can have the following parameters:<br>
    1649  *     <ul style="list-style-type:none">
    1650  *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    1651  *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    1652  *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    1653  *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    1654  *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    1655  *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    1656  *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    1657  *        <ul style="list-style-type:none">
    1658  *           <li>{String} type: vbox|hbox</li>
    1659  *           <li>{String} align: stretch</li>
    1660  *        </ul>
    1661  *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    1662  *        <ul style="list-style-type:none">
    1663  *           <li>{String} widgetGuid: unique widget identifier</li>
    1664  *           <li>{Number} width: width of widget in pixels</li>
    1665  *           <li>{Number} zIndex: in pixels</li>
    1666  *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    1667  *           <li>{Boolean} pinned: true if widget is pinned open</li>
    1668  *           <li>{String} buttonId: identifier of button that opens widget</li>
    1669  *           <li>{Number} height: height of widget in pixels</li>
    1670  *           <li>{Number} columnPos: position of widget in a column</li>
    1671  *           <li>{String} name: widget name</li>
    1672  *           <li>{Number} statePosition</li>
    1673  *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    1674  *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    1675  *           <li>{Boolean} minimized: true if widget is minimized</li>
    1676  *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    1677  *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    1678  *           <li>{Number} y: y-axis position in pixels</li>
    1679  *           <li>{Number} x: x-axis position in pixels</li>
    1680  *           <li>{Boolean} maximized: true if widget is maximized</li>
    1681  *        </ul>
    1682  *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    1683  *     </ul>
    1684  * <br>
    1685  * @param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    1686  * @example
    1687  *
    1688  * var onSuccess = function(dashboard) {
    1689  *     alert(dashboard.name);
    1690  * };
    1691  *
    1692  * var onFailure = function(error) {
    1693  *     alert(error);
    1694  * };
    1695  *
    1696  * OWF.Preferences.setDefaultDashboard({
    1697  *     dashboardId:'917b4cd0-ecbd-410b-afd9-42d150c26426',
    1698  *     isDefault:true,
    1699  *     onSuccess:onSuccess,
    1700  *     onFailure:onFailure
    1701  * });
    1702  */
    1703
    1704 /**
    1705  * @name createOrUpdateDashboard
    1706  * @methodOf OWF.Preferences
    1707  * @description Saves changes to a new or existing dashboard
    1708  * @param {Object} cfg config object see below for properties
    1709  * @param {Object} cfg.json The encoded JSON object representing the dashboard.
    1710  * The dashboard object has the following properties:<br>
    1711  * <br>
    1712  *     {Boolean} alteredByAdmin: true if altered by an administrator<br>
    1713  *     {Date} createdDate: date dashboard was created<br>
    1714  *     {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    1715  *     {String} layout: layout of dashboard<br>
    1716  *     {Boolean} isdefault: true if this is a default dashboard<br>
    1717  *     {String} name: name of dashboard<br>
    1718  *     {Number} columnCount: number of columns if dashboard is a portal type<br>
    1719  *     {Object} user: the dashoard owner.  Has the following properties:<br>
    1720  *         {String} userId: unique user identifier<br>
    1721  *     {List} EDashboardLayoutList: list of dashboard types<br>
    1722  *     {String} defaultSettings: JSON string of default settings which varies by dashboard type<br>
    1723  *     {Object} createdBy: dashboard creator.  Has the following properties:<br>
    1724  *         {String} userId: unique user identifier<br>
    1725  *         {String} userRealName: user's name<br>
    1726  *     {Date} editedDate: date dashboard was last edited<br>
    1727  *     {Array} groups:  groups dashboard is assigned to<br>
    1728  *     {String} description: description of dashboard<br>
    1729  *     {String} guid: uniqued dashboard identifier<br>
    1730  *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    1731  *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    1732  *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    1733  *     Panes can have the following parameters:<br>
    1734  *     <ul style="list-style-type:none">
    1735  *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    1736  *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    1737  *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    1738  *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    1739  *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    1740  *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    1741  *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    1742  *        <ul style="list-style-type:none">
    1743  *           <li>{String} type: vbox|hbox</li>
    1744  *           <li>{String} align: stretch</li>
    1745  *        </ul>
    1746  *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    1747  *        <ul style="list-style-type:none">
    1748  *           <li>{String} widgetGuid: unique widget identifier</li>
    1749  *           <li>{Number} width: width of widget in pixels</li>
    1750  *           <li>{Number} zIndex: in pixels</li>
    1751  *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    1752  *           <li>{Boolean} pinned: true if widget is pinned open</li>
    1753  *           <li>{String} buttonId: identifier of button that opens widget</li>
    1754  *           <li>{Number} height: height of widget in pixels</li>
    1755  *           <li>{Number} columnPos: position of widget in a column</li>
    1756  *           <li>{String} name: widget name</li>
    1757  *           <li>{Number} statePosition</li>
    1758  *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    1759  *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    1760  *           <li>{Boolean} minimized: true if widget is minimized</li>
    1761  *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    1762  *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    1763  *           <li>{Number} y: y-axis position in pixels</li>
    1764  *           <li>{Number} x: x-axis position in pixels</li>
    1765  *           <li>{Boolean} maximized: true if widget is maximized</li>
    1766  *        </ul>
    1767  *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    1768  *     </ul>
    1769  * <br>
    1770  * @param {Boolean} cfg.saveAsNew A Boolean indicating whether the entity being saved is new.
    1771  * @param {Function} cfg.onSuccess Callback function to capture the success result. Callback parameter is json representation of a Dashboard.
    1772  * This method will be passed the dashboard object which has the following properties:<br>
    1773  * <br>
    1774  *     {Boolean} alteredByAdmin: true if altered by an administrator<br>
    1775  *     {Date} createdDate: date dashboard was created<br>
    1776  *     {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    1777  *     {Boolean} isdefault: true if this is a default dashboard<br>
    1778  *     {String} name: name of dashboard<br>
    1779  *     {Object} user: the dashoard owner.  Has the following properties:<br>
    1780  *         {String} userId: unique user identifier<br>
    1781  *     {Object} createdBy: dashboard creator.  Has the following properties:<br>
    1782  *         {String} userId: unique user identifier<br>
    1783  *         {String} userRealName: user's name<br>
    1784  *     {Date} editedDate: date dashboard was last edited<br>
    1785  *     {Array} groups:  groups dashboard is assigned to<br>
    1786  *     {String} description: description of dashboard<br>
    1787  *     {String} guid: uniqued dashboard identifier<br>
    1788  *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    1789  *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    1790  *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    1791  *     Panes can have the following parameters:<br>
    1792  *     <ul style="list-style-type:none">
    1793  *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    1794  *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    1795  *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    1796  *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    1797  *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    1798  *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    1799  *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    1800  *        <ul style="list-style-type:none">
    1801  *           <li>{String} type: vbox|hbox</li>
    1802  *           <li>{String} align: stretch</li>
    1803  *        </ul>
    1804  *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    1805  *        <ul style="list-style-type:none">
    1806  *           <li>{String} widgetGuid: unique widget identifier</li>
    1807  *           <li>{Number} width: width of widget in pixels</li>
    1808  *           <li>{Number} zIndex: in pixels</li>
    1809  *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    1810  *           <li>{Boolean} pinned: true if widget is pinned open</li>
    1811  *           <li>{String} buttonId: identifier of button that opens widget</li>
    1812  *           <li>{Number} height: height of widget in pixels</li>
    1813  *           <li>{Number} columnPos: position of widget in a column</li>
    1814  *           <li>{String} name: widget name</li>
    1815  *           <li>{Number} statePosition</li>
    1816  *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    1817  *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    1818  *           <li>{Boolean} minimized: true if widget is minimized</li>
    1819  *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    1820  *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    1821  *           <li>{Number} y: y-axis position in pixels</li>
    1822  *           <li>{Number} x: x-axis position in pixels</li>
    1823  *           <li>{Boolean} maximized: true if widget is maximized</li>
    1824  *        </ul>
    1825  *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    1826  *     </ul>
    1827  * <br>
    1828  * @param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    1829  * @param {Boolean} [cfg.async] Async true or false defaults to true
    1830  * @example
    1831  *
    1832  * var onSuccess = function(dashboard) {
    1833  *   alert(dashboard.name);
    1834  * };
    1835  *
    1836  * var onFailure = function(error) {
    1837  *   alert(error);
    1838  * };
    1839  *
    1840  * var dashboard = {
    1841  *   alteredByAdmin: 'false',
    1842  *   createdDate: '04/18/2012 11:29 AM EDT',
    1843  *   isGroupDashboard: false,
    1844  *   isdefault: false,
    1845  *   locked: false,
    1846  *   name: 'My Dashboard',
    1847  *   user: {
    1848  *     userId: 'testAdmin1',
    1849  *   },
    1850  *   createdBy: {
    1851  *     userId: 'testAdmin1',
    1852  *     userRealName: 'Test Admin 1'
    1853  *   },
    1854  *   editedDate: '04/18/2012 11:29 AM EDT',
    1855  *   groups: [],
    1856  *   description: 'This is my dashboard',
    1857  *   guid: guid.util.guid(),
    1858  *   layoutConfig: {
    1859  *       xtype: "desktoppane",
    1860  *       flex: 1,
    1861  *       height: "100%",
    1862  *       items: [
    1863  *       ],
    1864  *       paneType: "desktoppane",
    1865  *       widgets: [{
    1866  *               widgetGuid: "ec5435cf-4021-4f2a-ba69-dde451d12551",
    1867  *               uniqueId: guid.util.guid(),
    1868  *               dashboardGuid: "6d7219cb-b485-ace5-946b-0affa1f227a3",
    1869  *               paneGuid: guid.util.guid(),
    1870  *               name: "Channel Listener",
    1871  *               active: false,
    1872  *               x: 50,
    1873  *               y: 66,
    1874  *               minimized: false,
    1875  *               maximized: false,
    1876  *               pinned: false,
    1877  *               collapsed: false,
    1878  *               columnPos: 0,
    1879  *               buttonId: null,
    1880  *               buttonOpened: false,
    1881  *               region: "none",
    1882  *               statePosition: 1,
    1883  *               intentConfig: null,
    1884  *               singleton: false,
    1885  *               floatingWidget: false,
    1886  *               background: false,
    1887  *               zIndex: 19050,
    1888  *               height: 440,
    1889  *               width: 540
    1890  *           }
    1891  *       ],
    1892  *       defaultSettings: {
    1893  *           widgetStates: {
    1894  *               "ec5435cf-4021-4f2a-ba69-dde451d12551": {
    1895  *                   x: 50,
    1896  *                   y: 66,
    1897  *                   height: 440,
    1898  *                   width: 540,
    1899  *                   timestamp: 1349809747336
    1900  *                }
    1901  *           }
    1902  *       }
    1903  *      }
    1904  * };
    1905  *
    1906  * OWF.Preferences.createOrUpdateDashboard({
    1907  *   json: dashboard,
    1908  *   saveAsNew: true,
    1909  *   onSuccess: onSuccess,
    1910  *   onFailure: onFailure,
    1911  *   async: true
    1912  * });
    1913  */
    1914
    1915 /**
    1916  * @name cloneDashboard
    1917  * @methodOf OWF.Preferences
    1918  * @description Copies an existing dashboard and saves it as new
    1919  * @param {Object} cfg config object see below for properties
    1920  * @param {Object} cfg.json The encoded JSON object representing the dashboard.
    1921  * The dashboard object has the following properties:<br>
    1922  * <br>
    1923  *     {Boolean} alteredByAdmin: true if altered by an administrator<br>
    1924  *     {Date} createdDate: date dashboard was created<br>
    1925  *     {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    1926  *     {Boolean} isdefault: true if this is a default dashboard<br>
    1927  *     {String} name: name of dashboard<br>
    1928  *     {Object} user: the dashoard owner.  Has the following properties:<br>
    1929  *         {String} userId: unique user identifier<br>
    1930  *     {Object} createdBy: dashboard creator.  Has the following properties:<br>
    1931  *         {String} userId: unique user identifier<br>
    1932  *         {String} userRealName: user's name<br>
    1933  *     {Date} editedDate: date dashboard was last edited<br>
    1934  *     {Array} groups:  groups dashboard is assigned to<br>
    1935  *     {String} description: description of dashboard<br>
    1936  *     {String} guid: uniqued dashboard identifier<br>
    1937  *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    1938  *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    1939  *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    1940  *     Panes can have the following parameters:<br>
    1941  *     <ul style="list-style-type:none">
    1942  *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    1943  *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    1944  *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    1945  *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    1946  *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    1947  *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    1948  *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    1949  *        <ul style="list-style-type:none">
    1950  *           <li>{String} type: vbox|hbox</li>
    1951  *           <li>{String} align: stretch</li>
    1952  *        </ul>
    1953  *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    1954  *        <ul style="list-style-type:none">
    1955  *           <li>{String} widgetGuid: unique widget identifier</li>
    1956  *           <li>{Number} width: width of widget in pixels</li>
    1957  *           <li>{Number} zIndex: in pixels</li>
    1958  *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    1959  *           <li>{Boolean} pinned: true if widget is pinned open</li>
    1960  *           <li>{String} buttonId: identifier of button that opens widget</li>
    1961  *           <li>{Number} height: height of widget in pixels</li>
    1962  *           <li>{Number} columnPos: position of widget in a column</li>
    1963  *           <li>{String} name: widget name</li>
    1964  *           <li>{Number} statePosition</li>
    1965  *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    1966  *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    1967  *           <li>{Boolean} minimized: true if widget is minimized</li>
    1968  *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    1969  *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    1970  *           <li>{Number} y: y-axis position in pixels</li>
    1971  *           <li>{Number} x: x-axis position in pixels</li>
    1972  *           <li>{Boolean} maximized: true if widget is maximized</li>
    1973  *        </ul>
    1974  *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    1975  *     </ul>
    1976  * <br>
    1977  * @param {Function} cfg.onSuccess Callback function to capture the success result. Callback parameter is json representation of a Dashboard.
    1978  * This method will be passed the dashboard object which has the following properties:<br>
    1979  * <br>
    1980  *     {Boolean} alteredByAdmin: true if altered by an administrator<br>
    1981  *     {Date} createdDate: date dashboard was created<br>
    1982  *     {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    1983  *     {Boolean} isdefault: true if this is a default dashboard<br>
    1984  *     {String} name: name of dashboard<br>
    1985  *     {Object} user: the dashoard owner.  Has the following properties:<br>
    1986  *         {String} userId: unique user identifier<br>
    1987  *     {Object} createdBy: dashboard creator.  Has the following properties:<br>
    1988  *         {String} userId: unique user identifier<br>
    1989  *         {String} userRealName: user's name<br>
    1990  *     {Date} editedDate: date dashboard was last edited<br>
    1991  *     {Array} groups:  groups dashboard is assigned to<br>
    1992  *     {String} description: description of dashboard<br>
    1993  *     {String} guid: uniqued dashboard identifier<br>
    1994  *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    1995  *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    1996  *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    1997  *     Panes can have the following parameters:<br>
    1998  *     <ul style="list-style-type:none">
    1999  *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    2000  *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    2001  *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    2002  *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    2003  *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    2004  *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    2005  *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    2006  *        <ul style="list-style-type:none">
    2007  *           <li>{String} type: vbox|hbox</li>
    2008  *           <li>{String} align: stretch</li>
    2009  *        </ul>
    2010  *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    2011  *        <ul style="list-style-type:none">
    2012  *           <li>{String} widgetGuid: unique widget identifier</li>
    2013  *           <li>{Number} width: width of widget in pixels</li>
    2014  *           <li>{Number} zIndex: in pixels</li>
    2015  *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    2016  *           <li>{Boolean} pinned: true if widget is pinned open</li>
    2017  *           <li>{String} buttonId: identifier of button that opens widget</li>
    2018  *           <li>{Number} height: height of widget in pixels</li>
    2019  *           <li>{Number} columnPos: position of widget in a column</li>
    2020  *           <li>{String} name: widget name</li>
    2021  *           <li>{Number} statePosition</li>
    2022  *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    2023  *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    2024  *           <li>{Boolean} minimized: true if widget is minimized</li>
    2025  *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    2026  *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    2027  *           <li>{Number} y: y-axis position in pixels</li>
    2028  *           <li>{Number} x: x-axis position in pixels</li>
    2029  *           <li>{Boolean} maximized: true if widget is maximized</li>
    2030  *        </ul>
    2031  *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    2032  *     </ul>
    2033  * <br>
    2034  * @param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    2035  * @example
    2036  *
    2037  * var onSuccess = function(dashboard) {
    2038  *   alert(dashboard.name);
    2039  * };
    2040  *
    2041  * var onFailure = function(error) {
    2042  *   alert(error);
    2043  * };
    2044  *
    2045  * var dashboard = {
    2046  *   alteredByAdmin: 'false',
    2047  *   createdDate: '04/18/2012 11:29 AM EDT',
    2048  *   isGroupDashboard: false,
    2049  *   isdefault: false,
    2050  *   name: 'My Dashboard',
    2051  *   user: {
    2052  *     userId: 'testAdmin1',
    2053  *   },
    2054  *   createdBy: {
    2055  *     userId: 'testAdmin1',
    2056  *     userRealName: 'Test Admin 1'
    2057  *   },
    2058  *   editedDate: '04/18/2012 11:29 AM EDT',
    2059  *   groups: [],
    2060  *   description: 'This is my dashboard',
    2061  *   guid: guid.util.guid(),
    2062  * };
    2063  *
    2064  * OWF.Preferences.cloneDashboard({
    2065  *   json: dashboard,
    2066  *   onSuccess: onSuccess,
    2067  *   onFailure: onFailure
    2068  * });
    2069  */
    2070
    2071
    2072 /**
    2073 	@description Saves changes to existing dashboards
    2074 	@name updateAndDeleteDashboards
    2075 	@methodOf OWF.Preferences
    2076
    2077 	@param {Object} cfg config object see below for properties
    2078 	@param {Array} cfg.viewsToUpdate array of JSON objects containing the view guid and data to be updated
    2079 	@param {Array} cfg.viewGuidsToDelete array of guids of views to be deleted
    2080 	@param {Boolean} cfg.updateOrder flag to update order
    2081 	@param {Function} cfg.onSuccess callback function to capture the success result
    2082 	@param {Function} [cfg.onFailure] callback to execute if there is an error (optional, a default alert provided)
    2083  */
    2084
    2085 /**
    2086  * @name deleteDashboard
    2087  * @methodOf OWF.Preferences
    2088  * @description Deletes the dashboard with the specified id
    2089  * @param {Object} cfg config object see below for properties
    2090  * @param {String} cfg.dashboardId Unigue dashbard identifier
    2091  * @param {Function} cfg.onSuccess Callback function to capture the success result. Callback parameter is json representation of a Dashboard.
    2092  * This method will be passed the dashboard object which has the following properties:<br>
    2093  * <br>
    2094  *     {Boolean} alteredByAdmin: true if altered by an administrator<br>
    2095  *     {Date} createdDate: date dashboard was created<br>
    2096  *     {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    2097  *     {Boolean} isdefault: true if this is a default dashboard<br>
    2098  *     {String} name: name of dashboard<br>
    2099  *     {Object} user: the dashoard owner.  Has the following properties:<br>
    2100  *         {String} userId: unique user identifier<br>
    2101  *     {Object} createdBy: dashboard creator.  Has the following properties:<br>
    2102  *         {String} userId: unique user identifier<br>
    2103  *         {String} userRealName: user's name<br>
    2104  *     {Date} editedDate: date dashboard was last edited<br>
    2105  *     {Array} groups:  groups dashboard is assigned to<br>
    2106  *     {String} description: description of dashboard<br>
    2107  *     {String} guid: uniqued dashboard identifier<br>
    2108  *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    2109  *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    2110  *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    2111  *     Panes can have the following parameters:<br>
    2112  *     <ul style="list-style-type:none">
    2113  *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    2114  *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    2115  *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    2116  *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    2117  *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    2118  *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    2119  *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    2120  *        <ul style="list-style-type:none">
    2121  *           <li>{String} type: vbox|hbox</li>
    2122  *           <li>{String} align: stretch</li>
    2123  *        </ul>
    2124  *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    2125  *        <ul style="list-style-type:none">
    2126  *           <li>{String} widgetGuid: unique widget identifier</li>
    2127  *           <li>{Number} width: width of widget in pixels</li>
    2128  *           <li>{Number} zIndex: in pixels</li>
    2129  *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    2130  *           <li>{Boolean} pinned: true if widget is pinned open</li>
    2131  *           <li>{String} buttonId: identifier of button that opens widget</li>
    2132  *           <li>{Number} height: height of widget in pixels</li>
    2133  *           <li>{Number} columnPos: position of widget in a column</li>
    2134  *           <li>{String} name: widget name</li>
    2135  *           <li>{Number} statePosition</li>
    2136  *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    2137  *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    2138  *           <li>{Boolean} minimized: true if widget is minimized</li>
    2139  *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    2140  *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    2141  *           <li>{Number} y: y-axis position in pixels</li>
    2142  *           <li>{Number} x: x-axis position in pixels</li>
    2143  *           <li>{Boolean} maximized: true if widget is maximized</li>
    2144  *        </ul>
    2145  *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    2146  *     </ul>
    2147  * <br>
    2148  * @param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    2149  * @example
    2150  *
    2151  * var onSuccess = function(dashboard) {
    2152  *     alert(dashboard.name);
    2153  * };
    2154  *
    2155  * var onFailure = function(error) {
    2156      *     alert(error);
    2157  * };
    2158  *
    2159  * OWF.Preferences.deleteDashboard({
    2160  *     dashboardId:'917b4cd0-ecbd-410b-afd9-42d150c26426',
    2161  *     onSuccess:onSuccess,
    2162  *     onFailure:onFailure
    2163  * });
    2164  */
    2165
    2166 /**
    2167  * @name findDashboards
    2168  * @methodOf OWF.Preferences
    2169  * @description Returns all dashboards for the logged in user.
    2170  * @param {Object} cfg config object see below for properties
    2171  * @param {Function} cfg.onSuccess Callback function to capture the success result.
    2172  * This method is passed an object having the following properties:<br>
    2173  * <br>
    2174  *     {Boolean} success: true if dashboards found<br>
    2175  *     {Number} results: number of dashboards found<br>
    2176  *     {Array} data: array of dashboards objects found.  Dashboard object has the following properties:<br>
    2177  *     <br>
    2178  *         {Boolean} alteredByAdmin: true if altered by an administrator<br>
    2179  *         {Date} createdDate: date dashboard was created<br>
    2180  *         {Boolean} isGroupDashboard: true if dashboard is a group dashboard<br>
    2181  *         {Boolean} isdefault: true if this is a default dashboard<br>
    2182  *         {String} name: name of dashboard<br>
    2183  *         {Object} user: the dashoard owner.  Has the following properties:<br>
    2184  *             {String} userId: unique user identifier<br>
    2185  *         {Object} createdBy: dashboard creator.  Has the following properties:<br>
    2186  *             {String} userId: unique user identifier<br>
    2187  *             {String} userRealName: user's name<br>
    2188  *         {Date} editedDate: date dashboard was last edited<br>
    2189  *         {Array} groups:  groups dashboard is assigned to<br>
    2190  *         {String} description: description of dashboard<br>
    2191  *         {String} guid: uniqued dashboard identifier<br>
    2192  *     {String} layoutConfig: Holds the various containers and panes on a dashboard and the widgets inside of the panes, including the widget states.
    2193  *     This parameter provides an EXT JS style configuration used to layout the supported pane types in an OWF dashboard along. Each
    2194  *     internal definition can hold nested panes in an items array, widgets in a widgets array, and default values for those widgets in a defaultValues array.
    2195  *     Panes can have the following parameters:<br>
    2196  *     <ul style="list-style-type:none">
    2197  *        <li>{String} xtype: container|accordionpane|desktoppane|fitpane|portalpane|tabbedpane|dashboardsplitter</li>
    2198  *        <li>{Number} flex: 1 if for a pane; 3 for a container<li>
    2199  *        <li>{String} htmlText: in pixels (e.g., 300px) or percent (e.g., 100%) or "variable"; valid if nested in a horizontally/vertically split pane</li>
    2200  *        <li>{String} cls: left|right if nested in a horizontally split pane; top|bottom if nested in a vertically split pane; vbox|hbox if xtype is container</li>
    2201  *        <li>{Array} items: an array of 2 nested pane configurations along with a possible dashboardspliiter for vbox and hbox containers; empty otherwise</li>
    2202  *        <li>{String} paneType: accordionpane|desktoppane|fitpane|portalpane|tabbedpane; valid if xtype is not container</li>
    2203  *        <li>{Array} layout: valid only for container xtype.  Includes the following elements:</li>
    2204  *        <ul style="list-style-type:none">
    2205  *           <li>{String} type: vbox|hbox</li>
    2206  *           <li>{String} align: stretch</li>
    2207  *        </ul>
    2208  *        <li>{Array} widgets: array of widget state objects.  Each has the following properties:</li>
    2209  *        <ul style="list-style-type:none">
    2210  *           <li>{String} widgetGuid: unique widget identifier</li>
    2211  *           <li>{Number} width: width of widget in pixels</li>
    2212  *           <li>{Number} zIndex: in pixels</li>
    2213  *           <li>{String} region: containing region on dashboard.  Dashboard type specific.</li>
    2214  *           <li>{Boolean} pinned: true if widget is pinned open</li>
    2215  *           <li>{String} buttonId: identifier of button that opens widget</li>
    2216  *           <li>{Number} height: height of widget in pixels</li>
    2217  *           <li>{Number} columnPos: position of widget in a column</li>
    2218  *           <li>{String} name: widget name</li>
    2219  *           <li>{Number} statePosition</li>
    2220  *           <li>{Boolean} active: true if this widget is the active (has focus) widget</li>
    2221  *           <li>{String} uniqueId: unique widget identifier on dashboard</li>
    2222  *           <li>{Boolean} minimized: true if widget is minimized</li>
    2223  *           <li>{Boolean} buttonOpened: true if button launched widget is opened</li>
    2224  *           <li>{Boolean} collapsed: true if widget is collapsed</li>
    2225  *           <li>{Number} y: y-axis position in pixels</li>
    2226  *           <li>{Number} x: x-axis position in pixels</li>
    2227  *           <li>{Boolean} maximized: true if widget is maximized</li>
    2228  *        </ul>
    2229  *        <li>{String} defaultSettings: JSON string of default settings which varies by pane type; not valid for containers</li>
    2230  *     </ul>
    2231  *     <br>
    2232  * <br>
    2233  * @param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    2234  * @example
    2235  *
    2236  * var onSuccess = function(obj) {
    2237  *     alert(obj.results);
    2238  *     if (obj.results > 0) {
    2239  *         for (var i = 0; i < obj.results; i++) {
    2240  *             alert(obj.data[i].name);
    2241  *         }
    2242  *     }
    2243  * };
    2244  *
    2245  * var onFailure = function(error) {
    2246  *     alert(error);
    2247  * };
    2248  *
    2249  * OWF.Preferences.findDashboards({
    2250  *     onSuccess:onSuccess,
    2251  *     onFailure:onFailure
    2252  * });
    2253  */
    2254
    2255 /**
    2256  * @name findDashboardsByType
    2257  * @methodOf OWF.Preferences
    2258  * @deprecated Deprecated starting with OWF 7. Dashboards no longer have a specific type. This function is stubbed
    2259  * to return success with 0 results until removal.
    2260  * @description Returns all dashboards for the logged in user filtered by the type of dashboard.
    2261  * @param {Object} cfg config object see below for properties
    2262  * @param {String} cfg.type A string representing the type of dashboard. If using built in dashboard types, this would include desktop, tabbed, portal, and accordion.
    2263  * @param {Function} cfg.onSuccess Callback function to capture the success result.
    2264  * This method is passed an object having the following properties:<br>
    2265  * <br>
    2266  *     {Boolean} success: true if dashboards found<br>
    2267  *     {Number} results: number of dashboards found<br>
    2268  *     {Array} data: an empty array<br>
    2269  *
    2270  * <br>
    2271  * @param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    2272  * @example
    2273  *
    2274  * var onSuccess = function(obj) {
    2275  *     alert(obj.results);
    2276  *     if (obj.results > 0) {
    2277  *         for (var i = 0; i < obj.results; i++) {
    2278  *             alert(obj.data[i].name);
    2279  *         }
    2280  *     }
    2281  * };
    2282  *
    2283  * var onFailure = function(error) {
    2284  *     alert(error);
    2285  * };
    2286  *
    2287  * OWF.Preferences.findDashboardsByType({
    2288  *     type:'desktop',
    2289  *     onSuccess:onSuccess,
    2290  *     onFailure:onFailure
    2291  * });
    2292  */
    2293
    2294 /**
    2295 	@description Gets the widget with the specified id
    2296 	@name getWidget
    2297 	@methodOf OWF.Preferences
    2298
    2299 	@param {Object} cfg config object see below for properties
    2300 	@param {String} cfg.widgetId The unique identifier (normally a guid) for the widget.
    2301 	@param {Function} cfg.onSuccess Callback function to capture the success result. Callback is passed the following object as a parameter: {id:Number, namespace:String, value:Object, path:String}
    2302 	This method is passed an object having the following properties:<br>
    2303 	<br>
    2304 		{Number} id: database pk identifier<br>
    2305 		{String} namespace: "widget"<br>
    2306 		{Object} value: widget object having the following properties:<br>
    2307 		<br>
    2308 		    {Boolean} editable: true if widget can be edited<br>
    2309 		    {Boolean} visible: true if widget is visible<br>
    2310 		    {Number} position<br>
    2311 		    {String} userId: widget owner identifier<br>
    2312 		    {String} userRealName: widget owner name<br>
    2313 		    {String} namespace: widget name<br>
    2314 		    {String} url: url of widget application<br>
    2315 		    {String} headerIcon: url of widget header icon<br>
    2316 		    {String} image: url of widget image<br>
    2317 		    {String} smallIconUrl: url of widget's small icon<br>
    2318 		    {String} largeIconUrl: url of widget's large icon<br>
    2319 		    {Number} width: width of the widget in pixels<br>
    2320 		    {Number} height: height of the widget in pixels<br>
    2321 		    {Number} x: x-axis position<br>
    2322 		    {Number} y: y-axis position<br>
    2323 		    {Boolean} minimized: true if widget is minimized<br>
    2324 		    {Boolean} maximized: true if widget is maximized<br>
    2325 		    {String} widgetVersion: widget version<br>
    2326 		    {Array} tags: array of tag strings<br>
    2327 		    {Boolean} definitionVisible: true if definition is visible<br>
    2328 		    {Boolean} singleton: true if widget is a singleton<br>
    2329 		    {Boolean} background: true if widget runs in the background<br>
    2330 		    {Array} allRequired: array of all widgets required by this widget<br>
    2331 		    {Array} directRequired: array of all widgets directly required by this widget<br>
    2332 		    {Array} widgetTypes: array of widget types this widget belongs to<br>
    2333 		<br>
    2334 		{String} path: unnique widget identifier<br>
    2335 	<br>
    2336 	@param {Function} [cfg.onFailure] Callback to execute if there is an error (optional, a default alert provided). Callback parameter is an error string.
    2337
    2338 	@example
    2339 var onSuccess = function(obj) {
    2340 	if (obj.value) {
    2341 		alert(obj.value.namespace);
    2342 	}
    2343 };
    2344
    2345 var onFailure = function(error) {
    2346 	alert(error);
    2347 };
    2348
    2349 OWF.Preferences.getWidget({
    2350 	widgetId:'ea5435cf-4021-4f2a-ba69-dde451d12551',
    2351 	onSuccess:onSuccess,
    2352 	onFailure:onFailure
    2353 });
    2354 */
    2355
    2356 /**
    2357 	@description Gets all widgets for a given user.
    2358 	@name findWidgets
    2359 	@methodOf OWF.Preferences
    2360
    2361 	@param {Object} cfg config object see below for properties
    2362 	@param {Boolean} [cfg.userOnly] boolean flag that determines whether to only return widgets assigned to the user (excluding widgets to which the user only has access via their assigned groups)
    2363 	@param {Object} [cfg.searchParams] object containing search parameters
    2364 	@param {String} [cfg.searchParams.widgetName] name of widget '%' are wildcards
    2365 	@param {String} [cfg.searchParams.widgetNameExactMatch] true or false to match the name exactly. defaults to false
    2366 	@param {String} [cfg.searchParams.widgetVersion] version of widget '%' are wildcards
    2367 	@param {String} [cfg.searchParams.widgetGuid] guid of widget '%' are wildcards
    2368 	@param {Function} cfg.onSuccess callback function to capture the success result.
    2369 	This method is passed an array of objects having the following properties:<br>
    2370 	<br>
    2371 		{Number} id: database pk identifier<br>
    2372 		{String} namespace: "widget"<br>
    2373 		{Object} value: widget object having the following properties:<br>
    2374 		<br>
    2375 		    {Boolean} editable: true if widget can be edited<br>
    2376 		    {Boolean} visible: true if widget is visible<br>
    2377 		    {Number} position<br>
    2378 		    {String} userId: widget owner identifier<br>
    2379 		    {String} userRealName: widget owner name<br>
    2380 		    {String} namespace: widget name<br>
    2381 		    {String} url: url of widget application<br>
    2382 		    {String} headerIcon: url of widget header icon<br>
    2383 		    {String} image: url of widget image<br>
    2384 		    {String} smallIconUrl: url of widget's small icon<br>
    2385 		    {String} largeIconUrl: url of widget's large icon<br>
    2386 		    {Number} width: width of the widget in pixels<br>
    2387 		    {Number} height: height of the widget in pixels<br>
    2388 		    {Number} x: x-axis position<br>
    2389 		    {Number} y: y-axis position<br>
    2390 		    {Boolean} minimized: true if widget is minimized<br>
    2391 		    {Boolean} maximized: true if widget is maximized<br>
    2392 		    {String} widgetVersion: widget version<br>
    2393 		    {Array} tags: array of tag strings<br>
    2394 		    {Boolean} definitionVisible: true if definition is visible<br>
    2395 		    {Boolean} singleton: true if widget is a singleton<br>
    2396 		    {Boolean} background: true if widget runs in the background<br>
    2397 		    {Array} allRequired: array of all widgets required by this widget<br>
    2398 		    {Array} directRequired: array of all widgets directly required by this widget<br>
    2399 		    {Array} widgetTypes: array of widget types this widget belongs to<br>
    2400 		<br>
    2401 		{String} path: unnique widget identifier<br>
    2402 	<br>
    2403 	@param {Function} [cfg.onFailure] callback to execute if there is an error (optional, a default alert provided).  This callback is called with two parameters: a error message string, and optionally a status code
    2404
    2405 	@example
    2406 var onSuccess = function(widgets) {
    2407 	if (widgets.length > 0) {
    2408 		alert(widgets[0].value.namespace);
    2409 	}
    2410 };
    2411
    2412 var onFailure = function(error, status) {
    2413 	alert(error);
    2414 };
    2415
    2416 OWF.Preferences.findWidgets({
    2417 	onSuccess:onSuccess,
    2418 	onFailure:onFailure
    2419 });
    2420 */
    2421
    2422 /**
    2423 	@description Saves changes to existing widgets
    2424 	@name updateAndDeleteWidgets
    2425 	@methodOf OWF.Preferences
    2426
    2427 	@param {Object} cfg config object see below for properties
    2428 	@param {Array} cfg.widgetsToUpdate array of JSON objects containing the widget guid and data to be updated
    2429 	@param {Array} cfg.widgetGuidsToDelete array of guids of widgets to be deleted
    2430 	@param {Boolean} cfg.updateOrder flag to update order
    2431 	@param {Function} cfg.onSuccess callback function to capture the success result
    2432 	@param {Function} [cfg.onFailure] callback to execute if there is an error (optional, a default alert provided)
    2433  */
    2434
    2435 /**
    2436 	@description Retrieves the user preference for the provided name and namespace
    2437 	@name getUserPreference
    2438 	@methodOf OWF.Preferences
    2439
    2440 	@param {Object} cfg config object see below for properties
    2441 	@param {String} cfg.namespace The namespace of the requested user preference
    2442 	@param {String} cfg.name The name of the requested user preference
    2443 	@param {Function} cfg.onSuccess The function to be called if the user preference is successfully retrieved from
    2444 	the database.  This function takes a single argument, which is a JSON object.  If a preference is found, the
    2445 	complete JSON structure as shown below will be returned.  If it is not found this function be passed an empty JSON object.
    2446 	@example
    2447 The following is an example of a complete preference object passed to the onSuccess
    2448 function:
    2449 {
    2450 	"value":"true",
    2451 	"path":"militaryTime",
    2452 	"user":
    2453 	{
    2454 		"userId":"testAdmin1"
    2455 	},
    2456 	"namespace":"com.mycompany.AnnouncingClock"
    2457 }
    2458 		@param {Function} [cfg.onFailure] This parameter is optional. If this function is not specified a default error
    2459 		message will be displayed.This function is called if an error occurs on preference retrieval.  It is not
    2460 		called if the preference is simply missing.
    2461 		This function should accept two arguments:<br>
    2462 		<br>
    2463 		error: String<br>
    2464 		The error message<br>
    2465 		<br>
    2466 		Status: The numeric HTTP Status code (if applicable)<br>
    2467 		401: You are not authorized to access this entity.<br>
    2468 		500: An unexpected error occurred.<br>
    2469 		404: The user preference was not found.<br>
    2470 		400: The requested entity failed to pass validation.<br>
    2471
    2472 		@example
    2473 The following shows how to make a call to getUserPreference:
    2474 function onSuccess(pref){
    2475 	alert(Ozone.util.toString(pref.value));
    2476 }
    2477
    2478 function onFailure(error,status){
    2479 	alert('Error ' + error);
    2480 	alert(status);
    2481 }
    2482
    2483 // The following code calls getUserPreference with the above defined onSuccess and
    2484 // onFailure callbacks.
    2485 OWF.Preferences.getUserPreference({
    2486 	namespace:'com.company.widget',
    2487 	name:'First President',
    2488 	onSuccess:onSuccess,
    2489 	onFailure:onFailure
    2490 });
    2491 */
    2492
    2493 /**
    2494 	@description Checks for the existence of a user preference for a given namespace and name
    2495 	@name doesUserPreferenceExist
    2496 	@methodOf OWF.Preferences
    2497
    2498 	@param {Object} cfg config object see below for properties
    2499 	@param {String} cfg.namespace The namespace of the requested user
    2500 	@param {String} cfg.name The name of the requested user
    2501 	@param {Function} cfg.onSuccess The callback function that is called if a preference successfully return from the database.
    2502 	This method is passed an object having the following properties:<br>
    2503 	<br>
    2504 		{Number} statusCode: status code<br>
    2505 		{Boolean} preferenceExist: true if preference exists<br>
    2506 	<br>
    2507     @param {Function} [cfg.onFailure] The callback function that is called if there was
    2508     an error looking up the preference.  This function is <em>not</em> called
    2509     if the preference simply does not exist
    2510
    2511 	@example
    2512 var onSuccess = function(obj) {
    2513 	if (obj.statusCode = 200) {
    2514 		alert(obj.preferenceExist);
    2515 	}
    2516 };
    2517
    2518 var onFailure = function(error) {
    2519 	alert(error);
    2520 };
    2521
    2522 OWF.Preferences.doesUserPreferenceExist({
    2523 	namespace:'foo.bar.0',
    2524 	name:'test path entry 0',
    2525 	onSuccess:onSuccess,
    2526 	onFailure:onFailure
    2527 });
    2528 */
    2529
    2530 /**
    2531 	@description retrieves the current user logged into the system
    2532 	@name getCurrentUser
    2533 	@methodOf OWF.Preferences
    2534
    2535 	@param {Object} cfg config object see below for properties
    2536 	@param {Function} cfg.onSuccess The callback function that is called for a successful retrieval of the user logged in.
    2537 	This method is passed an object having the following properties:<br>
    2538 	<br>
    2539 		{String} currentUserName: user name<br>
    2540 		{String} currentUser: user real name<br>
    2541 		{Date} currentUserPrevLogin: previous login date<br>
    2542 		{Number} currentId: database pk index<br>
    2543 	<br>
    2544 	@param {Function} cfg.[onFailure] The callback function that is called when the system is unable to retrieve the current user logged in. Callback parameter is an error string.
    2545
    2546 	@example
    2547 var onSuccess = function(obj) {
    2548 	if (obj) {
    2549 		alert(obj.currentUser);
    2550 	}
    2551 };
    2552
    2553 var onFailure = function(error) {
    2554 	alert(error);
    2555 };
    2556
    2557 OWF.Preferences.getCurrentUser({
    2558 	onSuccess:onSuccess,
    2559 	onFailure:onFailure
    2560 });
    2561 */
    2562
    2563 /**
    2564 	@description For retrieving the OWF system server version
    2565 	@name getServerVersion
    2566 	@methodOf OWF.Preferences
    2567
    2568 	@param {Object} cfg config object see below for properties
    2569 	@param {Function} cfg.onSuccess The callback function that is called for successfully retrieving the server version of the OWF system.
    2570 	This method is passed an object having the following properties:<br>
    2571 	<br>
    2572 		{String} {serverVersion: server version<br>
    2573 	<br>
    2574 	@param {Function} [cfg.onFailure] The callback function that is called when the system fails to retrieve the server version of the OWF system. Callback parameter is an error string.
    2575 	@example
    2576
    2577 var onSuccess = function(obj) {
    2578 	if (obj) {
    2579 		alert(obj.serverVersion);
    2580 	}
    2581 };
    2582
    2583 var onFailure = function(error) {
    2584 	alert(error);
    2585 };
    2586
    2587 OWF.Preferences.getServerVersion({
    2588 	onSuccess:onSuccess,
    2589 	onFailure:onFailure
    2590 });
    2591 */
    2592
    2593 /**
    2594 	@description Creates or updates a user preference for the provided namespace and name.
    2595 	@name setUserPreference
    2596 	@methodOf OWF.Preferences
    2597
    2598 	@param {Object} cfg config object see below for properties
    2599 	@param {String} cfg.namespace  The namespace of the user preference
    2600 	@param {String} cfg.name The name of the user preference
    2601 	@param {String} cfg.value  The value of the user preference. The value can be any string including JSON.
    2602 	@param {Function} cfg.onSuccess The function to be called if the user preference is successfully updated in
    2603 	the database.
    2604
    2605 	@example
    2606 The following is an example of a complete preference object passed to the onSuccess function:
    2607 {
    2608 	"value":"true",
    2609 	"path":"militaryTime",
    2610 	"user": {
    2611 		"userId":"testAdmin1"
    2612 	},
    2613 	"namespace":"com.mycompany.AnnouncingClock"
    2614 }
    2615 		@param {Function} [cfg.onFailure] The function to be called if the user preference cannot be stored in the database.
    2616 		If this function is not specified a default error message will be displayed. This function is passed
    2617 		back the following parameters:<br>
    2618 		<br>
    2619 		error: String<br>
    2620 		The error message<br>
    2621 		<br>
    2622 		Status: The HTTP Status code<br>
    2623 		401: You are not authorized to access this entity.<br>
    2624 		500: An unexpected error occurred.<br>
    2625 		404: The requested entity was not found.<br>
    2626 		400: The requested entity failed to pass validation.<br>
    2627
    2628 		@example
    2629 function onSuccess(pref){
    2630 	alert(pref.value);
    2631 }
    2632
    2633 function onFailure(error,status){
    2634 	alert('Error ' + error);
    2635 	alert(status);
    2636 }
    2637
    2638 var text = 'George Washington';
    2639 OWF.Preferences.setUserPreference({
    2640 	namespace:'com.company.widget',
    2641 	name:'First President',
    2642 	value:text,
    2643 	onSuccess:onSuccess,
    2644 	onFailure:onFailure
    2645 });
    2646 */
    2647
    2648 /**
    2649 	Deletes a user preference with the provided namespace and name.
    2650 	@name deleteUserPreference
    2651 	@methodOf OWF.Preferences
    2652
    2653 	@param {Object} cfg config object see below for properties
    2654 	@param {String} cfg.namespace The namespace of the user preference
    2655 	@param {String} cfg.name The name of the user preference
    2656 	@param {Function} cfg.onSuccess The function to be called if the user preference is successfully deleted from the database.
    2657 	@example
    2658 The following is an example of a complete preference object passed to the onSuccess
    2659 function:
    2660
    2661 {
    2662 	"value":"true",
    2663 	"path":"militaryTime",
    2664 	"user":
    2665 	{
    2666 		"userId":"testAdmin1"
    2667 	},
    2668 	"namespace":"com.mycompany.AnnouncingClock"
    2669 }
    2670 		@param {Function} [cfg.onFailure] The function to be called if the user preference cannot be deleted from the
    2671 		database or if the preference does not exist. If this function is not specified a default error message will be
    2672 		displayed. This function is passed back the following parameters: <br>
    2673 		<br>
    2674 		error: String <br>
    2675 		The error message <br>
    2676 		<br>
    2677 		Status: The HTTP Status code<br>
    2678 		<br>
    2679 		401: You are not authorized to access this entity.<br>
    2680 		500: An unexpected error occurred.<br>
    2681 		404: The user preference was not found.<br>
    2682 		400: The requested entity failed to pass validation. <br>
    2683 		<br>
    2684 		@example
    2685 function onSuccess(pref){
    2686 	alert(pref.value);
    2687 }
    2688
    2689 function onFailure(error,status){
    2690 	alert('Error ' + error);
    2691 	alert(status);
    2692 }
    2693
    2694 OWF.Preferences.deleteUserPreference({
    2695 	namespace:'com.company.widget',
    2696 	name:'First President',
    2697 	onSuccess:onSuccess,
    2698 	onFailure:onFailure
    2699 });
    2700  */
    2701
    2702 /**
    2703 	This method informs a widget developer if their widget is running from the OWF or from a direct URL call.
    2704 	@name isRunningInOWF
    2705 	@methodOf OWF.Util
    2706
    2707 	@returns  boolean true if the widget is inside OWF, false otherwise.
    2708  */
    2709
    2710 /**
    2711  @name isInContainer
    2712  @methodOf OWF.Util
    2713  * @description This method informs a widget developer if their widget is running
    2714  * in a Container, like OWF
    2715  *
    2716  * @returns  boolean true if the widget is inside a container, false otherwise.
    2717  *
    2718  */
    2719
    2720 /**
    2721 	Returns a globally unique identifier (guid).
    2722 	@name guid
    2723 	@methodOf OWF.Util
    2724
    2725 	@returns  boolean true if the widget is inside OWF, false otherwise.
    2726  */
    2727
    2728 /**
    2729 	This method returns flash/flex dom element from dom.
    2730 	@name getFlashApp
    2731 	@methodOf OWF.Util
    2732
    2733 	@param {String} id id of the flex dom element
    2734
    2735 	@returns  flash/flex object from dom
    2736  */
    2737
    2738  /**
    2739 	Basic logging capability - meant to be called by other methods which transform or validate data.
    2740 	@name logMetric
    2741 	@methodOf OWF.Metrics
    2742 	@since OWF 3.8.0
    2743
    2744 	@param {String} userId
    2745 	@param {String} userName
    2746 	@param {String} metricSite Identifier, potentially URL, for source of metric - typically OWF instance
    2747 	@param {String} componentName
    2748 	@param {String} componentId
    2749 	@param {String} componentInstanceId
    2750 	@param {String} metricTypeId String describing metric - recommend package name construct
    2751 	@param {String} metricData Any additional data for metric - do any necessary validation appropriate to metricTypeId before sending through
    2752  */
    2753
    2754 /**
    2755  * @description Logs a set of metrics to the server all at once.  All
    2756  * metrics passed into a call to this function will be logged in a single
    2757  * HTTP request, instead of one request per metric
    2758  * @name logBatchMetrics
    2759  * @methodOf OWF.Metrics
    2760  * @since OWF 6.0
    2761  *
    2762  * @param {Array} metrics
    2763  * @param {String} metrics[*].userId
    2764  * @param {String} metrics[*].userName
    2765  * @param {Number} metrics[*].metricTime The time at which is metric was collected (in UNIX time)
    2766  * @param {String} metrics[*].site Identifier, potentially URL, for source of metric - typically OWF instance
    2767  * @param {String} metrics[*].component
    2768  * @param {String} metrics[*].componentId
    2769  * @param {String} metrics[*].instanceId
    2770  * @param {String} metrics[*].metricTypeId String describing metric - recommend package name construct
    2771  * @param {String} metrics[*].widgetData Any additional data for metric - do any necessary validation appropriate to metricTypeId before sending through
    2772  * @param {String} metrics[*].userAgent Should be set to the user-agent string of the browser
    2773  */
    2774
    2775 /**
    2776 	Log view of widget - see calls in dashboards.
    2777 	@name logWidgetRender
    2778 	@methodOf OWF.Metrics
    2779 	@since OWF 3.8.0
    2780
    2781 	@param {String} userId     - see Ozone.metrics.logMetric userId
    2782 	@param {String} userName   - see Ozone.metrics.logMetric userName
    2783 	@param {String} metricSite - see Ozone.metrics.logMetric metricSite
    2784 	@param {Object} widget
    2785  */
    2786
    2787 /**
    2788 	Get a logger by name, if the logger has not already been created it will be created.
    2789 	@name getLogger
    2790 	@methodOf OWF.Log
    2791 	@since OWF 3.8.0
    2792 	@param {String} loggerName
    2793  */
    2794
    2795 /**
    2796 	Enable/Disable logging for the OWF application.
    2797 	@name setEnabled
    2798 	@methodOf OWF.Log
    2799 	@since OWF 3.8.0
    2800 	@param {Boolean} enabled true will enable logging false will disable
    2801  */
    2802
    2803 /**
    2804 	Get OWF's default logger
    2805 	@name getDefaultLogger
    2806 	@methodOf OWF.Log
    2807 	@since OWF 3.8.0
    2808  */
    2809
    2810 /**
    2811 	Launch the log window pop-up, this will re-launch the window in the event it has been closed.
    2812 	@name launchPopupAppender
    2813 	@methodOf OWF.Log
    2814 	@since OWF 3.8.0
    2815  */
    2816
    2817 /**
    2818 	Gets the language that is currently being used by OWF.
    2819 	@name getLanguage
    2820 	@methodOf OWF.Lang
    2821
    2822 	@returns {String} Returns the ISO 639-1 language code for the language that is currently being used by OWF.
    2823  */
    2824