P.S.  I am back in the land of Appcelerator for the time being so I should have a large update to the Mvc framework at some point.

Appcelerator Mvc Introduction
Appcelerator Mvc Routing
jsAutomapper

Setup

If you follow along with this post you will end up with the same working example I have on the Appcelerator Marketplace. If you just want to walk through the example you can download the project here. The first thing you are going to want to do is create a new, blank Appcelerator mobile project. Next, save these files and add them to your project:

• mvc.js
• jsAutomapper.js
• joli.js

You can place the files in the “~/Resources” folder or create a subfolder if you prefer. Through this example I will base all my code on the idea that you placed these files in this folder.

app.js

Now that you have added the files to the project we are ready to start writing code. Delete everything inside of the app.js file so we can start from scratch. Next add the following code. This will setup any includes we need for the mvc framework. The includes listed here take care of the Mvc framework itself as well as any Controllers you plan on using in your project. I also include a file named “dal.js” which is used to access the database and any data models we will need. We will uncomment this line later. We haven’t created these Controllers yet but list them here anyway — that’s coming up in our next step. The last line initializes the Mvc framework and sets up your Controllers as well as Views.

	Ti.include('mvc.js'); 

	//Ti.include("/dal.js");

	Ti.include('/controllers/HomeController.js');
	//Ti.include('/controllers/AccountsController.js');

	Mvc.init();

The next portion we have is adding any routes you may want. In this example I include a default route as well as a specific route. I won’t explain the routing here as I have already gone over it in my routing post

	// make a specific route
	Mvc.mapRoute(
		"DoStuff_Route",
		"DS",
		{
			controller : "Home",
			action : "DoStuff"
		}
	)

	// map a default route
	Mvc.mapRoute(
		"Default_Route",
		"{controller}.{action}.{text}", // could also be {controller}/{action}/{id}
		{
			controller : "Home",
			action : "Default",
			text : "Default Text"
		});

The last major portion of the code sets up your window management. I use this code as a hook in case you want to render your windows differently or even use this Mvc framework in another context (i.e. the web). In my implementation I basically keep track of a window stack and open/close the windows when appropriate. It should be fairly easy to create your own implementation if you desire alternative behavior… Anyway, here is the code. I have commented it pretty extensively so you should be able to get the gist of it.

// manage the windows -- window stack
var openWindows = [];

Mvc.render = function(ui, routeData) {
	var win, index, routeName = routeData.controller + "." + routeData.action;

	// find the index in the stack of windows
	for(var i = openWindows.length - 1; i >= 0; i -= 1) {
		if(openWindows[i]._title === routeName) {
			win = openWindows[i];
			index = i + 1;
			break;
		}
	}
	function cleanup(index) {
		for(var i = index; i < openWindows.length; i += 1) {
			openWindows[i].close();
			openWindows[i] = null;
		}
		openWindows = openWindows.splice(0, index);
	}
	// if the window already exists in the stack
	if(win) {
		// clean up array -- remove all windows
		cleanup(index);

		// remove children from current view
		var children = win.children;
		for(var i = 0; i < children.length; i += 1) {
			win.remove(children[i])
		}
	} else {
		// create a new window
		win = Ti.UI.createWindow({
			_title : routeName,
			fullscreen : true
		});

		win.addEventListener('close', function() {
			// find the index of this window so we can remove it when the back button is pressed
			for(var i = openWindows.length - 1; i >= 0; i -= 1) {
				if(openWindows[i]._title === routeName) {
					index = i;
					break;
				}
			}
			cleanup(index);
		});

		// This handles the creation of the first window so that
		// Appcelerator will exit your app when this window is closed.
		if(openWindows.length === 0) {
			win.exitOnClose = true;
		}

		openWindows.push(win);
		win.open();
	}

	// This adds the controls you created in your view
	win.add(ui);

	// return the window incase you need it for something in your view
	return win;
};

The last portion of code we need to add to app.js is used to start up the app and navigate to the correct window. If you do not pass any parameters it will resolve to your default route. If you want a specific route then simply pass the appropriate parameters.

	// This will go off and attempt to render the default route and will
	// fail since we have not created the 'Home' controller yet
	Mvc.start();

The Controllers

Next up we will create the our Controllers. First create a folder named “controllers” and place it under the “~/Resources” folder. Next create javascript files named “HomeController.js” and “AccountsController.js” under the “controllers” folder. First we will implement the “HomeController”. The code in this portion is very straight forward as this Controller does not use the Data Access Layer (dal.js) so we can implement the entire Controller. The “AccountsController” on the other hand is fairly complex and uses the Data Access Layer (dal.js) so we will focus on that later.

HomeController

Here is the implementation of the “HomeController”. The first portion is simply the includes the the Views used by this controller. I structure my code so each Action of the Controller has its own View.

	// This will be the location for the 'Default' view
	Ti.include('/views/Home/Default.js');
	// another view
	Ti.include('/views/Home/DoStuff.js');

The next portion is the shell of the Controller. It is a closure which takes in Mvc.Controllers as its parameter so we can populate the framework with all the controllers.

	(function(c) {
		c.HomeController = {
			// Actions go here...
		};
	}(Mvc.Controllers));

Inside the HomeController object we now add the Actions “Default” and “DoStuff”. In the “Default” method we create a Model to populate our UI. It populates the Model with things passed to the Action or default values defined in any routes we add in app.js. The “DoStuff” Action takes in a string as a parameter, modifies it, and sends it off to its view for rendering. I will show the implementation of “DefaultModel” in the next step. We return this model in the “this.view” function call of the “Default” Action which will send the Model to the view to render out.

	Default : function(text, other) {
		// Create the model and populate it with some values
		var model = DefaultModel();
		model.text = text;
		model.value = text;

		// This returns a view and tells the framework to render the
		// 'Default' view using the model we created.
		return this.view('Default', model);
	},
	// we could add another action here
	DoStuff : function (value) {
		// manipulate the value parameter and return the appropriate view
		return this.view('DoStuff', value + "!!!");
	}

Here is the implementation for “DefaultModel”. It is simply a factory to create an object.

	function DefaultModel() {
		return {
			text : null,
			value : 0
		};
	}

Here is what the “HomeController.js” file should look like in the end:

	// This will be the location for the 'Default' view
	Ti.include('/views/Home/Default.js');
	// another view
	Ti.include('/views/Home/DoStuff.js');

	(function(c) {
		// This is just a basic model used to render
		// the 'Default' view.
		function DefaultModel() {
			return {
				text : null,
				value : 0
			};
		}
		// Initializes the 'HomeController' in Mvc.Controllers
		c.HomeController = {
			Default : function(text, other) {
				// Create the model and populate it with some values
				var model = DefaultModel();
				model.text = text;
				model.value = text;

				// This returns a view and tells the framework to render the
				// 'Default' view using the model we created.
				return this.view('Default', model);
			},
			// we could add another action here
			DoStuff : function (value) {
				// manipulate the value parameter and return the appropriate view
				return this.view('DoStuff', value + "!!!");
			}
		};
	}(Mvc.Controllers));

That is it for our controllers for the moment. Like I said, the AccountsController has more complexities we need to tackle first so we will ignore the file for now.

Home Controller Views

The first thing we need to do here is create a “views” folder under “~/Resources” and then a “Home” folder under the “views” folder. Now create “Default.js” and “DoStuff.js” at “~/Resources/views/Home”. We start off by implementing the shell for the “Default” view. This works similar to Controllers in the fact that we pass “Mvc.Views” into a closure. We make sure that the object in which the View resides (in this case Home) exists and create it if it doesn’t. We then define our View as a function.

	(function(v) {
		// Create the 'Home' object if it doesn't already exist
		if(!v.Home) {
			v.Home = {};
		}

		/*
		 * Render the default page
		 */
		v.Home.Default = function(model) {

		};
	}(Mvc.Views));

The next portion of code will set up the actual UI elements of the window. We create a label and textfield which are populated from the model that was returned from the “HomeController.Default” Action and is passed into the function we defined in “Home.Default” View. There is also a button that we will use to navigate to the “HomeController.DoStuff” Action we previously defined. Since we added the “DoStuff_Route” in the app.js we can use the alias of “DS” to navigate there. The text value from the textbox is also passed to the Action. Lastly we return the View which contains all the controls used in the window. It is important that we have a single UI object to contain the entire View so it can be added appropriately to the window. This UI object will be used to populate a window created in the “Mvc.render” function we also defined in app.js.

	// get a reference to the view
		// get a reference to the view
		var self = this;

		var view = Ti.UI.createView();
		var label = Ti.UI.createLabel({
		    text : model.text,
		    top: "5%",
		    height : "5%"
		});
		var textField = Ti.UI.createTextField({
		    value : model.value,
		    top : "10%",
		    width: "50%",
		    height: "5%",
			backgroundColor: "#ffffff",
		    keyboardType:Ti.UI.KEYBOARD_DEFAULT,
		});
		var button = Ti.UI.createButton({
		    title : "Submit",
		    width: "50%",
		    height : "15%"
		});

		// This will call DoStuff
		button.addEventListener("click", function(e) {
		    // Uses a specific route ('DS') we defined in app.js
		    self.action("DS", textField.value);
		});
		view.add(label);
		view.add(textField);
		view.add(button);

		return view;

