Akelos For Dummies

My wife is a lightweight in Linux and in PHP programming. She has never used Akelos. She knows nothing about MVC programming. She has asked me to teach her. Her method of learning is for me to lecture her while she takes notes in very great detail. It isn't often that a husband gets to lecture his wife and she welcomes it, so I'm not going to miss the chance.

This material is pretty much the same as can be found in the tutorial. The booklink tutorial is briefer in some parts than this is. The first project here just displays a static page, which is what my wife wants to do for starters. Once the project has been generated, there are files in the project's docs directory that lists the booklink tutorial, too.

If you who read this wiki find any errors or have any unanswered questions about the subject matter, please post them to the documentation forum and mention “Akelos for Dummies”. If you're not reading this wiki, forget it.

The first question we might ask is “Why use Akelos (or any framework)?” Any programmer knows that a computer program can be written any number of different ways. Variable name options are endless. There are also a whole lot of nitty-gritty details that make writing a program a bunch of work, especially in a graphical environment. There are fun parts to programming, too. What we'd like to do is to have a code generator that will create the uninspiring code for us, leaving just the fun part. This would also make us more productive. There are things that we should do, such as testing, that we often don't do because of the extra work involved. Other people have written code that we can use, but we'd like an easy way to incorporate their code into our projects. Akelos will do all this and more, but will not charge us a performance penalty. It does, however, have a price.

The price of using Akelos is that we must give up our “right” to create code just any old which way. We employ the principle of “convention over configuration”, whereby we learn and follow certain rules for writing code. This makes it much easier to maintain other people's code as well as creating a consistency in our own code. One of the things we must do is to code using the Model-View-Controller (MVC) paradigm.

When we run an Akelos program, the Akelos software is on our machine and our project communicates with it as it runs. Akelos needs to know where to look for things. What this means is that our code goes into certain directories depending on what it is to do. This makes it easier for us to debug and maintain, too. Our project consists not of one monolithic piece of code, nor even a few large files, but a whole lot of small files.

Akelos is designed to access a database (model), process the data (controller), present the data to the user, accept the user's input (view) and process it (controller). The following notes do not give the details for writing MVC code. They just introduce it.

This is the data model. Code for it is in (surprise) app/models. Code placed here defines the database tables and the relationships between them (one to many, etc.) Models also tell how a table is to be looked at: a list, a tree or a nested set. Edits to insure that no garbage gets written also go here.

There may be as many controllers as are called for by the logic of a program. A controller describes how data is to be processed. Code for it is in app/controllers. A controller class, like any class, has a number of functions. There is one function corresponding to each web page. There may be functions that don't access web pages. Within each web page accessing function may be some code to be executed before the page is viewed. If the user enters data on the page, the function may also process the results.

The views, which are in app/views (another surprise) have a subdirectory corresponding to each controller. Within that subdirectory is one template file for each page that is to be generated. Template file? There's no point in making the programmer write HTML or PHP code for the entire page. There is a layout file that each page accesses containing code common to all of them. The template files have shortcuts for including forms and fields, as well as data loops. Akelos uses them to generate PHP files that actually render web pages.

We'll start with installing Akelos, then creating a project. As my wife goes through the steps, we'll stop every once in a while and she'll do what I've instructed her to do.

I'll probably walk her through her first several projects and make notes in this section accordingly. We'll update the main Wiki as needed, then reference the Wiki.

A lot of the instructions in this section repeat instructions found elsewhere in other parts of the documentation. I'm writing this from the standpoint of the rank beginner. Some of the other instructions give several ways to do a task. We'll give only one way to help keep things as easy as possible.

I might add that my wife runs a LAMP system (Linux, Apache, MySQL, PHP). Her Linux is Fedora 9. (Yeah, hubby had a hand in that, too.) Under her home directory, she has a directory called “php”.

Many of the instructions here are run from a command line in a terminal window. These instructions will begin with

$ 

the prompt for a user. When you change to a root prompt, the prompt will be

# 

.

Things to do before creating your first Akelos project

Her project name is im, for Internet Marketing. Akelos is designed to create and maintain dynamic web pages with a database interface. This first project is not going to use most of Akelos' features, for my wife wants only a single static page. It must later fit into a larger Akelos project and may have some dynamic features then, so she wants to use as many of Akelos' features as possible. Besides, she has experience with static web pages.

Hey, wait. This project has only a single static page. Why do we need databases? We need them because Akelos is designed for them and requires them. We won't be using them. Therefore we're not going to spend time learning why there are three databases and what each one does. Play along with me on this one. When you enter the first line in the terminal window, MySQL will ask you for it's root password:

$ mysql -u root -p

mysql> CREATE DATABASE im;
mysql> CREATE DATABASE im_dev;
mysql> CREATE DATABASE im_tests;

mysql> GRANT ALL ON im.* TO bermi@localhost IDENTIFIED BY "pass";
mysql> GRANT ALL ON im_dev.* TO bermi@localhost IDENTIFIED BY "pass";
mysql> GRANT ALL ON im_tests.* TO bermi@localhost IDENTIFIED BY "pass";

