define(
        Container
            registerFinishFunction
            registerCancelFunction
            informFinish
            informCancel
        loadWidgetData
        getWidgetDataStorageURL
        cssCache
        widgetLoader
            insertWidgets
            loadWidgets
                informOnLoad
                locateTagAndRemove
                loadWidgetFiles
                locateWidgets
        saveWidgetData
        removeWidgetData
        changeWidgetTitle
        isOnDashboard
        nofityWidgetShown
        bindToHash
        createHashURL
        handleHashChange
            if (!$.isEmptyObject(sakai_widgets_config)) {
        getWidget
        getWidgetTitle
        getWidgetDescription
        insertOnLoadWidgets
        registerLazyLoading
        isRecursivelyEmbedded
define(

class Widgets
description Widget related convenience functions. This should only hold functions which are used across multiple pages, and does not constitute functionality related to a single area/page
namespace Widget related convenience functions


Container : {

class Container
description This will expose 2 funcions that can be called by widgets to inform the container that the widget has finished doing things in its settings mode. The container can then do whatever it needs to do according to the context it's in (f.e.: if in the personal dashboard environment, the container will want to render the view mode of that widget, in a site page edit context the container will want to insert the widget into the WYSIWYG editor). This will also allow the container to register 2 functions related to widget settings mode. First of all, the container can register a finish function, which will be executed when a widget notifies the container that it has successfully finished its settings mode. It can also register a cancel function, which will be executed when a widget notifies the container that its settings mode has been cancelled.
namespace Widget container functions


registerFinishFunction : function(callback) {

The container can use this to register a function to be executed when a widget notifies the container that its settings mode has been successfully completed.
param {Object} callback Function that needs to be executed when a widget notifies the container that its settings mode has been successfully completed.


registerCancelFunction : function(callback) {

The container can use this to register a function to be executed when a widget notifies the container that its settings mode has been cancelled.
param {Object} callback Function that needs to be executed when a widget notifies the container that its settings mode has been cancelled.


informFinish : function(tuid, widgetname) {

Function that can be called by a widget to notify the container that it has successfully completed its settings mode
param {Object} tuid Unique id (= id of the container this widget is in) of the widget
param {Object} widgetname Name of the widget as registered in the widget config file(e.g. sites, myprofile, video, ...)


informCancel : function(tuid, widgetname) {

Function that can be called by a widget to notify the container that its settings mode has been cancelled
param {Object} tuid Unique id (= id of the container this widget is in) of the widget
param {Object} widgetname Name of the widget as registered in the widget config file(e.g. sites, myprofile, video, ...)


loadWidgetData : function(id, callback, infinity) {

Load the preference settings or data for a widget
param {String} id The unique id of the widget
param {Function} callback Callback function that gets executed after the load is complete
param {Boolean} Determines whether or not the json tree descends down all the nodes. True by default.


getWidgetDataStorageURL : function(id) {

Get the URL from which a widget should load its widget data and to which it should store its widget data
param {String} id The unique id of the widget


cssCache : {},

Will be used for detecting widget declerations inside the page and load those widgets into the page


widgetLoader : {

name sakai.api.Widgets.widgetLoader


insertWidgets : function(id, showSettings, context, widgetData, widgetDataPassthrough, callback) {

Function that can be called by the container. This will looks for widget declarations within the specified container and will load the widgets in the requested mode (view - settings)
param {Object} id Id of the HTML container in which we want to look for widget declarations
param {Object} showSettings true : render the settings mode of the widget false : render the view mode of the widget


loadWidgets : function(id, showSettings, context, widgetData, widgetDataPassthrough, callback) {

Load the actual widgets
param {String} id The id of the widget
param {Boolean} showSettings true : render the settings mode of the widget false : render the view mode of the widget
param {String} context The context of the widget (e.g. siteid)


var informOnLoad = function(widgetname) {

Inform the widget that is is loaded and execute the main JavaScript function If the widget name is 'createsite', then the function sakai.createsite will be executed.
param {String} widgetname The name of the widget


var locateTagAndRemove = function(content, tagName, URLIdentifier) {

Locate a tag and remove it from the content
param {String} content The complete content of a file (e.g. <div>...)
param {String} tagName The name of the tag you want to remove (link/script)
param {String} URLIdentifier The part that identifies the URL (href/src)


var loadWidgetFiles = function(widgetsInternal2, batchWidgets) {

Load the files that the widget needs (HTML/CSS and JavaScript)
param {Object} widgets
param {Object} batchWidgets A list of all the widgets that need to load


var locateWidgets = function(containerId, showSettings, widgetData, context, callback) {

Insert the widgets into the page
param {String} containerId The id of the container element
param {Boolean} showSettings Show the settings for the widget
param {Object} widgetData Widget data associated to the loaded widgets
param {String} context The context of the widget (e.g. siteid)


saveWidgetData : function(id, content, callback, removeTree) {

Save the preference settings or data for a widget
param {String} id The unique id of the widget
param {Object} content A JSON object that contains the data for the widget
param {Function} callback Callback function that gets executed after the save is complete
param {Boolean} removeTree If we should replace the entire tree of saved data or just update it
return {Void}


removeWidgetData : function(id, callback) {

Remove the preference settings or data for a widget
param {String} id The unique id of the widget
param {Function} callback Callback function that gets executed after the delete is complete
return {Void}


changeWidgetTitle : function(tuid, title) {

Change the given widget's title
param {String} tuid The tuid of the widget
param {String} title The title to change to


isOnDashboard : function(tuid) {

Check if a widget is on a dashboard
param {String} tuid The tuid of the widget
return {Boolean} true if on a dashboard, false if not (for example, on a page)


nofityWidgetShown : function(selector, showing) {

Notify widgets when they have been shown or hidden, given a root element
param {String} selector the root selector ('#theid') for the page which could house the widgets to nofity
param {Boolean} showing true if we are showing the widget, false if it is about to be hidden


bindToHash : function() {

This binds to any links with a hash URL and handles the pushState for them


createHashURL : function(paramsObject, url) {

This function is used for creating href's to link to a hash change
param {Object} paramsObject The object containing key value pairs to add to the URL
param {String} url The url you want to add hash parameters to. If not provided, the system will use the current page URL.


handleHashChange : function(e) {

Handle the hash change and dispatch the hashchange event to each widget that has the changed parameter
param {Object} e The hashchange event object


if (!$.isEmptyObject(sakai_widgets_config)) {

construct the changedParams object which contains a map like this: widgetHashes = { 'widgetid' : { 'changed': {'property': 'value'}, 'deleted': {}}};


getWidget: function(widgetid) {

This function will return widget configuration for a specific widget
param {Object} widgetid id of the widget as specified in the widget's config file


getWidgetTitle: function(widgetid) {

This function will return the name of a widget in the current user's language
param {Object} widgetid id of the widget as specified in the widget's config file


getWidgetDescription: function(widgetid) {

This function will return the description of a widget in the current user's language
param {Object} widgetid id of the widget as specified in the widget's config file


insertOnLoadWidgets: function() {

Add the widgets that need to be present at all time on all pages


registerLazyLoading: function() {

This function will register all widgets that require lazy loading


isRecursivelyEmbedded: function($rootel, poolID, ref) {

Check to see if a widget is embeddded inside itself
param {jQuery} $rootel The rootel of the widget
param {String} poolID The pool id of the widget
param {String} ref The _ref of the widget
return {Boolean} if it is safe to embed the widget