In the end your code for the “Home.Default” view should look like this:

	(function(v) {
    // Create the 'Home' object if it doesn't already exist
    if(!v.Home) {
        v.Home = {};
    }

    /*
     * Render the default page
     */
    v.Home.Default = function(model) {
		// get a reference to the view
		var self = this;

		var view = Ti.UI.createView();
		var label = Ti.UI.createLabel({
		    text : model.text,
		    top: "5%",
		    height : "5%"
		});
		var textField = Ti.UI.createTextField({
		    value : model.value,
		    top : "10%",
		    width: "50%",
		    height: "5%",
			backgroundColor: "#ffffff",
		    keyboardType:Ti.UI.KEYBOARD_DEFAULT,
		});
		var button = Ti.UI.createButton({
		    title : "Submit",
		    width: "50%",
		    height : "15%"
		});

		// This will call DoStuff
		button.addEventListener("click", function(e) {
		    // Uses a specific route ('DS') we defined in app.js
		    self.action("DS", textField.value);
		});
		view.add(label);
		view.add(textField);
		view.add(button);

		return view;
    };
}(Mvc.Views));

Now we can start in on the “Home.DoStuff” View. This view is very simple and just displays the text in the textbox of the “Home.Default” View in addition to a modification (the ‘!!!’) in the “HomeController.DoStuff” Action.

	(function(v) {
		// Create the 'Home' object if it doesn't already exist
		if(!v.Home) {
			v.Home = {};
		}

		/*
		 * Render the DoStuff page
		 */
		v.Home.DoStuff = function(model) {
			var view = Ti.UI.createView({
				backgroundColor : "#fff"
			});
			var label = Ti.UI.createLabel({
				text : model,
				color : "#000"
			});

			view.add(label);

			return view;
		};
	}(Mvc.Views));

That covers the source up to getting the HomeController running. You should now be able to run the project and see the framework in action although it is a boringly simple app at this point. When you run you should see some text and a textbox. If you modify the text it will show up in the next window along with three exclamation points. Next up we will get into working with joli and the DAL. If you followed all the steps correctly you should end up with this.

Data Access and Data Models

Let me start off first by saying that the Data Access Layer can be a nasty thing if you let it. This is why I prefer to user an ORM such as joli. This allows you to avoid writing data access code which may end up getting placed in your controller Actions which really defeats separation of concerns. It also allows you to reuse a ton of common functionality with a common API. In addition you can get down and dirty with custom SQL queries when you need it. Anyways, if you haven’t already, create a “dal.js” file and save it under the “~/Resources” folder. You also need to go to app.js and uncomment the “//Ti.include(“/dal.js”);” line. The source in this file will be fairly simple as we want to separate out the Data Access code to keep everything neat and tidy. We also will create a global object for accessing the DAL from any other file. So again we create our closure passing in the “Ti.App” object.

	var dal = (function(app) {
		// if the dal has already been defined, return
		if(app.dal) {
			return;
		}

		// initialize the dal object and get a local reference
		var d = app.dal = {};

		return d;
	}(Ti.App));

Next up we will add all our references to libraries/models we will need and set up our database. After this, add the following code.

	Ti.include("/joli.js");
	Ti.include("/jsAutomapper.js");

	// set up our database
	joli.connection = new joli.Connection('SampleDatabase');

	// run setup for all models
	Ti.include("/models/Accounts.js");

	// models have been setup. initialize the database
	joli.models.initialize();

This code creates a database called “SampleDatabase” you can name the database whatever you want here. We will do setup for the various tables in the models files — “/models/Accounts.js” for example. When we finally call “joli.models.initialize” we have completed our setup of the DAL.

Here is the final source for “dal.js”

	var dal = (function(app) {
	// if the dal has already been defined, return
	if(app.dal) {
		return;
	}

	// initialize the dal object and get a local reference
	var d = app.dal = {};

	return d;
}(Ti.App));

Ti.include("/joli.js");
Ti.include("/jsAutomapper.js");

// set up our database
joli.connection = new joli.Connection('SampleDatabase');

// run setup for all models
Ti.include("/models/Accounts.js");

// models have been setup. initialize the database
joli.models.initialize();

Now with that out of the way, we can focus on setting up our Accounts Model. First off, create a folder under “~/Resources” called “models”. Next create a javascript file called “Accounts.js”. This file will be used to house all database initialization code as well as and automapper code used to map between Models and View Models. Models are used to transfer data from your database tables and View Models are objects which map directly to a specific view.

So start off your model implementation by passing “Ti.App.dal” into a closure and validating that the “dal” object has defined and the “dal.accounts” property has not.

	(function() {
		// dal has not been initialized or accounts have already been initailized
		if(!dal || dal.accounts) {
			return;
		}

	}());

Next up we will actuall setup our table in the database using joli. This creates a simple table named “Accounts” with a few columns (firstName, lastName, email). If you read through the joli API, it explains you can also add prototype functions to any Account Models as well as helper functions to the dal.accounts object when you do your initialization. I won’t get into that here but I have found it very useful for extending the existing API.

	dal.accounts = new joli.model({
		table : 'Accounts',
		columns : {
			id : 'INTEGER PRIMARY KEY AUTOINCREMENT',
			firstName : 'TEXT',
			lastName : 'TEXT',
			email : 'TEXT',
		}
	});

The next portion is mapping your View Models to your Models and vice-versa. For a Mvc framework I think this is a very important process. I am using jsAutomapper although I am sure there are similar solutions out there. It creates a single place for setting up a transformation between two objects and forms a contract between them. This way if you change a property in your database or in your View Model, you will get immediate feedback when the objects no longer map correctly. You can write unit tests that simply check that the two objects map correctly. This way you don’t have “undefined” showing up in your UI with no knowledge of where it was supposed to be populated or have a random “object is undefined” exception from a View Model property show up on some Action or View you haven’t worked on in weeks.

Here is the next bit of code you need for the Accounts Model. I will let you read through the code/comments and then go over what is actually going on here.

	// automapper mappings for this model

	// include view models - models can be mapped to multiple view models
	Ti.include("/viewModels/AccountViewModel.js");
	Ti.include("/viewModels/AccountsViewModel.js");
	Ti.include("/viewModels/CreateAccountViewModel.js");

	// This maps an Account to an AccountViewModel -- I pass in the destination key
	// as a function so automapper can use it to create viewmodels
	automapper.createMap("Account", AccountViewModel)
		// we don't actually need the 'firstName' since the column name matches the view model name 1-to-1
		// I just include it as an example
		.forMember("firstName", function() { return this.mapFrom("firstName") })
		// ignore this field since we already have it implemented
		.forMember("fullName", function() { return this.ignore(); });

	// model maps 1-to-1 -- we don't need to set up any members
	automapper.createMap("Account", "CreateAccountViewModel");

	// This maps an AccountViewModel to an Account
	automapper.createMap("CreateAccountViewModel", "Account")
		/*
		 * forAllMembers is run for every mapping
		 * dest - the destination object
		 * prop - the property name to set
		 * value - the value from the source
		*/
		.forAllMembers(function(dest, prop, value) {
			// tell joli to properly set the values
			dest.set(prop, value);
		})
		// ignore joli internal properties
		.forMember("_data", function() { this.ignore(); })
		.forMember("_metadata", function() { this.ignore(); })
		.forMember("_options", function() { this.ignore(); })
		.forMember("_originalData", function() { this.ignore(); })
		.forMember("isNew", function() { this.ignore(); });

So first off we include references to View Model objects we have yet to define. These are simple files and we will get to them later. Next we create a map between an “Account” and a “AccountViewModel”. Doing so we can later on take two objects and map all the properties between the two. We add a “ignore” to the “fullName” property of the “AccountViewModel” — this is a function I have defined in “AccountViewModel” and we don’t want to override it. The next mapping between “Account” and “CreateAccountViewModel” is pretty self-explanatory. The last mapping between “CreateAccountViewModel” and “Account” is special in that we use the “forAllMembers” call. What this does is when we set any properties in the “Account” model, we call this function to do so. This must be done since “Account” is a joli object and you must call “set” in order to properly set the property on the object to let joli know that we have made changes to the object. If you don’t when you call “accountObj.save”, the database will not pick up our changes. The ignores on this mapping are simply properties which get added to ever joli object (Model). Here is the combined source for the “Accounts.js” file.

	(function() {
		// dal has not been initialized or accounts have already been initailized
		if(!dal || dal.accounts) {
			return;
		}

		// create the accounts table
		dal.accounts = new joli.model({
			table : 'Accounts',
			columns : {
				id : 'INTEGER PRIMARY KEY AUTOINCREMENT',
				firstName : 'TEXT',
				lastName : 'TEXT',
				email : 'TEXT',
			}
		});

		// automapper mappings for this model

		// include view models - models can be mapped to multiple view models
		Ti.include("/viewModels/AccountViewModel.js");
		Ti.include("/viewModels/AccountsViewModel.js");
		Ti.include("/viewModels/CreateAccountViewModel.js");

		// This maps an Account to an AccountViewModel -- I pass in the destination key
		// as a function so automapper can use it to create viewmodels
		automapper.createMap("Account", AccountViewModel)
			// we don't actually need the 'firstName' since the column name matches the view model name 1-to-1
			// I just include it as an example
			.forMember("firstName", function() { return this.mapFrom("firstName") })
			// ignore this field since we already have it implemented
			.forMember("fullName", function() { return this.ignore(); });

		// model maps 1-to-1 -- we don't need to set up any members
		automapper.createMap("Account", "CreateAccountViewModel");

		// This maps an AccountViewModel to an Account
		automapper.createMap("CreateAccountViewModel", "Account")
			/*
			 * forAllMembers is run for every mapping
			 * dest - the destination object
			 * prop - the property name to set
			 * value - the value from the source
			*/
			.forAllMembers(function(dest, prop, value) {
				// tell joli to properly set the values
				dest.set(prop, value);
			})
			// ignore joli internal properties
			.forMember("_data", function() { this.ignore(); })
		        .forMember("_metadata", function() { this.ignore(); })
			.forMember("_options", function() { this.ignore(); })
			.forMember("_originalData", function() { this.ignore(); })
			.forMember("isNew", function() { this.ignore(); });
	}());

