DOCS

EXC | DEV | Documentation

Controller

A controller is an object responsible of handling requests or events. In EXC we use controllers to implement the logic of our application.

A controller is a plain javascript object that EXC decorates with new functionality to become a full fledge controller. What makes it special is the functions that we place inside our controller object.

The execution of your application is in essence your code responding to events and messages. We respond to events by adding event handlers, which are nothing more than functions in a controller object.

An event may be raised by actions, by DOM events, by your code, or by EXC itself. The great thing of controllers is that they make it super easy to decouple your application logic using events.

Similar to event handlers a controller can receive messages. The basic difference is that while in an event your controller is reacting, in a message your controller is told to perform something. You can think of message as just a way to invoking a function on your controller.

Once again a message handler is nothing more than a function with a name that matches the message name. EXC provides some easy ways to invoke messages and attach them to DOM events.

Adding event handlers

An event handler is a function, who's name follows a simple naming convention (an event handler signature).

A function name that starts with "on" , for example onAppStart is considered a handler for the event "AppStart".

myController = {
	initialize: function(){
		//controller loaded, do my init
	},
	onAppStart: function(){
		console.log("App is running...");
		return true; //return false to cancel application run
	}
};

The event "AppStart" does not have parameters but other events may have parameters.

To learn more about events published by EXC read the Core Events guide.

App Controller

The app controller is the main controller responsible of the application. In addition to our app controller we add other controllers to better structure our app logic, made the code more manageable and add reusability.

The app controller is responsible for the orchestration of your app's entire life-cycle and every application must have an app controller.

Since the app controller is actually the only controller required in an EXC app, we will use it as a starting point to learn about controllers.

EXC uses a global object named app as your app controller.

When EXC is loading it will wait until a variable named app appears on the global scope (In a browser thats the window or self).

The app object can be inline inside your HTML in a <script> tag or loaded dynamically.

<html>
<head>...</head>
<body>
...
<script type='text/javascript'>
app = {
	initialize: function(){
		//app object was loaded as the app controller
	}
};
</script>
</body>
</html>

A controller may implement an initialize function. The initialize method is called to let you initialize your controller. The initialize is generally invoked before the app is running.

Be careful when making assumptions about what other things are loaded and available inside a initialize function of a controller. The only guarantee is that the controller object and its related scope is ready.

The app controller gets a lot of special events from EXC, most events are optional and you add event handlers for the ones that you need.

The AppStart event is a required event and it is called to ensure that EXC can RUN your app. The AppStart is a good place to check the state of your app and initialize things. This handler must return true to let the application run.

With these two our app controller knows looks like this:

app = {
	initialize: function(){
		//controller loaded, do my init
	},
	onAppStart: function(){
		console.log("App is running...");
		return true; //return false to cancel application run
	}
};

State Management

As a Javascript application grows in complexity managing the information is difficult, mostly because state and information is scattered across many components and pieces.

In EXC the app controller is a global object that is available to all the different elements of your application and can help you coordinate the different aspects of your application logic and move data around.

Your app controller is available in the global scope using the variable app or self.app or window.app.

Your app implements a publisher/subscriber functionality which makes it very easy to orchestrate your app logic and allow disconnected elements to work together.

Just to be clear! All controllers implement pub/sub functionality that you can use. The app controller is the only one used by EXC to broadcasts events around and the only one that provides automatic subscriptions from other controllers.

Lets see an example:

myController = {
	initialize: function(){
		//controller loaded, do my init
	},
	onUserReady: function(user){
		console.log("We got a user [%s]...", user.username);
	}
};
//some where in your app...
app.publish("userReady", {"username": "ctk", "name": "Jose"} );

Adding other controllers

Segregating our app logic with multiple controllers is always a good idea.

The following are the basic methods that you may use to load additional controllers in your front-end.

IMPORTANT do not use these methods to load your app controller as all of these require the app controller to be running already.

A third option not discussed here is to load a controller yourself and using exc.app.loadControllerByName(objName) to make it available.

Adding a controller with the Manifest

Your app controller (or any controller for the fact) may include a manifest property. A manifest is used to specify dependencies or additional assets used by a controller.

The manifest property is a plain object that you add to your controller with items in either a require or include property. See Controller's Manifest for more details.

self.app = {
	manifest: {
		require: [
			{controller: "loginController", url: "../a/js/controller.login.js", wait: true},
		]
	},
	initialize: function(){
		//app object was loaded as the app controller
	},
	onAppStart: function(){
		console.log("App is running...");
	}
};

See appController to learn more about your app controller.

Adding a controller with a backend interaction

You PHP backend may inject a controller using $client->addController():

<php
$client->addController('loginController', 'asset://js/controller.login.js');
$client->done();

See Interacting with the front-end for more details.

Related Topics

Controller's Manifest

Fork me on GitHub