File: javascript.js

//Front-end javascript controller
//LGPL - http://www.gnu.org/licenses/lgpl-3.0.txt
//Kristo Vaher - kristo@waher.net

//Backend engine
var ajaxEngine='ajax.php';

//Used for convenient internal variables
var system=new Object();

//If you ever set systemLock to true, then this prevents user interface actions from taking place
system.systemLock=false;

$(document).ready(function(){
	//You can bind events and whatnot here as you would in any other case. 
	//This here is a placeholder for your convenience.
});

//This is front-end input controller. Data can be whatever you want, 
//you can use it in different context depending on action.
function uiAction(action,data){
	//input is an object used to be sent to AJAX backend.
	var input=new Object();
	if(system.systemLock==false){
		switch(action){
			
			//This shows how to use simple uiAction without using AJAX
			case 'alertString':
				alert('Your string: '+data);
			break;
			
			//This is an example function, it takes a value and has PHP backend lowercase it before alerting it
			//to the user.
			case 'alertLowercaseString':
				//You do not have to use input object here, but you do need to provide an array or another object
				//to be sent to executeAjaxAction();
				input['string']=data;
				executeAjaxAction(action,input);
			break;
			
			default:
				alert('UI ERROR: This action ['+action+'] does not exist in user interface!');
		}
	}
}

//This should not be modified, it is standardized function for sending data to backend
//and retreiving the JSON string before forwarding it to frontend callback
function executeAjaxAction(action, rawdata){
	//data is an array or an object serialized for use in a URL
	data=$.param(rawdata);
	//Lock is used to prevent action spamming
	//If you don't want to lock AJAX actions, then comment this out or at least display an error
	if(system['lock_'+action]!=1){
		system['lock_'+action]=1;
		$.ajax({
			type: 'POST',
			url: ajaxEngine,
			dataType: 'json',
			cache: false,
			async: true,
			data: ({action : action, data : data}),
			success: function(json){
				//If successful the JSON returned from backend is forwarded to be parsed by frontend actions
				parseAjaxReturn(json);
				system['lock_'+action]=0;
			},
			error: function(obj,msg,detailedmsg){
				//In case there was any unexpected error in the backend (PHP errors and whatnot), alert everything
				alert('ENGINE ERROR: '+msg+' ('+detailedmsg+')');
				system['lock_'+action]=0;
			}
		});
	} else {
		//You can comment this alert out
		alert('ENGINE ERROR: This action is already in progress');
	}
}

//This function takes the AJAX returned JSON and executes actions depending on the type
//You can call new user interface actions from here as well
function parseAjaxReturn(json){
	//If backend defines an error and a message for the error, alert this
	if(json['error']==1){
		alert('ERROR: '+json['message']);
	} else {
		switch(json['action']){
			
			//Example action for alert should backend decide to call for an alert
			case 'alert':
				alert(json['message']);
			break;
			
			//Simple refresh callback from backend
			case 'refresh':
				document.location.href=document.location.href;
			break;
			
			//Backend should always define action to be 'none' if no callback is defined
			case 'none':
			break;
			
			//In case no action was defined, alert an error
			default:
				alert('UI ERROR: Callback action ['+json['action']+'] does not exist in user interface!');
		}
	}
}