With that completed we are nearly ready to start working on the “AccountsController”. The only thing left is to create a “viewmodels” folder under the “~/Resources” folder and the javascript files “AccountViewModel.js”, “AccountsViewModel.js”, and “CreateAccountViewModel.js”.

AccountViewModel.js

	/*
	 * Simple Account model used for displaying Accounts in a list
	 */
	function AccountViewModel() {
		return {
			id : null,
			firstName : null,
			lastName : null,
			fullName : function() {
				return this.firstName + " " + this.lastName;
			}
		};
	}

AccountsViewModel.js

	/*
	 * A viewmodel which contains a collection of
	 * AccountViewModels
	 *
	 * In this case we could return a collection of
	 * AccountViewModels from the Accounts.Default action
	 * and I usually end up needing to pass additional data
	 */
	function AccountsViewModel() {
		return {
			accounts : []
		};
	}

CreateAccountViewModel.js

	function CreateAccountViewModel() {
		return {
			id : null,
			firstName : null,
			lastName : null,
			email : null
		};
	}

AccountsController

We’ll start off the “AccountsController” much like the “HomeController”. If you haven’t already created a file for this, create one under “~/Resources/controllers” as “AccountsController.js”. After this you must uncomment “Ti.include(‘/controllers/AccountsController.js’);” the line in app.js. Next add the stub controller code.

	(function(c) {
		// include the views
		Ti.include("/views/Accounts/Default.js");
		Ti.include("/views/Accounts/Create.js");

		c.AccountsController = {
		};
	}(Mvc.Controllers));

Again, we include the View files that we’ll create later. Next up come the Actions. I will go over each seperately. Stub out the “AccountsController” definition like this:

	c.AccountsController = {
		Default : function() {
		},
		Create : function(id) {
		},
		CreateFinish : function(model) {
		},
		Delete : function(id) {
		}
	};

So first off is the “Default” Action. In this view we want to allow the user to create new Accounts and edit/delete previously created “Accounts”. In order to do that we need to list all accounts in the view. So first off we use the DAL to get all Accounts. We then create an AccountsViewModel to house all the AccountViewModels. We then will use automapper to map between the two collections and then return the result to the View. Notice in the code that we pass the “AccountViewModel” to the “automapper.map” call. This is done in order for automapper to have a factory method to populate the “model.accounts” array with the appropriate View Model.

	/*
	 * Default action which simply shows a list of Accounts
	 */
	Default : function() {
		// use the dal as a repository to grab all accounts
		var accounts = dal.accounts.all();

		var model = AccountsViewModel();

		// automapper knows to map the two collections
		automapper.map("Account", AccountViewModel, accounts, model.accounts);

		// return the model and render the view
		return this.view("Default", model);
	}

Next up comes the “Create” Action. Notice how simple the function becomes now that we are using jsAutomapper to map the Model to View Model and joli for accessing the database. The “Create” function is essentialy a create/update method. If you pass in the “id” parameter we know that we are updating an existing “Account”. This action is used to simply populate the create/update UI.

	/*
	 * Basic create/update operation for a new Account
	 */
	Create : function(id) {
		var model = CreateAccountViewModel();

		if(id) {
			automapper.map("Account", "CreateAccountViewModel", dal.accounts.findOneById(id), model)
		}

		return this.view("Create", model);
	}

Next up is the “CreateFinish” Action (for lack of a better name). This Action writes any changes you made to the Account model to the database. If it is a new Account we will have joli instantiate an Account for us. If we are updating we query for the appropriate Account.

	/*
	 * Finishes up the creation/update process by inserting the object into the database
	 */
	CreateFinish : function(model) {
		var account;
		if(!model.id) {
			account = dal.accounts.newRecord();
		} else {
			account = dal.accounts.findOneById(model.id);
		}
		automapper.map("CreateAccountViewModel", "Account", model, account);
		account.save();
	}

Lastly is the “Delete” Action. This is a pretty boring and simple implementation and in this case, boring is good.

	/*
	 * Delete an Account based on an id
	 */
	Delete : function(id) {
		dal.accounts.deleteRecords(id);
	}

So that is the “AccountsController” in a nutshell. By abstracting much of the logic using a repository pattern (DAL) and using jsAutomapper for object transformation, we ended up with nice, slim controllers. Here is the “AccountsController.js” in its entirety.

	(function(c) {
		// include the views
		Ti.include("/views/Accounts/Default.js");
		Ti.include("/views/Accounts/Create.js");

		c.AccountsController = {
			/*
			 * Default action which simply shows a list of Accounts
			 */
			Default : function() {
				// use the dal as a repository to grab all accounts
				var accounts = dal.accounts.all();

				var model = AccountsViewModel();

				// automapper knows to map the two collections
				automapper.map("Account", AccountViewModel, accounts, model.accounts);

				// return the model and render the view
				return this.view("Default", model);
			},
			/*
			 * Basic create/update operation for a new Account
			 */
			Create : function(id) {
				var model = CreateAccountViewModel();

				if(id) {
					automapper.map("Account", "CreateAccountViewModel", dal.accounts.findOneById(id), model)
				}

				return this.view("Create", model);
			},
			/*
			 * Finishes up the creation/update process by inserting the object into the database
			 */
			CreateFinish : function(model) {
				var account;
				if(!model.id) {
					account = dal.accounts.newRecord();
				} else {
					account = dal.accounts.findOneById(model.id);
				}
				automapper.map("CreateAccountViewModel", "Account", model, account);
				account.save();
			},
			/*
			 * Delete an Account based on an id
			 */
			Delete : function(id) {
				dal.accounts.deleteRecords(id);
			}
		};
	}(Mvc.Controllers));

Accounts Views

The Accounts Views are much more advanced and paint a better picture on how to use the framework. First off is the “Default” View. This View allows CRUD on all Accounts. We will have a button to create new Accounts as well as a list of all Accounts that were previously created. This list allows you to select an Account for editing or deleting. This is accomplished by popping up an alert dialog with the options of “Edit”, “Delete”, and “Cancel”. So create an “Accounts” folder under “~/Resources/views” and create “Default.js” and “Create.js” javascript file under “~/Resources/views/Accounts”. Start off the view by creating its stub.

	(function(v) {
		// Create the 'Accounts' object if it doesn't already exist
		if(!v.Accounts) {
			v.Accounts = {};
		}
		v.Accounts.Default = function(model) {
		};
	}(Mvc.Views));

Next we can implement the “Default” function. I make a reference to the View as “self”. Next I create the view UI control in which we will house the rest of the controls. A button is then added to the view which has a click event which will navigate to the “Accounts.Create” action.

	var self = this;

		var view = Ti.UI.createView({
			backgroundColor : "#000"
		});

		// a button to add a new account
		var createButton = Ti.UI.createButton({
			title : "Create Account",
			top : 0,
			height: "10%"
		});

		createButton.addEventListener("click", function(e) {
			self.action("Create");
		});

		view.add(createButton);

Now that we have the create portion complete in this CRUD interface, we will implement the read portion. To do so I make a reference to the accounts passed through the View Model and start creating “TableViewRows” which are added to the collection. I give each row a property of “_id” which we will use when we want to update/delete any Account. Then I create simple “Alert” dialog — I will get to the implementation of the “click” event later. In the next portion of this code I create a table and populate it with the collection of rows. I also added a “click” event to the table in order to catch any click events on the table rows. I get the Account id I set in the row and assign it to the alert box. This will allow us to pass the id to the “AccountsController.Create” or “AccountsController.Delete” when we click one of the buttons in the “Alert” dialog. The last portion of the code is the “click” event for the “Alert” dialog. We use the index of our buttons to decide which action we wish to make when this event is fired. When someone clicks the delete button we call two actions. Since the “Delete” action does not return anything (Look at “AccountsController.Delete”), we know that no content should be displayed and that we shouldn’t open a new window. Right after that we call the “Accounts” action which resolves to “AccountsController.Default”. Since we are already displaying this window it simply refreshes the current page. This makes sense since we have now deleted one of the Accounts from the list.