mysql> FLUSH PRIVILEGES;
mysql> exit

$ cd ~/php
$ akelos/script/setup im

This will generate a lot of files beginning with a project directory called im. The last thing the setup does is to issue a message suggesting that the project be run in a browser to complete the setup. We're not going to do that just yet. There are things that would need to be done first. Instead, we'll change to the project directory and copy set_apache into it.

$ cd im
$ cp ~/bin/set_apache .

We made set_apache executable when we created it, so the copy should be executable, too. If it isn't, you'll have to make it so:

$ chmod u+x set_apache

Now, we'll run it:

$ sudo ./set_apache

If we run our project and try to edit a locale file that has been created by Apache, we won't be able to save it. Running set_apache as we did above will enable our ability to save our editing changes.

So that we can use our browser to execute our project, we must create a link from our http document root to the public directory of our project, im. My wife's document root is at /var/www/html.

$ sudo ln -s ~/im/public /var/www/html/im

Why did I use ~/im/public when I could have just used . (dot)? Because I didn't want the link to point to dot, that's why. I had to specify exactly where I wanted it to point, so I did.

If we execute our project in our browser, we'll be asked for

• database connection information.
• language codes for multi-lingual projects

The password asked for by the configuration is the one supplied while setting the privileges (GRANT ALL) for the databases. My wife knows the rest of the information required, so I can go on (and on and on).

As we make references to our project's directories, unless we say otherwise, the directory's location is relative to our project root. In our case, this is ~/php/im.

While we're searching for strings, we can get results we don't need (or want) by keeping files that are useless to us. We can either delete them or move them out of our project root's path. The latter is safer, and we just might find code in some of them that we can use.

In the docs directory are some tutorial files in different languages. My wife can delete all but one of them, As she is an English speaker, she can delete

• tutorial-fr.markdown
• tutorial-es.markdown
• tutorial-ja.markdown

Because she's not just an English speaker, but a Linux user, she can delete

• windows_set_php_path-es.markdown.

I have never deleted the page files, from a project, but I don't think they are needed after a project is set up. They might be handy for reference:

$ rm -f app/views/layouts/compiled/page.tpl.php
$ rm -f app/views/layouts/page.tpl
$ rm -rf app/views/page/
$ rm -rf app/locales/page/

$ gedit config/routes.php

Akelos will read the browser's URL and the routes.php file, then will execute the correct function (action) in the named controller. The file has reference to the page controller, which we're not going to use. The page that we're going to create is for an electric power filter, so we're going to create a controller called pwr_fltr. The code in routes.php can be quite complex, but, for starters, we just have these two lines. Wife will edit this file replacing “page” with “pwr_fltr”.

From the project root

$ ./script/generate controller pwr_fltr

A scaffold is view code that is generated from the model and the controller. It doesn't need to be generated, but it may be easier to modify the generated code than to write view code from scratch, especially when you're not familiar with Akelos.

$ ./script/generate scaffold pwr_fltr

Because we didn't create a model to access the database, some of the scaffold files were not generated, but that's OK. My wife is smart. She can work with what she has.

In her favorite editor, my wife should open app/controller/pwr_fltr_controller.php. It has a PHP class in it, but nothing else. She'll need to create a name for the page file. For the sake of this document, we'll call it “ad”, for “advertisement”. She'll enter the following code in the class.

function index()
{
    $this->redirectTo(array('action' => 'ad'));
}
 
function ad()
{
}

So, what does this do? The routes.php file will direct action to the index function (action) of this controller. Because there is only one page, we don't need a menu or anything like that. We'll just tell the project to go to the ad function. But, it's empty! Not to worry. What that means is that the project will do no processing, either before displaying the page or afterward. It's a static page.

Wife, save the file.

First, wife, create a pwr_fltr layout file. If she'd had a model, it would have been generated for her. In a new file put this code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
 <head>
  <title><?php  echo $text_helper->translate('Power Filter',array(),'layout');?>:
    <?php  echo  $text_helper->translate($controller->getActionName(),array(),'layout');?>
  </title>
  <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
  <?php  echo  $asset_tag_helper->stylesheet_link_tag('scaffold') ?>
 </head>
 <body>
 {?flash-notice}<div class="flash_notice">{flash-notice}</div>{end}
  <?php  echo  $content_for_layout ?>
 </body>
</html>

Hey! It works. I'll give you the details of what the code is and what it does later. If you're too impatient, more information on flash is here.

Create a new page and save it as app/views/pwr_fltr/ad.tpl. Remember the function ad in the controller? Akelos will use it to cause this page to be displayed. The contents of this file should be what you'd put in the body of the HTML page.

This file is in public/stylesheets/scaffold.css. It will run as it is, but, of course, it may be changed.

Just put the project's URL in your browser and go. http://host.name.com/im Using my host name, it ran fine. I don't know what your problem is. Yes, I know. It's my fault. Let's just find out what's wrong and fix it.

Well, the first project is done. We'll have other projects that will use more of Akelos' features.