Deprecated/0.10/YourFirstModule

Warning! This page has the following tags:

  • This page is deprecated, and is only useful for developers using Agavi 0.10.
  • This page exists for reference purposes only.

Your First Module

I'm assuming that you have managed to download Agavi, and your looking at the screen and thinking to yourself, "What next?". If that describes your current situation then you have come to the right page.

Aim

This tutorial will show you how to set up an initial web page using the Agavi framework. This tutorial will not include any of the features which Agavi supports, we'll get to those later, for now it's a no frills example to get you up and running.

Tasks

There are a few tasks that we will look at, these are summarised as follows:

  • Directory structure
  • Create a new Module
  • Edit the configuration files
  • Edit the Action
  • Edit the View
  • Edit the Template

Directories

Okay I admit it there is nothing special here it's just a case of creating a few directories and copying the right files into them. However, I would like to point out that it is one of those tasks that we need to get right at the start.

Whilst the QuickStart? shows an automated way of setting these up I'll step through the process of creating the directories and copying the files just so you know what is happening.

  1. Create a directory that will have web access
  2. Create a directory that will not be accessible directly from the web
  3. Copy the index.php file into the web directory
  4. Copy the default module into the source directory

Parent Directory

Okay, so this is where you learn that I don't follow my own instructions. I'm creating a directory to hold the two directories mentioned above. You don't need to do this but it will help to keep everything nicely ordered.

So I have created a directory called Tutorial and I have given this directory read and execute permissions (755). In this directory I will place the other two directories.

www Directory

You can give this directory any name you like but I'm calling it www just to remind me this is the directory will have access to the big bad world out there. This directory is set up with read and execute permissions (755).

This is the directory the web server will have to have access to, I'm using Apache and I have set up a virtual server with the following settings 

<VirtualHost 172.16.2.23:80>
DocumentRoot /home/graeme/Development/Web/Tutorial/www
ServerName tutorial.agavi.bt
</VirtualHost>

I've also added an entry on the DNS server so the computer knows where to look up when I give the web address of tutorial.agavi.bt to the browser. This was the following setting in the file called /var/named/agavi.bt.hosts 

$ttl 38400
agavi.bt.	IN	SOA	graeme.sherubtse.edu.bt. root.graeme.sherubtse.edu.bt. (
			1119111175
			10800
			3600
			604800
			38400 )
agavi.bt.		IN	NS	graeme.sherubtse.edu.bt.
tutorial.agavi.bt.	IN	CNAME	graeme.sherubtse.edu.bt.

source Directory

This is the directory that will contain the Agavi modules that we will create. It will hold our source code. It's important to realise that this is different from the source code provided by the Agavi framework, but these two will work together.

This directory requires execute permissions (711).

index.php

You should find the generic index.php file in agavi/samples/www directory. Copy this folder into the www directory created above. Give this file read permissions (644).

Default Module Code

You should find the generic default module directory in the agavi/samples directory. This directory is called webapp. Copy the contents of this directory into the source directory create above. This will copy five directories adn a file. The directories are called:

cache(777)
config(711)
lib(711)
modules(755)
templates(711)

These directories only require execute permissions, except for the modules which also requires read and the cache which also requires read and write permissions. These have been given in brackets after each directory.

Configuration Files

There are two files that need to be modified before agavi will work.

The first is index.php the file which we just moved into the www directory. This file requires two lines to be modified. These will tell it the location of two files:

config.phpin the web app directory
agavi.phpin the mojavi source directory

The lines before: 

// +---------------------------------------------------------------------------+
// | An absolute filesystem path to our webapp/config.php script.              |
// +---------------------------------------------------------------------------+
require_once('INSERT PATH TO "webapp/config.php" HERE');

// +---------------------------------------------------------------------------+
// | An absolute filesystem path to the agavi/agavi.php script.              |
// +---------------------------------------------------------------------------+
require_once('INSERT PATH TO "agavi/agavi.php" HERE');

The lines after modification for my system I've removed the comment block to make the changes clearer: 

require_once('/home/graeme/Development/Web/Tutorial/source/config.php');

require_once('/home/graeme/Development/Web/agavi/src/agavi.php');

The second file that needs to be changed is the config.php file, the path of which has been identified above. The lines before: 