var accounts = model.accounts,
			data = [];
		for(var i = 0; i < accounts.length; i += 1) {
			data.push(Ti.UI.createTableViewRow({
				title : accounts[i].fullName(),
				// used to store data in the row so we can update later
				_id : accounts[i].id
			}));
		}

		// alert so you can choose to edit or delete
		var alertDialog = Ti.UI.createAlertDialog({
			buttonNames : ["Edit", "Delete", "Cancel"],
			cancel : 2
		});

		var table = Ti.UI.createTableView({
			data : data,
			top : "10%",
			height: "90%"
		});

		// click event for updating a row
		table.addEventListener("click", function(e) {
			// get the id of the Account from the row
			var id = e.row._id;
			alertDialog._id = id;
			alertDialog.show();
		});

		alertDialog.addEventListener("click", function(e) {
			// get the id from the alert box set in the table click event
			var id = e.source._id;
			if(e.index === 0) {
				self.action("Create", id);
			} else if(e.index === 1) {
				self.action("Delete", id);
				self.action("Accounts");  // routing will resolve to Accounts.Default
			}
		});

		view.add(table);

		return view;

Here is the all the code for the View

(function(v) {
	// Create the 'Accounts' object if it doesn't already exist
	if(!v.Accounts) {
		v.Accounts = {};
	}
	v.Accounts.Default = function(model) {
		var self = this;

		var view = Ti.UI.createView({
			backgroundColor : "#000"
		});

		// a button to add a new account
		var createButton = Ti.UI.createButton({
			title : "Create Account",
			top : 0,
			height: "10%"
		});

		createButton.addEventListener("click", function(e) {
			self.action("Create");
		});

		view.add(createButton);

		var accounts = model.accounts,
			data = [];
		for(var i = 0; i < accounts.length; i += 1) {
			data.push(Ti.UI.createTableViewRow({
				title : accounts[i].fullName(),
				// used to store data in the row so we can update later
				_id : accounts[i].id
			}));
		}

		// alert so you can choose to edit or delete
		var alertDialog = Ti.UI.createAlertDialog({
			buttonNames : ["Edit", "Delete", "Cancel"],
			cancel : 2
		});

		var table = Ti.UI.createTableView({
			data : data,
			top : "10%",
			height: "90%"
		});

		// click event for updating a row
		table.addEventListener("click", function(e) {
			// get the id of the Account from the row
			var id = e.row._id;
			alertDialog._id = id;
			alertDialog.show();
		});

		alertDialog.addEventListener("click", function(e) {
			// get the id from the alert box set in the table click event
			var id = e.source._id;
			if(e.index === 0) {
				self.action("Create", id);
			} else if(e.index === 1) {
				self.action("Delete", id);
				self.action("Accounts");  // routing will resolve to Accounts.Default
			}
		});

		view.add(table);

		return view;
	};
}(Mvc.Views));

The last View we need to display is the Accounts "Create" View. This view is very straight forward and has only one major thing I need to talk about. If you haven't created a file for this, create a "Create.js" under "~/Resources/views/Accounts". Here is the source for the "Create" View.

	 (function(v) {
		// Create the 'Accounts' object if it doesn't already exist
	if(!v.Accounts) {
		v.Accounts = {};
	}
	Ti.include("/utils.js");

	/*
	 * Render the Create page
	 */
	v.Accounts.Create = function(model) {
		var self = this;

		var view = Ti.UI.createView({
			backgroundColor : "#777777",
			height: "100%"
		});

		var fnLabel = Ti.UI.createLabel({
			text : "First Name",
			top: "5%",
			height : "5%"
		});
		var fnTextField = Ti.UI.createTextField({
			width:'50%',
			top : "10%",
			height:"5%",
			backgroundColor: "#ffffff",
		    keyboardType:Ti.UI.KEYBOARD_DEFAULT,
		});
		model.firstName = utils.bind(fnTextField, model.firstName); // bind the textfield to the view model

		var lnLabel = Ti.UI.createLabel({
			text : "Last Name",
			top : "20%",
			height : "5%"
		});
		var lnTextField = Ti.UI.createTextField({
			width:'50%',
			top : "25%",
			height:"5%",
			backgroundColor: "#ffffff",
		    keyboardType:Ti.UI.KEYBOARD_DEFAULT,
		});
		model.lastName = utils.bind(lnTextField, model.lastName); // bind the textfield to the view model

		var emailLabel = Ti.UI.createLabel({
			text : "Email",
			top : "35%",
			height : "5%"
		});
		var emailTextField = Ti.UI.createTextField({
			width:'50%',
			top : "40%",
			height:"5%",
			backgroundColor: "#ffffff",
		    keyboardType:Ti.UI.KEYBOARD_DEFAULT,
		});
		model.email = utils.bind(emailTextField, model.email); // bind the textfield to the view model

		var submit = Ti.UI.createButton({top : "50%", height: "10%"});

		if(model.id) {
			submit.title = "Update";
		} else {
			submit.title = "Create";
		}

		submit.addEventListener("click", function() {
			self.action("CreateFinish", model);
			self.action("Accounts");  // routing will resolve to Accounts.Default
		});

		view.add(fnLabel);
		view.add(fnTextField);
		view.add(lnLabel);
		view.add(lnTextField);
		view.add(emailLabel);
		view.add(emailTextField);

		view.add(submit);

		return view;
	};
}(Mvc.Views));

The next thing you need to do is create a simple "utils.js" file. I plan on extending the functionality of this class to include many helper functions but for now, it just enables two-way binding of the View Models to the controls.

var utils = (function(app) {
	if(app.utils) {
		return app.utils;
	}
	app.utils = {
		/*
		 * Very basic databinding with an Appcelerator control.
		 */
		bind : function(control, value, fieldName) {
			var self=control;
			if(!fieldName) {
				fieldName = "value";
			}
			function setValue(val) {
				if(typeof val === "undefined") {
					val = "";
				}
				self[fieldName] = val;
			}
			setValue(value);
			return function(input) {
				if(!input) {
					return self[fieldName];
				}
				setValue(value);
			};
		}
	};
	return app.utils;
}(Ti.App));

Now that we have completed the AccountsController, let's set up the app so it navigates to the AccountsController by default. Open up app.js and change the last line of the file to Mvc.start("Accounts");

Run It!

That should be everything you need to run the application. This example application should be more than enough to get you going in developing your own application using my framework. As always leave any comments, suggestions, or bugs in my comments section.

Here is the Completed Example

UPDATE

Joel Brage was kind enough to port jsAutomapper to coffeescript. You can download it here

This week I plan on writing the more in-depth tutorial for using the framework so that should give some better examples on how to use the framework on a large application.

	Mvc.mapRoute(
		"Default_Route",
		"{controller}.{action}.{text}", // could also be {controller}/{action}/{id}
		{
			controller : "Home",
			action : "Default",
			text : "Default Text"
		});

The first parameter here is the name of the route. I use this only for keeping track of various routes incase you wish to override a previously defined route. The next parameter is the important part of the route. This is used to define what variables can be passed to an action. Anything that resides inside curly braces is considered a ‘variable’. The last parameter is an object which defines the default values to be used with the specified. So if we are targeting the default route and we do something like this (Note: Mvc.start is normally only called once in app.js but we can use it to see the various actions being hit):

	Mvc.start(); // resolves to "Home.Default" passing "Default Text" to the 'text' parameter of the action
	Mvc.start("Default"); // resolves to "Home.Default" passing "Default Text" to the 'text' parameter of the action
	Mvc.start("Accounts"); // resolves to "Accounts.Default" passing "Default Text" to the 'text' parameter of the action
	Mvc.start("Home.Foo"); // resolves to "Home.Foo" passing "Default Text" to the text parameter of the action
	Mvc.start("Accounts.Bar.Value"); // resolves to "Accounts.Bar" passing "Value" to the text parameter of the action
	Mvc.start("Accounts", "Foo", 2); // resolves to "Accounts.Default" passing "Foo" to the first parameter and 2 to the second parameter

After seeing that example you should have a basic idea of how the routing works. In general you should make a “default” catch-all route to make things easier to work with. Now lets add two more routes to make things interesting (Note: these routes need to be defined before the “Default_Route” as we will check for a match in them first).

	Mvc.mapRoute(
		"Specific_Route",
		"DeleteAccount.{id}",
		{
			controller : "Account",
			action : "Delete"
		});

	Mvc.mapRoute(
		"Account_Route",
		"Account.{action}.{id}",
		{
			controller : "Account",
			action : "Default",
		});

You can see that we have two entirely different routes that we have added. The first one is very specific and only has one variable. The “DeleteAccount” portion does not map to a controller. In this case we take advantage of the ‘default’ parameters listed in the third argument. In the next route, you can see that it is similar to the default route except we do not set the ‘controller’ as a variable. Here are some examples of these routes in action:

	Mvc.start("DeleteAccount.1"); // resolves to "Account.Delete" passing 1 to the 'id' parameter
	Mvc.start("DeleteAccount", 1); // resolves to "Account.Delete" passing 1 to the 'id' parameter
	Mvc.start("Account.Foo.1"); // resolves to "Account.Foo" passing 1 to the 'id' parameter
	Mvc.start("Account.Bar", 1); // resolves to "Account.Bar" passing 1 to the 'id' parameter

