symfony advent calendar day nine: local improvements
====================================================

Previously on symfony
---------------------

During [day eight](8.txt), we added AJAX interactions to askeet without pain. The application is now quite usable, but could use a lot of little improvements. Rich text should be allowed in the questions `body`, and primary keys should not appear in the URIs. All that is not difficult to put in place with symfony: today will be a good occasion to practice what you already learned, and to check that you know how to manipulate all the layers of the MVC architecture.

Allow rich text formatting on questions and answers
---------------------------------------------------

### Markdown

The question and answer bodies only accept plain text for now. To allow basic formatting - bold, italic, hyperlinks, images, etc. - we will use an external library rather than reinvent the wheel. 

If you have taken a look at the symfony documentation in text format, you probably know that we are big [Markdown](http://daringfireball.net/projects/markdown/) fans. Markdown is a text-to-HTML conversion tool, and a syntax for text formatting. The great advantage of Markdown over, for instance, Wiki or forum syntax, is that a plain text markdown file is still very readable:

    Test Markdown text
    ------------------
    
    This is a **very simple** example of [Markdown][1].
    The best thing about markdown is its _auto-escape_ feature for code chunks:
    
        <a href="http://www.symfony-project.com">link to symfony</a>
    
    >The `<` and `>` are properly escaped as `&lt;` and `&gt;`,
    >and are not interpreted by any browser
    
    [1]: http://daringfireball.net/projects/markdown/   "Markdown"

This Markdown renders as follow:

>Test Markdown text
>------------------
>
>This is a **very simple** example of [Markdown](http://daringfireball.net/projects/markdown/).
>The best thing about markdown is its _auto-escape_ feature for code chunks:
>
>      <a href="http://www.symfony-project.com">link to symfony</a>
>
>>The `<` and `>` are properly escaped as `&lt;` and `&gt;`,
>>and are not interpreted by any browser

### Markdown library

Although originally written in [Perl](http://www.perl.com/), Markdown is available as a PHP library at [PHP Markdown](http://www.michelf.com/projects/php-markdown/). That's the one we will use. Download the `markdown.php` file and put it in the `lib` folder of the askeet project (`askeet/lib/`). That's all: It is now available to all the classes of the askeet applications, provided that you require it first:

    [php]
    require_once('markdown.php');   

We could call the Markdown converter each time we display the body of a message, but that would require too high a load on our servers. We'd rather convert the text body to an HTML body when the question is created, and store the HTML version of the body in the `Question` table. You are probably getting used to this, so the model extension won't be a surprise.

### Extend the model

First, add a colomn to the `Question` table in the `schema.xml`:

    [php]
    <column name="html_body" type="longvarchar" />

Then, regenerate the model and update the database:

    $ symfony propel-build-model
    $ symfony propel-build-sql
    $ symfony propel-insert-sql

### Override the `setBody` method 

When the `->setBody()` method of the `Question` class is called, the `html_body` column must also be updated with the Markdown conversion of the text body. Open the `askeet/lib/model/Question.php` model file, and create:

    [php]
    public function setBody($v)
    {
      parent::setBody($v);
  
      require_once('markdown.php');
      
      // strip all HTML tags
      $v = htmlentities($v, ENT_QUOTES, 'UTF-8');
            
      $this->setHtmlBody(markdown($v));
    }

Applying the `htmlentities()` function before setting the HTML body protects askeet from cross-site-scripting (XSS) attacks since all `<script>` tags are escaped.

### Update the test data

We will add some Markdown formatting to some of the questions of the test data (in `askeet/data/fixtures/test_data.yml`), to be able to check that the conversion works properly:

    Question:
      q1:
        title: What shall I do tonight with my girlfriend?
        user_id: fabien
        body:  |
          We shall meet in front of the __Dunkin'Donuts__ before dinner, 
          and I haven't the slightest idea of what I can do with her. 
          She's not interested in _programming_, _space opera movies_ nor _insects_.
          She's kinda cute, so I __really__ need to find something 
          that will keep her to my side for another evening.
    
      q2:
        title: What can I offer to my step mother?
        user_id: anonymous
        body:  |
          My stepmother has everything a stepmother is usually offered
          (watch, vacuum cleaner, earrings, [del.icio.us](http://del.icio.us) account). 
          Her birthday comes next week, I am broke, and I know that 
          if I don't offer her something *sweet*, my girlfriend 
          won't look at me in the eyes for another month.

You can now repopulate the database:

    $ php batch/load_data.php

### Modify the templates

The `showSuccess.php` template of the `question` module can be sightly modified:

    [php]
    ...
    <div class="question_body">
      <?php echo $question->getHtmlBody() ?>
    </div>
    ...
    
The list template fragment (`_list.php`) also shows the body, but in a truncated version:

    [php]
    <div class="question_body">
      <?php echo truncate_text(strip_tags($question->getHtmlBody()), 200) ?>
    </div>

Everything is now ready for the final test: display the three pages that were modified, and observe the formatted text coming from the test data:

    http://askeet/question/list
    http://askeet/recent
    http://askeet/question/show/stripped_title/what-shall-i-do-tonight-with-my-girlfriend    

![markdown text](/images/askeet/markdown_question.gif)

The same goes for the `Answer` `body`: An alternate `html_body` column has to be created in the model, the `->setBody()` method needs to be overridden, and the answers displayed in `question/show` have to use the `->getHtmlBody()` method instead of the `->getBody()`. As the code is exactly the same as above, we won't decribe it here, but you will find it in today's SVN code.

Hide all `id`s
--------------

Another good practice in symfony actions is to avoid as much as possible to pass primary keys as request parameters. This is because our primary keys are mainly auto-incremental, and this gives hackers too much information about the records of the database. Plus, the displayed URI doesn't mean anything, and that's bad for the search engines.

Take the user profile page, for instance. For now, it uses the user `id` as a parameter. But if we make sure that the `nickname` is unique, it could as well be the parameter for the request. Let's do it.

### Change the action

Edit the `user/show` action:

    [php]
    public function executeShow()
    {
      $this->subscriber = UserPeer::retrieveByNickname($this->getRequestParameter('nickname'));
      $this->forward404Unless($this->subscriber);
    
      $this->interests = $this->subscriber->getInterestsJoinQuestion();
      $this->answers   = $this->subscriber->getAnswersJoinQuestion();
      $this->questions = $this->subscriber->getQuestions();
    }

### Change the model

Add the following method to the `UserPeer` class in the `askeet/lib/model/` directory.

    [php]
    public static function retrieveByNickname($nickname)
    {
      $c = new Criteria();
      $c->add(self::NICKNAME, $nickname);

      return self::doSelectOne($c);
    }
 
### Change the template

The pages that display a link to the user profile must now mention the user's `nickname` instead of his/her `id`. 

In the `question/showSuccess.php`, `question/_list.php` templates, replace:

    [php]
    <?php echo link_to($question->getUser(), 'user/show?id='.$question->getUserId()) ?>

by:

    [php]
    <?php echo link_to($question->getUser(), 'user/show?nickname='.$question->getUser()->getNickname()) ?>
    
The same kind of modification goes for the `answer/_answer.php` template.

### Add the routing rule

Add a new rule in the routing configuration for this action so that the `url` pattern shows a `nickname` request parameter:

    user_profile:
      url:   /user/:nickname
      param: { module: user, action: show }    

After a `symfony clear-cache`, the last thing to do is to test your modifications.

Routing
-------

Apart from today's additions, many of the actions written until now use the default routing, so the module name and the action name are often displayed in the address bar of the browser. You already learned how to fix it, so let's define URL patterns for all the actions. Edit the `askeet/apps/frontend/config/routing.yml`:

    # question
    question:
      url:   /question/:stripped_title
      param: { module: question, action: show }

    popular_questions:
      url:   /index/:page
      param: { module: question, action: list, page: 1 }

    recent_questions:
      url:   /recent/:page
      param: { module: question, action: recent, page: 1 }

    add_question:
      url:   /add_question
      param: { module: question, action: add }

    # answer
    recent_answers:
      url:   /recent/answers/:page
      param: { module: answer, action: recent, page: 1 }

    # user
    login:
      url:   /login
      param: { module: user, action: login }

    logout:
      url:   /logout
      param: { module: user, action: logout }

    user_profile:
      url:   /user/:nickname
      param: { module: user, action: show }

    # default rules
    homepage:
      url:   /
      param: { module: question, action: list }

    default_symfony:
      url:   /symfony/:action/*
      param: { module: default }

    default_index:
      url:   /:module
      param: { action: index }

    default:
      url:   /:module/:action/*

If you navigate in the production environment, you are strongly advised to clear the cache before testing this configuration modification. 

One good practice of symfony routing is to use the rule names in a `link_to()` helper instead of the `module/action`. Not only is it faster (the routing engine doesn't need to parse the routing configuration to find the rule to apply), but it also allows you to modify the action behind a rule name later. The [routing chapter](http://www.symfony-project.com/book/1_0/09-Links-and-the-Routing-System) of the symfony book explains that more in detail.

    [php]
    <?php link_to('@user_profile?id='.$user->getId()) ?>
    // is better than
    <?php link_to('user/show?id='.$user->getId()) ?>
 
Askeet follows the symfony good practices, so the code that you will download at the end of this day's tutorial contains only rule names in the link helpers. Replacing `action/module` by `@rule` in all the templates and custom helper is not very fun to do, so the last advice concerning routing is: Write the routing rules as you create actions, and use rule names in the link helpers from the beginning. 

See you Tomorrow
----------------

Today's changes were longer to read than to understand. In addition, the modifications described in the tutorial were repeated for similar cases in the overall code. Although no real new feature was added today, the code changed a lot. 

If you feel that you didn't learn much about symfony today, it means that you are getting ready to start your own project. The process of creating an action, modifying the model to have it serve the action as needed, write a simple template to output the action and edit the configuration to integrate the new action into the logic of the application are the basics of symfony development. 

All the good practices exposed here (using external libraries instead of rewriting it in symfony, not showing primary keys in the application, using routing rule names instead of `module/action`) will keep your application clean, safe, fast and maintainable.

But the askeet application is far from finished! The functionnality that lacks the most is the ability to add a new question and to add a new answer. That's what we will develop tomorrow. 

Do you have a suggestion about the additional feature of the 21st day? Make sure you send it to the [askeet mailing-list](mailto:askeet-subscribe@symfony-project.com). Stay tuned!