// +---------------------------------------------------------------------------+
// | An absolute filesystem path to the agavi package. This directory         |
// | contains all the Agavi packages.                                         |
// +---------------------------------------------------------------------------+
define('AG_APP_DIR', '<REPLACE ME>/agavi');

// +---------------------------------------------------------------------------+
// | An absolute filesystem path to your web application directory. This       |
// | directory is the root of your web application, which includes the core    |
// | configuration files and related web application data.                     |
// +---------------------------------------------------------------------------+
define('AG_WEBAPP_DIR', '<REPLACE ME>/webapp');

The lines after modification on my system, again I've removed the comment block: 

define('AG_APP_DIR', '/home/graeme/Development/Web/agavi/src/');
define('AG_WEBAPP_DIR', '/home/graeme/Development/Web/Tutorial/source');

Check it out

Okay before we go any further you should go to your browser and point it to your new web site. You should get the default Agavi web page.

Now we will look at two of the core classes in the framework, the Action and the View classes.

Edit the Action

The action class is our interface with the outside world. Every piece of data that comes from our application should be routed through this class. Once the data has been cleaned up then it is ready for other classes to use the data, these classes will then not need to worry about the integrity of the data.

In this step we will look at how to get some data from the user. But first we need to locate the file we will be changing. This file is in the source/modules/Default/actions directory, and the file is called IndexAction?.class.php.

Open this file for editing, the file consists of one class called Default_IndexAction which extends the Agavi framework file Action. This class has three methods defined; these are the execute(), getDefaultView() and getRequestMethods() methods. We will need to modify the first and last of these methods.

What we will be looking to do is to get some data from the user through a GET and then display this on the screen. So the first thing is to tell Agavi that we will be expecting some data to be coming into the system. This is done in the getRequestMethods() method. Change the code as follows: 

public function getRequestMethods ()
{
	return Request::GET;
}

Now we need to get the data that is to be passed in. This is done in the execute() method. The data will be passed in using the variable msg. To get the parameter we need to first get the context, within that object we can get the request and then we are able to get the parameter for the request. This is done as follows: 

public function execute ()
{
	echo $this->getContext()->getRequest()->getParameter('msg');
	return View::SUCCESS;
}

Now test that by pointing your browser to the web site and pass it some data using the msg variable. This can be done as follows: http://tutorial.agavi.bt/?msg=hello%20world,%20how%20are%20you?

You should see your message being displayed on the screen. However, this is not the correct way to display data. The Action class is about getting the data, checking it and then passing it to the View class that will then display the data.

So let's change the code: 

public function execute ()
{
	$msg = $this->getContext()->getRequest()->getParameter('msg');
	$this->getContext()->getRequest()->setAttribute('message',$msg);
	return View::SUCCESS;
}

The code now gets the parameter and stores it as an attribute, obviously between these two stages it would be possible to add some validation.

Now it is the responsibility of the View class to get the message attribute and display it on the web page.

Edit the View

The view class is our means of presenting the data that will appear on the web page. This class will use templates to generate the final html.

In this step we will look at how to get the data from the action class and pass it into a template. Again we need to locate the file we will be changing. This file is in the source/modules/Default/views directory, and the file is called IndexSuccessView?.class.php

This file consists of the Default_IndexSuccessView class and has just one method, the execute() method. This method should be modified as follows: 

public function execute ()
{
	// set our template
	$this->setTemplate('IndexSuccess.php');

	// set the title
	$this->setAttribute('title', 'Default Action');

	$msg = $this->getContext()->getRequest()->getAttribute('message');
	$this->setAttribute('message', $msg);
}

The first lines set up the template that will be used.

The next lines send the words 'Default Action' to this template using the variable title.

The next two lines are the ones that I have added. The first gets the message variable that was set up by the action. The second then sends this data to the template.

Finally the view sets up the default menu.

The view has now been changed, now it is time to modify the template.

Edit the Template

The template is located in the directory source/modules/Default/templates and is called IndexSuccess?.php. Add the following code to this template: 

<p>
<?php echo $template['message'] ?>
</p>

This will get the message variable and display it on the screen in its own paragraph.

Check it out.

-->Continue to part 2 of this tutorial UsingTheForm?