So that is the routing portion of my framework in a nutshell. Like I said, it might be overkill but I am really enjoying how easy it is to get from window to window. In my next post I will show a “real world” example of using my framework. It will include joli, jsAutomapper, and some databinding. It basically shows how I set up my project and use the framework. Anyway, leave your comments/suggestions.

I searched around the internet and found a few solutions. Some people were using PureMvc or similar frameworks. I read through the documentation and the frameworks were either too complex for my needs or may have felt out of place when used with Appcelerator. I did find something close to what I wanted by Scott Montgomerie. My issues with his implementation was that you constantly have to deal with the current window context and you are coupling your views with your controllers. I also like to stay away from the ‘new’ keyword when working with javascript. In addition I wanted routing as I am used to the MVC style of Asp.Net MVC (may be overkill but it was nice to have). It’s what I know and I love it .

Before I get started here is the working example. Keep in mind this has only been tested on Android in my Windows environment and probably needs a bit more testing so this release is just an Alpha.

So with my implementation I wanted to keep things very simple and try to stay away from coupling the framework to Appcelerator. I also wanted routing so I could simply write code that evaluates to, ”Go to the default view for the current controller.” This led me to a framework with the following setup:

For setting up the framework I have:

• Mvc.init – This is called to setup the framework. It initializes and extends all controllers
  and views.
• Mvc.mapRoute – This sets up your default routes and is used internally by the routing engine.
• Mvc.render – This is a callback function which is invoked after a view has been rendered.
  Using this approach we can decouple the Mvc framework from Appcelerator and possibly use in
  some other context. In the case of Appcelerator, I used this function for window management.
• Mvc.find – You shouldn’t ever need to use this but I exposed it just in case. This will find
  your route based on a path.
• Mvc.start – After everything is set up, this must be called to render the default action. This
  will make much more sense after my example.

For each controller I simply have:

• name – The name of the view you want to render.
• view – A function that takes the parameters of “action” and “model”. The action being the
  view you wish to render and the model used to render the view.

For each view I have the following functions:

• action – When you pass a path to this function and possibly a value or model, this will invoke
  an action on a controller and return a rendered view.
• partial – This simply takes whatever path you pass in and returns a view. This does not invoke
  the action for the route so in some cases you may have a view without an action.

That right there is the entire framework. It is very simple and easy to use. It also abstracts a ton of the work you have to go through in order to manage your project. Next I’ll go through how to use the framework with sample code.

The first thing we need to do is grab the mvc code. This is all home-grown except for some regular expressions I borrowed and modified from jsRouter. Save this as ‘mvc.js’. Here it is:

		var Mvc = (function ($) {

			if($.mvc) {
				return $.mvc; // do not reinitialize
			}

			var getRouteCollection;

			function extend() {
				var destination = arguments[0], source;
				for(var i = 1; i < arguments.length; i += 1) { 					source = arguments[i]; 					for (var property in source) { 						if (typeof source[property] === "object" && 							source[property] !== null ) { 							destination[property] = destination[property] || {}; 							arguments.callee(destination[property], source[property]); 						} else if(destination && source[property]) { 							destination[property] = source[property]; 						} 					} 				} 				return destination; 			} 			 			function isEmptyObject(obj) { 				for(var prop in obj) { 					if (Object.prototype.hasOwnProperty.call(obj, prop)) { 						return false; 					} 				} 				return true; 			} 			 			// via jsRouter with some modifications -- http://jsrouter.codeplex.com/ 			function buildRegExp(route) { 				// converts the route format into a regular expression that would match matching paths 				var pathSegments = route.path.replace(/[\/\.]+$/, '').split(/\/|\./), 					defaults = route.defaults; 				var regexp = ['^']; 				for (var i = 0, segment, match; (segment = pathSegments[i]) !== undefined; i++) { 					if ((match = /{(\w+)}/.exec(segment)) != null) { 						var argName = match[1]; 						// add a backslash, except for the first segment 						regexp.push((i > 0 ? '(\/' : '') + '([^\/]+)' + (i > 0 ? ')' : ''));

						if (defaults && defaults[argName] !== undefined) {
							// make the group optional if the parameter has a default value
							regexp.push('?');
						}
					}
					else {
						regexp.push((i > 0 ? '/' : '') + segment);
					}
				}
				regexp.push('$');

				return new RegExp(regexp.join(''), 'i');
			}

			function parsePath(path, route) {
				// parses the values in the hash into an object with the keys the values specified in the given route
				var values = extend({}, route.defaults),
					pathSegments = path.split(/\/|\./);

				for (var i = 0, segment, match; i < pathSegments.length && (segment = route.segments[i]); i++) {
					if ((match = /{(\w+)}/.exec(segment)) != null) {
						if (pathSegments[i] == '' && values[match[1]]) {
							continue; // skip empty values when the value is already set to a default value
						}
						values[match[1]] = pathSegments[i];
					}
				}
				return values;
			}

			// The base controller -- all controllers under Mvc.Controllers will get these properties
			function Controller(name) {
				return {
					name : name,
					view : function(action, model) {
						return {
							action : action, // either foo/bar/1, foo.bar.1 or {controller : 'foo', action : 'bar', id : '1'}
							model : model
						};
					}
				};
			}

			$.mvc = {
				Controllers: {}, // object to hold all controllers -- used in initialization
				Views : {}, // object to hold all views
				init : function(options) {
					var ctrlrs = this.Controllers, controller, views = this.Views;

					// set up controllers
					for(var key in ctrlrs) {
						if(!ctrlrs.hasOwnProperty(key)) {
							continue;
						}

						// make sure this is actually a Controller
						if(key.indexOf("Controller") === -1) {
							ctrlrs[key] = null;
							continue;
						}

						// extend the controller to include the properties from baseController
						ctrlrs[key] = extend(ctrlrs[key], Controller(key));
					}

					var self = this;
					self.process = function(route, data) {
						var r = self.find(route), createdObject = false;
						if(!r) {
							throw "Could not find any routes. Register routes via Mvc.mapRoute";
						}

						// set the routeData in sharedData
						rc.context.routeData = extend({}, r.routeData);

						if(!data && data !== false) {
							data = {};
							createdObject = true;
						}

						// only extend the data object if it is already a complex object
						if(!isEmptyObject(data)) {
							data = extend(data, r.routeData);
						}

						var rd = r.routeData;
						delete data["controller"];
						delete data["action"];				

						if(createdObject && isEmptyObject(data)) {
							data = null;
						}

						var cname = rd.controller + "Controller", controller = self.Controllers[cname];
						if(!controller) {
							throw "Controller " + cname + " has not been defined";
						}
						if(!controller[rd.action]) {
							throw "Action " + rd.action + " in controller " + cname + " does not exist";
						}
						var view = controller[rd.action].call(controller, data);

						if(!view) {
							// we didn't need to show anything
							return;
						}

						return self._render(view.action, view.model);
					};

					self._render = function(route, data, partial) {
						var r = self.find(route);
						if(!r) {
							throw "Could not find any routes. Register routes via Mvc.mapRoute";
						}
						var cname = r.routeData.controller, vname = r.routeData.action;
						if(!self.Views[cname]) {
							throw "View Controller " + cname + " does not exist in Views collection";
						}
						if(!self.Views[cname][vname]) {
							throw "View " + vname + " does not exist in View Controller " + cname;
						}
						var renderOutput = self.Views[cname][vname](data);
						if(!partial && self.render) {
							renderOutput = self.render(renderOutput, r.routeData);
						}
						return renderOutput;
					};
					self._partial = function(route, data) {
						// tell the render function that this is a partial render and we should not call
						// the user defined render function
						return self._render(route, data, true);
					}

					// setup the views so they have an 'action' method
					for(var key in views) {
						if(!views.hasOwnProperty(key)) {
							continue;
						}
						views[key].action = self.process;
						views[key].partial = self._partial;
					}

					var rc = this.sharedData = {
						routes : [],
						context : {
							routeData : {
								controller : null,
								action : null
							}
						}
					};
				},
				mapRoute : function (name, path, defaults) {
					var scrubbedPath = path.substr(path.indexOf('{'));

					// get rid of slashes
					if(scrubbedPath[0] === '/') {
						scrubbedPath = scrubbedPath.substring(1, scrubbedPath.length - 1);
					}
					if(scrubbedPath[scrubbedPath.length - 1] === '/') {
						scrubbedPath = scrubbedPath.substr(scrubbedPath.length - 2);
					}

					this.sharedData.routes.push({
						name : name,
						path : path,
						defaults: defaults
					})
				},
				find: function (path) {
					var routes = this.sharedData.routes,
						ctrlrs = this.Controllers,
						context = this.sharedData.context;

					if(!path) {
						path = "";
					}

					// check for match
					for (var i = 0, route; i < routes.length; i++) { 						route = routes[i]; 						if (!route.regexp) { // generate regexps on the fly and cache them for the future 							route.regexp = buildRegExp(route); 							route.segments = route.path.split(/\/|\./); 						} 						var isMatch = route.regexp.test(path); 						if (isMatch) { 							// route found, parse the route values and return an extended object 							 							// populate last controller if it doesn't exist with default 							if(!context.routeData.controller) { 								context.routeData.controller = route.defaults.controller; 							} 							 							// check current controller for match -- takes care of simply passing an action 							var ctrlr = context.routeData.controller + "Controller"; 							var useLastController = ctrlrs[ctrlr] && 													ctrlrs[ctrlr][path];  							 							var routeData = extend({}, context.routeData); 							if(useLastController) { 								var pathSegments = path.split(/\/|\./), iter = 1; 								routeData.action = pathSegments[0]; 								for(var key in routeData) { 									if(!routeData.hasOwnProperty(key)) { 										continue; 									} 									if(key === "controller" || key === "action") { 										continue; 									} 									 									if(iter >= pathSegments.length) {
										break;
									}

									routeData[key] = pathSegments[iter];
									iter += 1;
								}
							} else {
								routeData = parsePath(path, route);
							}

							return extend({}, route, { routeData : routeData });
						}
					}
					return null;
				},
				start : function (route, data) { // parameters in case we want to start the app with something other than the default page
					this.process(route, data);
				}
			};

			return $.mvc;
		}(Titanium.App));

