Source: manager/controllerManager.js

/*
 * 	Copyright (C) 2012-2013 DFKI GmbH
 * 	Deutsches Forschungszentrum fuer Kuenstliche Intelligenz
 * 	German Research Center for Artificial Intelligence
 * 	http://www.dfki.de
 * 
 * 	Permission is hereby granted, free of charge, to any person obtaining a 
 * 	copy of this software and associated documentation files (the 
 * 	"Software"), to deal in the Software without restriction, including 
 * 	without limitation the rights to use, copy, modify, merge, publish, 
 * 	distribute, sublicense, and/or sell copies of the Software, and to 
 * 	permit persons to whom the Software is furnished to do so, subject to 
 * 	the following conditions:
 * 
 * 	The above copyright notice and this permission notice shall be included 
 * 	in all copies or substantial portions of the Software.
 * 
 * 	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 
 * 	OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
 * 	MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 
 * 	IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 
 * 	CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 
 * 	TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 
 * 	SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
define(['mmirf/dictionary', 'mmirf/controller', 'mmirf/constants', 'mmirf/commonUtils', 'mmirf/util/deferred' ],
	/**
	 * A class for managing the controllers of the application. <br>
	 * It's purpose is to load the controllers and their views / partials and provide functions to find controllers or
	 * perform actions or helper-actions.
	 * 
	 * This "class" is structured as a singleton - so that only one instance is in use.<br>
	 * 
	 * 
	 * @class
	 * @name mmir.ControllerManager
	 * @static
	 * 
	 */
	function( 
		Dictionary, Controller, constants, commonUtils, deferred
){
	//the next comment enables JSDoc2 to map all functions etc. to the correct class description
	/** @scope mmir.ControllerManager.prototype */
	
	// private members
	/**
	 * Array of controller-instances
	 * 
	 * @type Dictionary
	 * @private
	 * 
	 * @memberOf mmir.ControllerManager#
	 */
	var controllers = new Dictionary();
	
	/**
	 * Initialize ControllerManager:
	 * 
	 * Load all Controllers from /controller
	 * that are specified in /config/directories.json
	 * 
	 * @function
	 * @param {Function} [callback] OPTIONAL
	 * 				an optional callback that will be triggered after the controllers where loaded
	 * @param {Object} [ctx] OPTIONAL
	 * 				the context for the controller & helper implementations (DEFAULT: the global context, i.e. window)
	 * @returns {Promise}
	 * 				a Deferred promise that will get fulfilled when controllers are loaded
	 * @private
	 * 
	 * @memberOf mmir.ControllerManager#
	 */
	function _init(callback, ctx) {
		
		//shift arguments if necessary:
		if(!ctx && typeof callback !== 'function'){
			ctx = callback;
			callback = void(0);
		}
		
		//set ctx to global/window, if not already set:
		ctx = ctx || (typeof window !== 'undefined'? window : global);
		
		//create return value
		var defer = deferred();
		if(callback){
			defer.then(callback, callback);
		}
		
		
		/**
		 * HELPER FUNC: remove file extension from file-name
		 * @private
		 * 
		 * @memberOf mmir.ControllerManager#
		 */
		function removeFileExt(fileName){
	    	return fileName.replace(/\.[^.]+$/g,'');
	    }
		/**
		 * HELPER FUNC: convert first letter to upper case
		 * @private
		 * 
		 * @memberOf mmir.ControllerManager#
		 */
	    function firstToUpperCase(name){
	    	return name[0].toUpperCase()+name.substr(1);
	    }
	    
	    /**
		 * HELPER FUNC: add file path for generated / compiled view-element
		 *              if it exists.
		 * 
		 * @param {String} genDirPath
		 * 				path the the directory, where the file for the generated view-element
		 * 				is potentially located (generated file may not exists)
		 * 
		 * @param {PlainObject} infoObj
		 * 				the info-object for the view-element. MUST HAVE property <code>name</code>!
		 * 
		 * @param {String} [fileNamePrefix] OPTIONAL
		 * 				prefix for the file-name, e.g. in case of Partials, the file-name would be:
		 * 				<code>fileNamePrefix + infoObj.name</code> (+ file-extension)
		 * 
		 * @returns {PlainObject}
		 * 				the info-object: if a path for the generated file exists,
		 * 				a property <code>genPath</code> (String) with the path as value is added.
		 * @private
		 * 
		 * @memberOf mmir.ControllerManager#
		 */
	    function addGenPath(genDirPath, infoObj, fileNamePrefix){
	    	
	    	var prefix = fileNamePrefix? fileNamePrefix : '';
	    	var genPath = commonUtils.listDir(genDirPath, prefix + infoObj.name + '.js');
    		if(genPath && genPath.length > 0){
    			infoObj.genPath = genDirPath + '/' + genPath[0];
    		}
    		
    		return infoObj;
	    }
		
		/**
		 * This function gets the controller file names and builds a JSON object containing information about
		 * the location, file name etc. for the controller itself, its views, partials, layout, and helper.
		 * 
		 * @function
		 * @param {String} controllerName
		 * 					the name of the Controller (must start with an upper case letter).
		 * @param {String} controllerPath
		 * 					the path (URL) where the file with the Controller's implementation
		 * 					is located (according to information in file <code>/config/directories.json</code>,
		 * 					i.e. {@link mmir.CommonUtils#getDirectoryStructure})
		 * @returns {JSON} JSON-Object containing information about the controller,
		 * 				its views, partials, and paths etc. 
		 * @private
		 * 
		 * @example
		 * //EXAMPLE for returned object:
		 * {
		 *   "fileName": "application",
		 *   "name": "Application",
		 *   "path": "controllers/application.js",
		 *   "views": [
		 *     {
		 *       "name": "login",
		 *       "path": "views/application/login.ehtml",
		 *       "genPath": "gen/views/application/login.js"
		 *     },
		 *     {
		 *       "name": "registration",
		 *       "path": "views/application/registration.ehtml",
		 *       "genPath": "gen/views/application/registration.js"
		 *     },
		 *     {
		 *       "name": "welcome",
		 *       "path": "views/application/welcome.ehtml",
		 *       "genPath": "gen/views/application/welcome.js"
		 *     }
		 *   ],
		 *   "partials": [
		 *     {
		 *       "name": "languageMenu",
		 *       "path": "views/application/~languageMenu.ehtml",
		 *       "genPath": "gen/views/application/~languageMenu.js"
		 *     }
		 *   ],
		 *   "helper": {
		 *     "fileName": "applicationHelper",
		 *     "name": "ApplicationHelper",
		 *     "path": "helpers/applicationHelper.js"
		 *   },
		 *   "layout": {
		 *     "fileName": "application",
		 *     "name": "application",
		 *     "path": "views/layouts/application.ehtml",
		 *     "genPath": "gen/views/layouts/application.js"
		 *   }
		 * }
		 * //NOTE 1: genPath is an optional field, i.e. it will only be added
		 *           if the corresponding file exists
		 * //NOTE 2: layout may be NULL
		 * 
		 * @requires mmir.CommonUtils
		 * @requires mmir.Constants
		 * 
		 * @memberOf mmir.ControllerManager#
		 */
	    function getControllerResources(controllerName, controllerPath){
	    	
	    	var partialsPrefix = commonUtils.getPartialsPrefix();
	    	var controllerFilePath = controllerPath + controllerName;
	    	
	    	var rawControllerName= removeFileExt(controllerName);
	    	controllerName = rawControllerName;
	    	
	    	//helper: check if string starts with the controller's name (ignoring case)
	    	var reStartsWithCtrl = new RegExp('^'+controllerName, 'i');
	    	
	    	
	    	var viewsPath = constants.getViewPath() + controllerName;
	    	var genViewsPath = constants.getCompiledViewPath() + controllerName;
	    	
	    	controllerName = firstToUpperCase(controllerName);
	    	var reView = new RegExp('^(?!'+partialsPrefix+').*\\.ehtml$', 'ig');//<- for finding ehtml files that do NOT start with ~ (i.e. exluding partials)
	    	var viewsFileList = commonUtils.listDir(viewsPath, reView);
	    	var i, size;
	    	var viewsList = [];
	    	if(viewsFileList != null){
	    		for (i=0, size = viewsFileList.length; i < size; ++i){
	    			
	    			viewsList.push(addGenPath( genViewsPath, {
		    			name: removeFileExt(viewsFileList[i]),
		    			path: viewsPath+"/"+viewsFileList[i]
		    		}));
		    	}
	    	}
	    	var rePartials = new RegExp('^'+partialsPrefix+'.*\\.ehtml$', 'ig');//<- for finding ehtml files that start with ~ (i.e. partials)
	    	var partialsFileList = commonUtils.listDir(viewsPath, rePartials);
	    	var partialsInfoList = [];
	    	if(partialsFileList != null) {
	    		for (i=0, size = partialsFileList.length; i < size; ++i){
	    		
		    		partialsInfoList.push(addGenPath(genViewsPath, {
				    		// remove leading "~" indicating it is a partial
				    		name: removeFileExt( partialsFileList[i].replace(partialsPrefix,'') ),
				        	path: viewsPath+"/"+partialsFileList[i]
		    		
					}, partialsPrefix));
		        }
	    	}
	    	var helpersPath = constants.getHelperPath();
	    	helpersPath = helpersPath.substring(0, helpersPath.length-1);//remove trailing slash
	    	var helpersFileList = commonUtils.listDir(helpersPath, /^.*\.js$/ig);//get *.js files
	    	var helperSuffix = constants.getHelperSuffix();
	    	var helperInfo = null;
	    	var reHelpersEnd = new RegExp(helperSuffix+'\.js$', 'i');
	    	if(helpersFileList != null){
	    		
	    		for(i=0, size = helpersFileList.length; i < size; ++i){
		    		if(reStartsWithCtrl.test(helpersFileList[i]) && reHelpersEnd.test(helpersFileList)){
		    	    	
		    			var name = removeFileExt(helpersFileList[i]);
		    			helperInfo = {
		    	    			fileName: name,
		    	    			name: firstToUpperCase(name),
		    	    			path: helpersPath+"/"+helpersFileList[i]
		    	    	};
		    		}
		    	}
	    		
	        }
	    	
	    	var layoutsPath = constants.getLayoutPath();
	    	layoutsPath = layoutsPath.substring(0, layoutsPath.length-1);//remove trailing slash
	    	var reLayout = new RegExp('^(?!'+partialsPrefix+').*\\.ehtml$', 'ig');//<- for finding ehtml files that do NOT start with ~ (i.e. exluding partials)
	    	var layoutsFileList = commonUtils.listDir(layoutsPath, reLayout);
	    	
	    	var layoutInfo = null, layoutGenPath;
	    	if(layoutsFileList != null){
		    	for(i=0, size = layoutsFileList.length; i < size; ++i){
		    		
		    		if( reStartsWithCtrl.test(layoutsFileList[i]) ){
		    			
		    			var layoutName = removeFileExt(layoutsFileList[i]);
		    	    	layoutInfo = {
				    		fileName: layoutName,
				    		name: firstToUpperCase(layoutName),
				        	path: layoutsPath+"/"+layoutsFileList[i],
		    	    	};
		    	    	
		    	    	layoutGenPath = constants.getCompiledLayoutPath();
		    	    	addGenPath(layoutGenPath.substring(0, layoutGenPath.length-1), layoutInfo);
			        	
		    	    	//there can be max. 1 layout per controller
			        	break;
		    		}
		        }
	    	}
	    	
	    	var ctrlInfo = {
	    		fileName: rawControllerName,
	    		name:     controllerName,
	    		path:     controllerFilePath,
	    		
	    		views:    viewsList,
	    		partials: partialsInfoList,
	    		helper:   helperInfo,
	    		layout:   layoutInfo
	    	};
	    	
	    	//TEST compare info with "reference" result from original impl.:
//	    	var test ={
//	    			application: '{"fileName":"application","name":"Application","path":"controllers/application.js","views":[{"name":"login","path":"views/application/login.ehtml"},{"name":"registration","path":"views/application/registration.ehtml"},{"name":"welcome","path":"views/application/welcome.ehtml"}],"partials":[{"name":"languageMenu","path":"views/application/~languageMenu.ehtml"}],"helper":{"fileName":"applicationHelper","name":"ApplicationHelper","path":"helpers/applicationHelper.js"},"layout":{"fileName":"application","name":"application","path":"views/layouts/application.ehtml"}}',
//	    			calendar: '{"fileName":"calendar","name":"Calendar","path":"controllers/calendar.js","views":[{"name":"create_appointment","path":"views/calendar/create_appointment.ehtml"}],"partials":[],"helper":null,"layout":null}'
//	    	};
//	    	
//	    	var isEqual = (JSON.stringify(ctrlInfo) === test[ctrlInfo.fileName]);
//	    	console[isEqual? 'info':'error']('compliance-test: isEual? '+  isEqual);
	        
	        return ctrlInfo;
		};
		commonUtils.loadImpl(
				constants.getControllerPath(),
				false,
				function () {
					
					console.info( '[loadControllers] done' );
					
					defer.resolve(_instance);
				},
				function isAlreadyLoaded (name) {
					return false;
				},
				function callbackStatus(status, fileName, msg) {
					if(status==='info'){
						
						console.info('[loadController] "'+fileName);
						var ctrlInfo = getControllerResources(fileName, constants.getControllerPath());
						var controller = new Controller(ctrlInfo.name, ctrlInfo, ctx);
						if(ctrlInfo.helper){
							var helperPath = ctrlInfo.helper.path;
							var helperName = ctrlInfo.helper.name;
							controller.loadHelper(helperName,helperPath, ctx);
						}
						controllers.put(controller.getName(), controller);
					}
					else if(status==='warning'){
						console.warn('[loadController] "'+fileName+'": '+msg);
					}
					else if(status==='error'){
						console.error('[loadController] "'+fileName+'": '+msg);
					}
					else{
						console.error('[loadController] '+status+' (UNKNOWN STATUS) -> "'+fileName+'": '+msg);
					}               
				}
		);		
		return defer;
	};
	/**
     * Object containing the instance of the class {@link mmir.ControllerManager} 
     * 
     * @type Object
     * @private
	 * @augments mmir.ControllerManager
	 * @ignore
     */
	var _instance = {
			/** @scope mmir.ControllerManager.prototype *///for jsdoc2
			// public members           
			/**
			 * This function gets the controller by name. 
			 * 
			 * @function
			 * @param {String} ctrlName Name of the controller which should be returned
			 * @returns {Object} controller if found, null else
			 * @public
			 * @memberOf mmir.ControllerManager.prototype
			 */
			get: function(ctrlName){
				var ctrl = controllers.get(ctrlName);
				if(!ctrl){
					return null;
				}
				return ctrl;
			},
			/**
			 * This function returns names of all loaded controllers. 
			 * 
			 * @function
			 * @returns {Array<String>} Names of all loaded controllers
			 * @public
			 * @memberOf mmir.ControllerManager.prototype
			 */
			getNames: function(){
				return controllers.getKeys();
			},
			/**
			 * This function performs an action of a controller. 
			 * 
			 * @function
			 * @param {String} ctrlName Name of the controller to which the action belongs
			 * @param {String} actionName Name of the action that should be performed
			 * @param {Object} data optional data that can be submitted to the action
			 * @returns {Object} the return object of the performed action
			 * @public
			 * @memberOf mmir.ControllerManager.prototype
			 */
			perform: function(ctrlName, actionName, data){
				var ctrl = this.get(ctrlName);
				if (ctrl != null) {
					return ctrl.perform(actionName, data);
				}
				else {
					console.error('ControllerManager.perform: the controller could not be found "'+ctrlName+'"');
				}
			},
			/**
			 * This function performs an action of a helper-class for a controller. 
			 * 
			 * @function
			 * @param {String} ctrlName Name of the controller to which the helper action belongs
			 * @param {String} actionName Name of the action that should be performed by the helper
			 * @param {Object} data optional data that can be submitted to the action
			 * @returns {Object} the return object of the performed action
			 * @public
			 * @memberOf mmir.ControllerManager.prototype
			 */
			performHelper: function(ctrlName, actionName, data) {
				var ctrl = this.get(ctrlName);
				if (ctrl != null) {
					if(arguments.length > 3){
						return ctrl.performHelper(actionName, data, arguments[3]);
					}
					else {
						return ctrl.performHelper(actionName, data);
					}
				}
				else {
					console.error('ControllerManager.performHelper: the controller could not be found "'+ctrlName+'"');
				}
			},
			/**
			 * This function must be called before using the {@link mmir.ControllerManager}. The Initialization process is asynchronous, 
			 * because javascript-files must be loaded (the controllers).
			 * To ensure that the ControllerManager is initialized, a callback can be used, or the returned
			 * <em>Promise</em> (i.e. a "then-able" object) for code, that relies
			 * on the presence of the loaded controllers.<br>   
			 * 
			 * 
			 * <div class="box important">
			 * <b>Note:</b>
			 * The callback function should be used for code, that requires the prior loading of the controllers.<br> 
			 * The callback mechanism is necessary, because loading the controllers is asynchronous.<br><br>
			 * If provided, the callback function is invoked with 1 argument, the ControllerManager instance:<br>
			 * <code> callbackFunction(controllerManagerInstance) </code>
			 * </div>
			 * 
			 * @function
			 * 
			 * @param {Function} [callback] OPTIONAL
			 * 				an optional callback that will be triggered after the controllers where loaded
			 * @param {Object} [ctx] OPTIONAL
			 * 				the context for the controller & helper implementations (DEFAULT: the global context, i.e. window)
			 * @returns {Promise}
			 * 				a deferred promise that will get fulfilled when controllers are loaded
			 * @example
			 *  //recommended style:
			 *  mmir.require(['mmirf/controllerManager', ...], function(controllerManager, ...) {
			 *  	controllerManager.init().then(function(theInitializedControllerInstance){
			 *  		...
			 *  	});
			 *  })
			 *  
			 *  //old style:
			 * 	function afterLoadingControllers(controllerManagerInstance){
			 * 		var appCtrl = controllerManagerInstance.get('Application');
			 * 		//do something...
			 * 	} 
			 * 	mmir.ctrl.init(afterLoadingControllers);
			 * @public
			 * @memberOf mmir.ControllerManager.prototype
			 */
			init: _init
	};
	/**@ignore*/
	return _instance;
	
});