Chapter 4 - The Basics Of Page Creation

Curiously, the first tutorial that programmers follow when learning a new language or a framework is the one that displays "Hello, world!" on the screen. It is strange to think of the computer as something that can greet the whole world, since every attempt in the artificial intelligence field has so far resulted in poor conversational abilities. But symfony isn't dumber than any other program, and the proof is, you can create a page that says "Hello, <Your Name Here>" with it.

This chapter will teach you how to create a module, which is a structural element that groups pages. You will also learn how to create a page, which is divided into an action and a template, because of the MVC pattern. Links and forms are the basic web interactions; you will see how to insert them in a template and handle them in an action.

Creating a Module Skeleton

As Chapter 2 explained, symfony groups pages into modules. Before creating a page, you need to create a module, which is initially an empty shell with a file structure that symfony can recognize.

The symfony command line automates the creation of modules. You just need to call the init-module task with the application name and the module name as arguments. In the previous chapter, you created a myapp application. To add a mymodule module to this application, type the following commands:

> cd ~/myproject
> symfony init-module myapp mymodule

>> dir+      ~/myproject/apps/myapp/modules/mymodule
>> dir+      ~/myproject/apps/myapp/modules/mymodule/actions
>> file+     ~/myproject/apps/myapp/modules/mymodule/actions/actions.class.php
>> dir+      ~/myproject/apps/myapp/modules/mymodule/config
>> dir+      ~/myproject/apps/myapp/modules/mymodule/lib
>> dir+      ~/myproject/apps/myapp/modules/mymodule/templates
>> file+     ~/myproject/apps/myapp/modules/mymodule/templates/indexSuccess.php
>> dir+      ~/myproject/apps/myapp/modules/mymodule/validate
>> file+     ~/myproject/test/functional/myapp/mymoduleActionsTest.php
>> tokens    ~/myproject/test/functional/myapp/mymoduleActionsTest.php
>> tokens    ~/myproject/apps/myapp/modules/mymodule/actions/actions.class.php
>> tokens    ~/myproject/apps/myapp/modules/mymodule/templates/indexSuccess.php

Apart from the actions/, config/, lib/, templates/, and validate/ directories, this command created only three files. The one in the test/ folder concerns unit tests, and you don't need to bother with it until Chapter 15. The actions.class.php (shown in Listing 4-1) forwards to the default module congratulation page. The templates/indexSuccess.php file is empty.

Listing 4-1 - The Default Generated Action, in actions/actions.class.php

<?php
 
class mymoduleActions extends sfActions
{
  public function executeIndex()
  {
    $this->forward('default', 'module');
  }
}

For each new module, symfony creates a default index action. It is composed of an action method called executeIndex and a template file called indexSuccess.php. The meanings of the execute prefix and Success suffix will be explained in Chapters 6 and 7, respectively. In the meantime, you can consider that this naming is a convention. You can see the corresponding page (reproduced in Figure 4-1) by browsing to the following URL:

http://localhost/myapp_dev.php/mymodule/index

The default index action will not be used in this chapter, so you can remove the executeIndex() method from the actions.class.php file, and delete the indexSuccess.php file from the templates/ directory.

Figure 4-1 - The default generated index page

Adding a Page

In symfony, the logic behind pages is stored in the action, and the presentation is in templates. Pages without logic (still) require an empty action.

Adding an Action

The "Hello, world!" page will be accessible through a myAction action. To create it, just add an executeMyAction method to the mymoduleActions class, as shown in Listing 4-2.

Listing 4-2 - Adding an Action Is Like Adding an Execute Method to the Action Class

<?php
 
class mymoduleActions extends sfActions
{
  public function executeMyAction()
  {
  }
}

The name of the action method is always execute``Xxx``(), where the second part of the name is the action name with the first letter capitalized.

Now, if you request the following URL:

http://localhost/myapp_dev.php/mymodule/myAction

symfony will complain that the myActionSuccess.php template is missing. That's normal; in symfony, a page is always made of an action and a template.

http://localhost/myapp_dev.php/article/index?id=123

http://localhost/articles/europe/france/finance.html

http://localhost/articles/tagged/finance+france+euro

Adding a Template

The action expects a template to render itself. A template is a file located in the templates/ directory of a module, named by the action and the action termination. The default action termination is a "success," so the template file to be created for the myAction action is to be called myActionSuccess.php.

Templates are supposed to contain only presentational code, so keep as little PHP code in them as possible. As a matter of fact, a page displaying "Hello, world!" can have a template as simple as the one in Listing 4-3.

Listing 4-3 - The mymodule/templates/myActionSuccess.php Template

<p>Hello, world!</p>