The next thing you need to do is erase everything in your app.js file. This file will be the setup/initialization code for the project. We will add the following code.

		// include a reference to the mvc file
		Ti.include('mvc.js'); 

		// This doesn't exist yet but we'll get to that next
		Ti.include('/controllers/HomeController.js');

		// Initializes the framework
		Mvc.init(); 

		// map a default route
		Mvc.mapRoute(
			"Default_Route",
			"{controller}.{action}.{id}", // could also be {controller}/{action}/{id}
			{
				controller : "Home",
				action : "Default",
				id : null
			});

		// we'll get into this in a bit.
		Mvc.render = function(ui, routeData) { } 

		// This will go off and attempt to render the default route but will
		// fail since we have not created the 'Home' controller yet
		Mvc.start();

Now I will actually implement the Mvc.render function in app.js. This is super specific to how I want my app to manage windows. It should work for you as well but you may want to customize/improve this code.

	// manage the windows -- window stack
	var openWindows = [];

	Mvc.render = function(ui, routeData) {
		var win, index, routeName = routeData.controller + "." + routeData.action;

		// find the index in the stack of windows
		for(var i = openWindows.length - 1; i >= 0; i -= 1) {
			if(openWindows[i]._title === routeName) {
				win = openWindows[i];
				index = i + 1;
				break;
			}
		}
		function cleanup(index) {
			for(var i = index; i < openWindows.length; i += 1) {
				openWindows[i].close();
				openWindows[i] = null;
			}
			openWindows = openWindows.splice(0, index);
		}
		// if the window already exists in the stack
		if(win) {
			// clean up array -- remove all windows
			cleanup(index);

			// remove children from current view
			var children = win.children;
			for(var i = 0; i < children.length; i += 1) { 				win.remove(children[i]) 			} 		} else { 			// create a new window 			win = Ti.UI.createWindow({  				_title : routeName, 				fullscreen : true 			}); 			 			win.addEventListener('close', function() { 				// find the index of this window so we can remove it when the back button is pressed 				for(var i = openWindows.length - 1; i >= 0; i -= 1) {
					if(openWindows[i]._title === routeName) {
						index = i;
						break;
					}
				}
				cleanup(index);
			});

			// This handles the creation of the first window so that
			// Appcelerator will exit your app when this window is closed.
			if(openWindows.length === 0) {
				win.exitOnClose = true;
			}

			openWindows.push(win);
			win.open();
		}

		// This adds the controls you created in your view
		win.add(ui);

		// return the window in case you need it for something in your view
		return win;
	};

That right there is all the code you need to get going. Next we need to actually implement the ‘HomeController’. So create a file called ‘HomeController.js’ inside a ‘controllers’ folder and add the following code:

		// This will be the location for the 'Default' view
		Ti.include('/views/Home/Default.js');
		// another view
		Ti.include('/views/Home/DoStuff.js');

		(function(c) {
			// This is just a basic model used to render
			// the 'Default' view.
			function DefaultModel() {
				return {
					text : null,
					value : 0
				};
			}
			// Initializes the 'HomeController' in Mvc.Controllers
			c.HomeController = {
				Default : function() {
					// Create the model and populate it with some values
					var model = DefaultModel();
					model.text = "Sample Text";
					model.value = "Sample value";

					// This returns a view and tells the framework to render the
					// 'Default' view using the model we created.
					return this.view('Default', model);
				},
				// we could add another action here
				DoStuff : function (value) {
					// manipulate the value parameter and return the appropriate view
					return this.view('DoStuff', value + "!!!");
				}
			};
		}(Mvc.Controllers));

Next we need to implement our view. This is a very simple and similar process to creating Controllers. Create a ‘views’ folder and then a ‘Home’ folder.

		(function(v) {
			// Create the 'Home' object if it doesn't already exist
			// This is used by the routing engine to assosciate the
			// view with the correct controller
			if(!v.Home) {
				v.Home = {};
			}

			/*
			 * Render the default page
			 */
			v.Home.Default = function(model) {
				// get a reference to the view
				var self = this;

				var view = Ti.UI.createView({layout : "vertical"});
				var label = Ti.UI.createLabel({
					text : model.text
				});
				var textField = Ti.UI.createTextField({
					value : model.value
				});
				var button = Ti.UI.createButton({
					title : "Submit"
				});

				// This will call DoStuff
				button.addEventListener("click", function(e) {
					self.action("DoStuff", textField.value);
				});
				view.add(label);
				view.add(textField);
				view.add(button);

				return view;
			};
		}(Mvc.Views));

Lastly we create the ‘DoStuff’ view which is nearly the same as the ‘Default’ view.

		(function(v) {
	// Create the 'Home' object if it doesn't already exist
	if(!v.Home) {
		v.Home = {};
	}

	/*
	 * Render the DoStuff page
	 */
	v.Home.DoStuff = function(model) {
		var view = Ti.UI.createView({
			layout : "vertical",
			backgroundColor : "#fff"
		});
		var label = Ti.UI.createLabel({
			text : model,
			color : "#000"
		});

		view.add(label);

		return view;
	};
}(Mvc.Views));

That is my MVC framework in a nutshell although this only shows the basic functionality. In my next post I will expand on this example and integrate model-binding, jsAutomapper, and using joli for data access. I will also focus on the routing portion of my framework and how to do some more advanced things with it. I think this framework is stupidly simple and really allows for SOC as well as forcing you to write better code. If you have any comments/suggestings/bugs feel free to leave them here.

Anyway, you can download the working project HERE

The automapper javascript implementation:

var automapper = (function (app) {
	if(app.automapper) {
		return app.automapper;
	}

	var dictionary = {};

	app.automapper = {
		createMap : function (sourceKey, destinationKey) {
			var combinedKey = sourceKey + destinationKey, functions;
			dictionary[combinedKey] = {};

			functions = {
				forMember : function (key, e) {
					dictionary[combinedKey][key] = e;
					return functions;
				},
				forAllMembers : function(func) {
					dictionary[combinedKey].__forAllMembers = func;
					return functions;
				}
			};
			return functions;
		},
		map : function (sourceKey, destinationKey, sourceValue, destinationValue, lazy) {
			if(!sourceValue && sourceValue !== false) {
				return;
			}

			function getValue(item) {
				if(typeof item === "function" && !lazy) {
					return item();
				}
				return item;
			}
			var combinedKey = sourceKey + destinationKey;
			var mappings = dictionary[combinedKey], output, key,
				    extensions = {
						ignore : function () {
							// don't do anything
						},
						mapFrom : function (sourceMemberKey) {
							if (!this.__sourceValue.hasOwnProperty(sourceMemberKey)) {
								throw sourceKey + "." + sourceMemberKey + " has not been defined.";
							}
							var value = getValue(this.__sourceValue[sourceMemberKey]);
							if(mappings.__forAllMembers) {
								mappings.__forAllMembers(this.__destinationValue, this.__key, value);
							} else {
								this.__destinationValue[this.__key] = value;
							}
						}
					};

			if(!mappings) {
				throw "Could not find mapping with a source of " + sourceKey + " and a destination of " + destinationKey;
			}

			function mapItem(destinationValue, sourceValue) {
				for (key in destinationValue) {
					if (!destinationValue.hasOwnProperty(key)) {
						continue;
					}			

					if (mappings.hasOwnProperty(key) && mappings[key]) {
						if (typeof mappings[key] === "function") {
							extensions.__key = key;
							extensions.__sourceValue = sourceValue;
							extensions.__destinationValue = destinationValue;

							output = mappings[key].call(extensions);
						} else {  // forMember second parameter was not a function
							output = mappings[key];
						}
						// object was returned from the 'forMember' call
						if (output) {
							var value = getValue(output);
							if(mappings.__forAllMembers) {
								mappings.__forAllMembers(destinationValue, key, value);
							} else {
								destinationValue[key] = value;
							}
						}
					}
					else if (!sourceValue.hasOwnProperty(key)) {
						throw sourceKey + "." + key + " has not been defined.";
					} else {
						var value = getValue(sourceValue[key]);
						if(mappings.__forAllMembers) {
							mappings.__forAllMembers(destinationValue, key, value);
						} else {
							destinationValue[key] = value;
						}
					}
				}
			}

			// actually do the mapping here
			if(sourceValue instanceof Array) {
				if(destinationValue instanceof Array) {
					// loop
					for(var i = 0; i < sourceValue.length; i += 1) {
						if(!destinationValue[i]) {
							if(typeof destinationKey !== "function") {
								throw "destinationKey of mapping must be a function in order to initialize the array";
							}
							destinationValue[i] = destinationKey();
						}
						mapItem(destinationValue[i], sourceValue[i]);
					}
				} else {
					throw "Cannot map array to object";
				}
			}
			else if(destinationValue instanceof Array) {
				throw "Cannot map object to array";
			} else {
				mapItem(destinationValue, sourceValue);
			}
		}
	};

	return app.automapper;
}(this));

