Starting a New Application: Hello World

Posted Jan 26, 2009 by Kris Jordan | Comments ( 1 ) | Filed in: | | | | |

Today's post is a quick, simple tutorial for kicking off a new Recess Application. We'll start with the automated New App Wizard in Recess Tools, and then we’ll walk through step-by-step what this wizard has done to set up a new application.

The New App Wizard in Recess Tools

To stay true to programming pedagogy let’s create a dynamic “Hello World!” application.

Lets open up Recess Tools in a browser by navigating to the directory you installed recess to, /recess. This is probably http://localhost/recess/

The wizard kicks off by asking us for two names, first a human readable name. This is used by Recess Tools to identify the application. We’ll name this application simply “Hello World”. The programmatic name is what the wizard will use when generating the Application class and directory structure. The programmatic name should not have spaces and should be a valid PHP identifier, like “HelloWorld”.

Next we’ll select a URL prefix for the application. A URL prefix determines how Recess will map a request URL to your application. Recess Tools, for example, has the prefix ‘recess/’. For hello world lets use ‘helloWorld/’.

At this point the wizard will generate a directory structure and some files that form the skeleton of an application. We will walk through what the wizard generates in detail in the following section. Let’s keep going through the wizard which is asking us to place a string into the RecessConf::$applications array. The string ‘helloWorld.HelloWorldApplication’ references the HelloWorldApplication class which the wizard generated which is located in the ‘helloWorld’.

Open your recess-conf.php file and find the RecessConf::$applications array. Add the line to the array as instructed. This array of strings tells Recess which applications are installed. Your RecessConf should look something like this:

After saving the recess-conf.php file we have finished installing our ‘Hello World’ application. By navigating to ‘Apps’ we’ll see our application ‘Hello World’ installed on the list of applications. Go ahead and follow the link.

When viewing an application in Recess Tools we can see the Models, Controllers, Views, and Routes. Note the new application wizard created a ‘Home’ controller for us.

The routes section shows us which URLs our application will respond to and which method in a controller is being mapped. We can see the url ‘helloWorld/’ will call the ‘index’ method in our ‘HelloWorldHomeController’ class. In a new tab try navigating to the location you installed Recess followed by ‘/helloWorld/’ (probably http://localhost/helloWorld/). You should be greeted with the default new application landing page:

Advanced: Creating a New Application Manually

Behind the scenes of the new application wizard a couple of steps happen to kick off a new application. There’s nothing to stop developers from doing this manually should the need arise.

The first step is creating the application directory structure. After installing Recess open up the ‘apps’ directory. Create a new sub-directory with a name for your application like ‘helloWorld’. Directories in Recess are typically named using the camelCaseConvention.

Now create the following ‘views’ and ‘controllers’ sub-directories so your structure looks like this:

• apps/
  • helloWorld/
    • controllers/
    • views/

Note: In a full-blown Recess application you would likely have a ‘models’ sup-directory as well. In this Hello World application we aren’t going to dive into models quite yet.

After creating the directory structure, the next step is creating a sub-class of Application. This class holds settings specific to the application such as the location of views in the directory structure and the prefix of models and controllers in the class path. In the ‘apps/helloWorld/’ directory create a new file named ‘HelloWorldApplication.class.php’. The ‘.class.php’ extension is an important distinction for the Recess Library to know the file contains a PHP class named HelloWorldApplication. The class should be specified as follows:

 <?php
 Library::import(‘recess.framework.Application’);
 
 
 
 class HelloWorldApplication extends Application {
 	public function __construct() {
 		$this->name = ‘Hello World’;
 		$this->viewsDir = $_ENV[‘dir.apps’] . ‘helloWorld/views/’;	
 		$this->modelsPrefix = ‘helloWorld.models.’;
 		$this->controllersPrefix = ‘helloWorld.controllers.’;
 		$this->modelsPrefix = ‘helloWorld.models.’;
 		$this->routingPrefix = ‘helloWorld/’;
 	}
 }
 ?>

Now that the Application class is set-up our last step is to ‘install’ the application into the recess-conf.php file. Within recess-conf.php there is an array of strings named RecessConf::$applications. These strings point to application classes in the class path. The apps folder is in the Library’s class path so we can reference the newly created HelloWorldApplication using ‘helloWorld.HelloWorldApplication’. If we were to put the HelloWorldApplication class in a subdirectory called ‘app’ within the ‘helloWorld’ subdirectory the fully-qualified class name would be ‘helloWorld.app.HelloWorldApplication’. The convention of single classes per file and directories being broken up with dots is taken from the land of Java. The Recess library provides an layer important to auto-loading and performance between framework code and PHP’s native include_once and require_once methods. The Library is covered in later documentation.