If you need to execute some PHP code in the template, you should avoid using the usual PHP syntax, as shown in Listing 4-4. Instead, write your templates using the PHP alternative syntax, as shown in Listing 4-5, to keep the code understandable for non-PHP programmers. Not only will the final code be correctly indented, but it will also help you keep the complex PHP code in the action, because only control statements (if, foreach, while, and so on) have an alternative syntax.

Listing 4-4 - The Usual PHP Syntax, Good for Actions, But Bad for Templates

<p>Hello, world!</p>
<?php
 
if ($test)
{
  echo "<p>".time()."</p>";
}
 
?>

Listing 4-5 - The Alternative PHP Syntax, Good for Templates

<p>Hello, world!</p>
<?php if ($test): ?>
<p><?php echo time(); ?></p>
<?php endif; ?>

Passing Information from the Action to the Template

The job of the action is to do all the complicated calculation, data retrieval, and tests, and to set variables for the template to be echoed or tested. Symfony makes the attributes of the action class (accessed via $this->variableName in the action) directly accessible to the template in the global namespace (via $variableName). Listings 4-6 and 4-7 show how to pass information from the action to the template.

Listing 4-6 - Setting an Action Attribute in the Action to Make It Available to the Template

<?php
 
class mymoduleActions extends sfActions
{
  public function executeMyAction()
  {
    $today = getdate();
    $this->hour = $today['hours'];
  }
}

Listing 4-7 - The Template Has Direct Access to the Action Attributes

<p>Hello, world!</p>
<?php if ($hour >= 18): ?>
<p>Or should I say good evening? It is already <?php echo $hour ?>.</p>
<?php endif; ?>

Gathering Information from the User with Forms

Forms are a good way to get information from the user. Writing form and form elements in HTML can sometimes be cumbersome, especially when you want to be XHTML-compliant. You could include form elements in symfony templates the usual way, as shown in Listing 4-8, but symfony provides helpers that make this task easier.

Listing 4-8 - Templates Can Include Usual HTML Code

<p>Hello, world!</p>
<?php if ($hour >= 18): ?>
<p>Or should I say good evening? It is already <?php echo $hour ?>.</p>
<?php endif; ?>
<form method="post" action="/myapp_dev.php/mymodule/anotherAction">
  <label for="name">What is your name?</label>
  <input type="text" name="name" id="name" value="" />
  <input type="submit" value="Ok" />
</form>

A helper is a PHP function defined by symfony that is meant to be used within templates. It outputs some HTML code and is faster to use than writing the actual HTML code by yourself. Using symfony helpers, you can have the same result as in Listing 4-8 with the code shown in Listing 4-9.

Listing 4-9 - It Is Faster and Easier to Use Helpers Than to Use HTML Tags

<p>Hello, world!</p>
<?php if ($hour >= 18): ?>
<p>Or should I say good evening? It is already <?php echo $hour ?>.</p>
<?php endif; ?>
<?php echo form_tag('mymodule/anotherAction') ?>
  <?php echo label_for('name', 'What is your name?') ?>
  <?php echo input_tag('name') ?>
  <?php echo submit_tag('Ok') ?>
</form>

<?php
>     $card_list = array(
>       'VISA' => 'Visa',
>       'MAST' => 'MasterCard',
>       'AMEX' => 'American Express',
>       'DISC' => 'Discover');
>     echo select_tag('cc_type', options_for_select($card_list, 'AMEX'));
>     ?>

<select name="cc_type" id="cc_type">
  <option value="VISA">Visa</option>
  <option value="MAST">MasterCard</option>
  <option value="AMEX" selected="selected">American Express</option>
  <option value="DISC">Discover</option>
</select>

Note that the use of the short opening tags (<?=, equivalent to <?php echo) is not recommended for professional web applications, since your production web server may be able to understand more than one scripting language and consequently get confused. Besides, the short opening tags do not work with the default PHP configuration and need server tweaking to be activated. Ultimately, when you have to deal with XML and validation, it falls short because <? has a special meaning in XML.

Form manipulation deserves a whole chapter of its own, since symfony provides many tools, mostly helpers, to make it easier. You will learn more about these helpers in Chapter 10.

Linking to Another Action

You already know that there is a total decoupling between an action name and the URL used to call it. So if you create a link to anotherAction in a template as in Listing 4-10, it will only work with the default routing. If you later decide to change the way the URLs look, then you will need to review all templates to change the hyperlinks.

Listing 4-10 - Hyperlinks, the Classic Way

<a href="/myapp_dev.php/mymodule/anotherAction?name=anonymous">
  I never say my name
</a>