Usage:

var atest = {
	same : 10,
	bleh : 4
};
var btest = {
	dumb: null,
	func: null,
	foo : null,
	bar : null,
	same : null
};
/*
*  call 'createMap' where "a" and "b" are the name of your
*  models.  These values can be whatever you want but you
*  must match the values when you call 'map'.
*/
automapper.createMap("a","b")
	   // forAllMembers isn't necessary here but it allows you to
	   // customize how you apply values to the destination model
	  .forAllMembers(function(model, prop, value) {
		model[prop] = value;
	  })
	  .forMember("dumb", 12)
	  .forMember("func", function() { return 8 })
	  .forMember("foo", function() { this.ignore(); })
	  .forMember("bar", function() { this.mapFrom("bleh"); });

automapper.map("a", "b", atest, btest);

Leave any suggestions or bug-fixes in the comments. Thanks.

UPDATE

Joel Brage was kind enough to port jsAutomapper to coffeescript. You can download it here

using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;

namespace Common.Collections
{
    public class SortedBucketList<TKey, TValue> : IDictionary<TKey, TValue>
    {
        /// <summary>
        /// This stores the first key and first value added to the collection.
        /// </summary>
        private readonly SortedList<TKey, TValue> _sort;
        /// <summary>
        /// The value of this is used to reference the first KeyValuePair stored in the SortedList
        /// </summary>
        private readonly Dictionary<TValue, TKey> _bucket;

        public SortedBucketList()
        {
            _sort = new SortedList<TKey, TValue>();
            _bucket = new Dictionary<TValue, TKey>();
        }

        public SortedBucketList(IComparer<TKey> comparer)
        {
            _sort = new SortedList<TKey, TValue>(comparer);
            _bucket = new Dictionary<TValue, TKey>();
        }
        public SortedBucketList(IDictionary<TKey, TValue> dictionary)
        {
            _sort = new SortedList<TKey, TValue>(dictionary);
            _bucket = new Dictionary<TValue, TKey>();
            foreach (var value in dictionary)
            {
                _bucket.Add(value.Value, value.Key);
            }
        }
        public SortedBucketList(int capacity)
        {
            _sort = new SortedList<TKey, TValue>(capacity);
            _bucket = new Dictionary<TValue, TKey>(capacity);
        }
        public SortedBucketList(IDictionary<TKey, TValue> dictionary, IComparer<TKey> comparer)
        {
            _sort = new SortedList<TKey, TValue>(dictionary, comparer);
            _bucket = new Dictionary<TValue, TKey>();
            foreach (var value in dictionary)
            {
                _bucket.Add(value.Value, value.Key);
            }
        }
        public SortedBucketList(int capacity, IComparer<TKey> comparer)
        {
            _sort = new SortedList<TKey, TValue>(capacity, comparer);
            _bucket = new Dictionary<TValue, TKey>(capacity);
        }
        public void Add(TKey key, TValue value)
        {
            if (!_sort.ContainsKey(key))
            {
                _sort.Add(key, value);
            }
            _bucket[value] = key;
        }
        public void Clear()
        {
            _sort.Clear();
            _bucket.Clear();
        }
        public bool ContainsKey(TKey key)
        {
            return _sort.ContainsKey(key);
        }
        public bool ContainsValue(TValue value)
        {
            return _bucket.ContainsKey(value);
        }

        public int IndexOfKey(TKey key)
        {
            return _sort.IndexOfKey(key);
        }
        public int IndexOfValue(TValue value)
        {
            TKey key;
            if (_bucket.TryGetValue(value, out key))
            {
                return _sort.IndexOfKey(key);
            }
            return -1;
        }

        public bool Remove(TKey key)
        {
            if (!_sort.Remove(key))
                return false;
            RemoveFromBucket(key);
            return true;
        }
        public void RemoveAt(int index)
        {
            var item = _sort.ElementAt(index);
            _sort.RemoveAt(index);
            RemoveFromBucket(item.Key);
        }

        private void RemoveFromBucket(TKey key)
        {
            var del = new List<TValue>();
            foreach (var kvp in _bucket)
            {
                if (kvp.Value.Equals(key))
                {
                    del.Add(kvp.Key);
                }
            }
            foreach (var item in del)
            {
                _bucket.Remove(item);
            }
        }

        ICollection<TKey> IDictionary<TKey, TValue>.Keys
        {
            get { return _bucket.Values; }
        }

        public bool TryGetValue(TKey key, out TValue value)
        {
            throw new NotImplementedException();
        }

        public ICollection<TValue> Values
        {
            get { return _bucket.Keys; }
        }

        TValue IDictionary<TKey, TValue>.this[TKey key]
        {
            get
            {
                throw new NotImplementedException();
            }
            set
            {
                throw new NotImplementedException();
            }
        }

        public IEnumerable<TValue> this[TKey key]
        {
            get
            {
                var output = new List<TValue>();

                //_bucket.EachParallel(kvp =>
                //                         {
                //                             if (kvp.Value.Equals(key))
                //                             {
                //                                 output.Add(kvp.Key);
                //                             }
                //                         });
                //output.AddRange(from kvp in _bucket where kvp.Value.Equals(key) select kvp.Key);
                foreach (var kvp in _bucket)
                {
                    if (kvp.Value.Equals(key))
                    {
                        output.Add(kvp.Key);
                    }
                }
                return output;
            }
            set
            {
                if (value == null)
                    return;
                if (!_sort.ContainsKey(key))
                {
                    _sort[key] = value.ElementAt(0);
                }
                foreach (var el in value)
                {
                    _bucket[el] = key;
                }
            }
        }

        void ICollection<KeyValuePair<TKey, TValue>>.Add(KeyValuePair<TKey, TValue> item)
        {
            Add(item.Key, item.Value);
        }

        void ICollection<KeyValuePair<TKey, TValue>>.Clear()
        {
            _sort.Clear();
            _bucket.Clear();
        }

        bool ICollection<KeyValuePair<TKey, TValue>>.Contains(KeyValuePair<TKey, TValue> item)
        {
            return ContainsKey(item.Key) && ContainsValue(item.Value);
        }

        void ICollection<KeyValuePair<TKey, TValue>>.CopyTo(KeyValuePair<TKey, TValue>[] array, int arrayIndex)
        {
            throw new NotImplementedException();
        }

        int ICollection<KeyValuePair<TKey, TValue>>.Count
        {
            get { return _sort.Count; }
        }

        bool ICollection<KeyValuePair<TKey, TValue>>.IsReadOnly
        {
            get { throw new NotImplementedException(); }
        }

        bool ICollection<KeyValuePair<TKey, TValue>>.Remove(KeyValuePair<TKey, TValue> item)
        {
            throw new NotImplementedException();
        }

        IEnumerator<KeyValuePair<TKey, TValue>> IEnumerable<KeyValuePair<TKey, TValue>>.GetEnumerator()
        {
            return _sort.GetEnumerator();
        }

        void IDictionary<TKey, TValue>.Add(TKey key, TValue value)
        {
            Add(key, value);
        }

        bool IDictionary<TKey, TValue>.ContainsKey(TKey key)
        {
            return ContainsKey(key);
        }

        bool IDictionary<TKey, TValue>.Remove(TKey key)
        {
            throw new NotImplementedException();
        }

        bool IDictionary<TKey, TValue>.TryGetValue(TKey key, out TValue value)
        {
            return _sort.TryGetValue(key, out value);
        }

        ICollection<TValue> IDictionary<TKey, TValue>.Values
        {
            get { return _bucket.Keys; }
        }

        IEnumerator IEnumerable.GetEnumerator()
        {
            throw new NotImplementedException();
        }
    }
}

The first thing you need to do is check out the documentation and follow each step of the lessons. It is also very helpful if you watch the video talks and at least skim all the reference material on this page. The main thing to take note of here is the xml. I would say it is the core of what makes the PushButton Engine so powerful.

So now that you are up to speed with the basics, you want to actually start modularizing the code and going beyond what was in the lessons. This was a sticking point for me as I had a complete misunderstanding of how the PBE was supposed to be used. As I started trying to break up the code from the lesson, I immediately moved the ‘createHero’ function into its own class. As I learned from a long chat on the PushButton IRC channel, this is not the correct way. You need to use Templates in Level Xml or
Templates. Since I am just prototyping at this point I chose to use a template as a function. I moved the ‘createHero’ code from out of my class (which should have never been used) into a static factory class where I will create/initialize all entities. As this is a prototype I don’t feel too bad for doing this although for any large project, using xml templates
is definitely the way to go. For this prototype I will be making a simple platform game with mouse navigation.

So now without further ado, we have some code .  Here is the main function.

public function Main():void
{
    PBE.startup(this);

    var sceneView:SceneView = new SceneView();
    sceneView.width = 700;
    sceneView.height = 400;
    PBE.initializeScene(sceneView);

    PBE.defineEntityByFunction("Hero", EntityFactory.CreateHero);

    PBE.makeEntity("Hero");
}

As you can see, it is very similar to what was in the PushButton example. The only difference here is that instead of calling EntityFactore. CreateHero explicitly, we call PBE.makeEntity which resolves the correct function (I am assuming using a dictionary but I didn’t look at the source). This is a much cleaner solution because it allows us to swap out the CreateHero function with something else if we really need to throughout the prototype – although if it gets that involved then perhaps it is time to start using xml templates.

The next bit of code is the EntityFactory.CreateHero

public static function CreateHero():IEntity
{
    var entity:IEntity = PBE.allocateEntity();
    entity.initialize("Hero");

    var positionProperty:PropertyReference = new PropertyReference("@Spatial.position");

    var spatial:SimpleSpatialComponent = new SimpleSpatialComponent();
    var render:MovieClipRenderer = new MovieClipRenderer();
    var controller:MouseControllerComponent = new MouseControllerComponent();

    spatial.position = new Point(0, 0);
    spatial.size = new Point(50, 90);
    spatial.spatialManager = PBE.spatialManager;

    render.clip = new Static(); // Something my art guy gave me
    render.frameRate = 60;
    render.loop = true;
    render.positionOffset = new Point(-50, -90);
    render.positionProperty = positionProperty;
    render.rotationProperty = new PropertyReference("@Spatial.rotation");
    render.scene = PBE.scene;

    controller.PositionProperty = positionProperty;

    entity.addComponent(spatial, "Spatial");
    entity.addComponent(render, "Render");
    entity.addComponent(controller, "Controller");

    return entity;
}

Take note of the line entity.initialize(“Hero”). The identifier “Hero” can only be used once. PBE uses this identifier in PropertyReferences in order to find component properties of entities. Since I named the entity “Hero” I can get to its spatial ‘position’ property by using the string ”#Hero.Spatial.position” in the property reference. You can see an example of this later on in the post. I use a MovieClipRenderer to render an animation for my character. In the future I will be changing this to use an AnimatorComponent but that is for a later post. Also, I have not created a physics component which I will need to do later. For now I am just trying to get things animating

So for my prototype I am making a character which uses the mouse for navigation. I am replacing the mouse cursor with an arrow graphic that always points away from the character and grows/shrinks depending on the distance from the character.

So now I add two lines to the main function to create this arrow.

public function Main():void
{
    PBE.startup(this);

    var sceneView:SceneView = new SceneView();
    sceneView.width = 700;
    sceneView.height = 400;
    PBE.initializeScene(sceneView);

    PBE.defineEntityByFunction("Hero", EntityFactory.CreateHero);
    PBE.defineEntityByFunction("Arrow", EntityFactory.CreateArrow);

    PBE.makeEntity("Hero");
    PBE.makeEntity("Arrow");
}

So I bind the EntityFactore.CreateArrow function and then make the entity. Here is the code for EntityFactory.CreateArrow.

public static function CreateArrow():IEntity
{
    var entity:IEntity = PBE.allocateEntity();
    entity.initialize();

    var positionProperty:PropertyReference = new PropertyReference("@Spatial.position");
    var rotationProperty:PropertyReference = new PropertyReference("@Spatial.rotation");

    var spatial:SimpleSpatialComponent = new SimpleSpatialComponent();
    var render:MovieClipRenderer = new MovieClipRenderer();
    var controller:ArrowControllerComponent = new ArrowControllerComponent();

    spatial.position = new Point(0, 0);
    spatial.size = new Point(40, 50);
    spatial.spatialManager = PBE.spatialManager;

    render.clip = new Default(); // Default arrow
    render.frameRate = 60;
    render.loop = true;
    render.positionProperty = positionProperty;
    render.rotationProperty = rotationProperty;
    render.scene = PBE.scene;

    controller.PositionProperty = positionProperty;
    controller.RotationProperty = rotationProperty;
    controller.ScaleProperty = new PropertyReference("@Render.scale");

    entity.addComponent(spatial, "Spatial");
    entity.addComponent(render, "Render");
    entity.addComponent(controller, "Controller");

    return entity;
}

As you can see, this time when I call entity.initialize I do not pass in an identifier. In this case I do no really need an identifier but if you were doing something such as creating bullet entities where you would have more than one created at a time, you would need to do this since the identifier would clash and PBE would complain. Other than that, this function is very similar to the EntityFactory.CreateHero function.

The next thing I have to worry about is actually moving the arrow with the mouse. For that I created the ArrowControllerComponent.

public class ArrowControllerComponent extends TickedComponent
{
    public var PositionProperty:PropertyReference;
    public var RotationProperty:PropertyReference;
    public var ScaleProperty:PropertyReference;

    private var _heroSpatialProperty:PropertyReference = new PropertyReference("#Hero.Spatial.position");

    public static const MINDISTANCE:Number = 200;
    public static const MAXDISTANCE:Number = 300;

    override public function onTick(deltaTime:Number):void
    {
        owner.setProperty(
            PositionProperty,
                new Point(
                    PBE.mainStage.mouseX - .5 * PBE.scene.sceneView.width,
                    PBE.mainStage.mouseY - .5 * PBE.scene.sceneView.height));

        var position:Point = owner.getProperty(PositionProperty) as Point;

        var charPosition:Point = owner.getProperty(_heroSpatialProperty) as Point;
        var difference:Point = position.subtract(charPosition);

        var scale:Number = 1 + Math.max((Math.min(difference.length, MAXDISTANCE) - MINDISTANCE) / (MAXDISTANCE - MINDISTANCE), 0);
        trace(scale);
        owner.setProperty(
            ScaleProperty,
                new Point(1, scale));

        owner.setProperty(
        RotationProperty,
        Math.atan2(difference.y, difference.x) * 57.32 + 90);
    }
}

So in this class I have four PropertyReferences. The first three are instantiated by the EntityFactory.CreateArrow function when creating that entity. The private _heroSpatialProperty is set and cached so it does not have to find the property each time onTick is called. Doing this is crucial when using PBE because the PropertyReference class is a beast. I looked through the source code a bit and if you do not use the PropertyReference correctly, your project will definitely take a huge performance hit. Anyways, as you can see I use the “#Hero.Spatial.position” to resolve the hero’s position not ”#Hero.@Spatial.position” which was a mistake I made and took a while to figure out. The next bits of code is just doing math stuff in order to properly position the arrow at the correct cordinates — mouseX is using the flash coordinates where (0,0) is in the top left while the rest of PBE assumes (0,0) is in the center of the stage/box. I am assuming this is to make integration with Box2D make more sense…

Well, that is all for now. I will be posting the entire source of this prototype when I am finished with everything. I will keep posting updates as I move along. Next up the
AnimatorComponent and SpriteSheets (or however I figure out how to render movie clips with a state machine).

(function ($) {
    $.mvcname = function (json) {
        function recurseJson(json, parentID, parentName) {
            for (var key in json) {
                var item = json[key];
                var id = key, name = key;
                if(parentID){
                    id = parentID + "__" + id;
                }
                if(parentName) {
                    name = parentName + "." + name;
                }

                if($.isArray(item)) {
                for(var i = 0; i < item.length; i++) {
                    item[i] = recurseJson(item[i], id + "_" + i, name + "[" + i + "]");
                }
            } else {
                json[key] = {
                value: recurseJson(item, id, name),
                id: id,
                name: name
                };
            }
        }
        return json;
    }
    return recurseJson(json);
    };
}(jQuery));

So if you pass in some json that looks like:

var json = {
    foo: {
        a: "text",
        b: 1
    },
    bar: [
        {
            c: [2,3,4],
            d: "abc"
        },
        {
            c: [5,7,9]
            d: "text",
        }
    ]
};
$.mvcname(json);

You will end up with something like:

json = {
    foo: {
        value: {
            a: "text",
            b: 1
        },
        name: "foo",
        id: "foo"
    },
    bar: [
        {
            c: {
                value: [2,3,4],
                name: "bar[0].c",
                id: "bar_0__c"
            },
            d: {
                value: "abc",
                name: "bar[0].d",
                id: "bar_0__d"
            }
        },
        {
            c: {
                value: [5,7,9,11],
                name: "bar[1].c",
                id: "bar_1__c"
            },
            d: {
                value: "def",
                name: "bar[1].d",
                id: "bar_1__d"
            }
        }
    ]
};

Quite possibly a useless plugin but have fun…