To avoid this hassle, you should always use the link_to() helper to create hyperlinks to your application's actions. Listing 4-11 demonstrates the use of the hyperlink helper.

Listing 4-11 - The link_to() Helper

<p>Hello, world!</p>
<?php if ($hour >= 18): ?>
<p>Or should I say good evening? It is already <?php echo $hour ?>.</p>
<?php endif; ?>
<?php echo form_tag('mymodule/anotherAction') ?>
  <?php echo label_for('name', 'What is your name?') ?>
  <?php echo input_tag('name') ?>
  <?php echo submit_tag('Ok') ?>
  <?php echo link_to('I never say my name','mymodule/anotherAction?name=anonymous') ?>
</form>

The resulting HTML will be the same as previously, except that when you change your routing rules, all the templates will behave correctly and reformat the URLs accordingly.

The link_to() helper, like many other helpers, accepts another argument for special options and additional tag attributes. Listing 4-12 shows an example of an option argument and the resulting HTML. The option argument is either an associative array or a simple string showing key=value couples separated by blanks.

Listing 4-12 - Most Helpers Accept an Option Argument

// Option argument as an associative array
<?php echo link_to('I never say my name', 'mymodule/anotherAction?name=anonymous',
  array(
    'class'    => 'special_link',
    'confirm'  => 'Are you sure?',
    'absolute' => true
)) ?>
 
// Option argument as a string
<?php echo link_to('I never say my name', 'mymodule/anotherAction?name=anonymous',
  'class=special_link confirm=Are you sure? absolute=true') ?>
 
// Both calls output the same
 => <a class="special_link" onclick="return confirm('Are you sure?');"
    href="http://localhost/myapp_dev.php/mymodule/anotherAction/name/anonymous">
    I never say my name</a>

Whenever you use a symfony helper that outputs an HTML tag, you can insert additional tag attributes (like the class attribute in the example in Listing 4-12) in the option argument. You can even write these attributes in the "quick-and-dirty" HTML 4.0 way (without double quotes), and symfony will output them in nicely formatted XHTML. That's another reason why helpers are faster to write than HTML.

Like the form helpers, the link helpers are numerous and have many options. Chapter 9 will describe them in detail.

Getting Information from the Request

Whether the user sends information via a form (usually in a POST request) or via the URL (GET request), you can retrieve the related data from the action with the getRequestParameter() method of the sfActions object. Listing 4-13 shows how, in anotherAction, you retrieve the value of the name parameter.

Listing 4-13 - Getting Data from the Request Parameter in the Action

<?php
 
class mymoduleActions extends sfActions
{
  ...
 
  public function executeAnotherAction()
  {
    $this->name = $this->getRequestParameter('name');
  }
}

If the data manipulation is simple, you don't even need to use the action to retrieve the request parameters. The template has access to an object called $sf_params, which offers a get() method to retrieve the request parameters, just like the getRequestParameter() in the action.

If executeAnotherAction() were empty, Listing 4-14 shows how the anotherActionSuccess.php template would retrieve the same name parameter.

Listing 4-14 - Getting Data from the Request Parameter Directly in the Template

<p>Hello, <?php echo $sf_params->get('name') ?>!</p>

The $sf_params object is more powerful than just giving a getter equivalent to an array. For instance, if you only want to test the existence of a request parameter, you can simply use the $sf_params->has() method instead of testing the actual value with get(), as in Listing 4-15.

Listing 4-15 - Testing the Existence of a Request Parameter in the Template

<?php if ($sf_params->has('name')): ?>
  <p>Hello, <?php echo $sf_params->get('name') ?>!</p>
<?php else: ?>
  <p>Hello, John Doe!</p>
<?php endif; ?>

You may have already guessed that this can be written in a single line. As with most getter methods in symfony, both the getRequestParameter() method in the action and the $sf_params->get() method in the template (which, as a matter of fact, calls the same method on the same object) accept a second argument: the default value to be used if the request parameter is not present.

<p>Hello, <?php echo $sf_params->get('name', 'John Doe') ?>!</p>

Summary

In symfony, pages are composed of an action (a method in the actions/actions.class.php file prefixed with execute) and a template (a file in the templates/ directory, usually ending with Success.php). They are grouped in modules, according to their function in the application. Writing templates is facilitated by helpers, which are functions provided by symfony that return HTML code. And you need to think of the URL as a part of the response, which can be formatted as needed, so you should refrain from using any direct reference to the URL in action naming or request parameter retrieval.

Once you know these basic principles, you can already write a whole web application with symfony. But it would take you way too long, since almost every task you will have to achieve during the course of the application development is facilitated one way or another by some symfony feature . . . which is why the book doesn't stop now.