PageRenderTime 77ms CodeModel.GetById 2ms app.highlight 65ms RepoModel.GetById 1ms app.codeStats 0ms

/gentle-introduction/en/07-Inside-the-View-Layer.markdown

https://github.com/rafaelgou/symfony1-docs
Markdown | 985 lines | 688 code | 297 blank | 0 comment | 0 complexity | bceb726509a121109b5594b92125e0ea MD5 | raw file

Large files files are truncated, but you can click here to view the full file

  1Chapter 7 - Inside The View Layer
  2=================================
  3
  4The view is responsible for rendering the output correlated to a particular action. In symfony, the view consists of several parts, with each part designed to be easily modified by the person who usually works with it.
  5
  6* Web designers generally work on the templates (the presentation of the current action data) and on the layout (containing the code common to all pages). These are written in HTML with small embedded chunks of PHP, which are mostly calls to helpers.
  7* For reusability, developers usually package template code fragments into partials or components. They use slots to affect more than one zone of the layout. Web designers can work on these template fragments as well.
  8* Developers focus on the YAML view configuration file (setting the properties of the response and other interface elements) and on the response object. When dealing with variables in the templates, the risks of cross-site scripting must not be ignored, and a good comprehension of output escaping techniques is required to safely record user data.
  9
 10But whatever your role is, you will find useful tools to speed up the tedious job of presenting the results of the action. This chapter covers all of these tools.
 11
 12Templating
 13----------
 14
 15Listing 7-1 shows a typical symfony template. It contains some HTML code and some basic PHP code, usually calls to variables defined in the action (via `$this->name = 'foo';`) and helpers.
 16
 17Listing 7-1 - A Sample indexSuccess.php Template
 18
 19    [php]
 20    <h1>Welcome</h1>
 21    <p>Welcome back, <?php echo $name ?>!</p>
 22    <ul>What would you like to do?
 23      <li><?php echo link_to('Read the last articles', 'article/read') ?></li>
 24      <li><?php echo link_to('Start writing a new one', 'article/write') ?></li>
 25    </ul>
 26
 27As explained in Chapter 4, the alternative PHP syntax is preferable for templates to make them readable for non-PHP developers. You should keep PHP code to a minimum in templates, since these files are the ones used to design the GUI of the application, and are sometimes created and maintained by another team, specialized in presentation but not in application logic. Keeping the logic inside the action also makes it easier to have several templates for a single action, without any code duplication.
 28
 29### Helpers
 30
 31Helpers are PHP functions that return HTML code and can be used in templates. In Listing 7-1, the `link_to()` function is a helper. Sometimes, helpers are just time-savers, packaging code snippets frequently used in templates. For instance, you can easily imagine the function definition for this helper:
 32
 33    [php]
 34    <?php echo image_tag('photo.jpg') ?>
 35     => <img src="/images/photo.jpg" />
 36
 37It should look like Listing 7-2.
 38
 39Listing 7-2 - Sample Helper Definition
 40
 41    [php]
 42    function image_tag($source)
 43    {
 44      return '<img src="/images/'.$source.'" />';
 45    }
 46
 47As a matter of fact, the `image_tag()` function built into symfony is a little more complicated than that, as it accepts a second parameter to add other attributes to the `<img>` tag. You can check its complete syntax and options in the online [API documentation](http://www.symfony-project.org/api/1_4/).
 48
 49Most of the time, helpers carry intelligence and save you long and complex coding:
 50
 51    [php]
 52    <?php echo auto_link_text('Please visit our website www.example.com') ?>
 53     => Please visit our website <a href="http://www.example.com">www.example.com</a>
 54
 55Helpers facilitate the process of writing templates and produce the best possible HTML code in terms of performance and accessibility. You can always use plain HTML, but helpers are usually faster to write.
 56
 57>**TIP**
 58>You may wonder why the helpers are named according to the underscore syntax rather than the camelCase convention, used everywhere else in symfony. This is because helpers are functions, and all the core PHP functions use the underscore syntax convention.
 59
 60#### Declaring Helpers
 61
 62The symfony files containing helper definitions are not autoloaded (since they contain functions, not classes). Helpers are grouped by purpose. For instance, all the helper functions dealing with text are defined in a file called `TextHelper.php`, called the `Text` helper group. So if you need to use a helper in a template, you must load the related helper group earlier in the template by declaring it with the `use_helper()` function. Listing 7-3 shows a template using the `auto_link_text()` helper, which is part of the `Text` helper group.
 63
 64Listing 7-3 - Declaring the Use of a Helper
 65
 66    [php]
 67    // Use a specific helper group in this template
 68    <?php use_helper('Text') ?>
 69    ...
 70    <h1>Description</h1>
 71    <p><?php echo auto_link_text($description) ?></p>
 72
 73>**TIP**
 74>If you need to declare more than one helper group, add more arguments to the `use_helper()` call. For instance, to load both the `Text` and the `Javascript` helper groups in a template, call `<?php use_helper('Text', 'Javascript') ?>`.
 75
 76A few helpers are available by default in every template, without need for declaration. These are helpers of the following helper groups:
 77
 78  * `Helper`: Required for helper inclusion (the `use_helper()` function is, in fact, a helper itself)
 79  * `Tag`: Basic tag helper, used by almost every helper
 80  * `Url`: Links and URL management helpers
 81  * `Asset`: Helpers populating the HTML `<head>` section, and providing easy links to external assets (images, JavaScript, and style sheet files)
 82  * `Partial`: Helpers allowing for inclusion of template fragments
 83  * `Cache`: Manipulation of cached code fragments
 84
 85The list of the standard helpers, loaded by default for every template, is configurable in the `settings.yml` file. So if you know that you will not use the helpers of the `Cache` group, or that you will always use the ones of the Text group, modify the `standard_helpers` setting accordingly. This will speed up your application a bit. You cannot remove the first four helper groups in the preceding list (`Helper`, `Tag`, `Url`, and `Asset`), because they are compulsory for the templating engine to work properly. Consequently, they don't even appear in the list of standard helpers.
 86
 87>**TIP**
 88>If you ever need to use a helper outside a template, you can still load a helper group from anywhere by calling `sfProjectConfiguration::getActive()->loadHelpers($helpers)`, where `$helpers` is a helper group name or an array of helper group names. For instance, if you want to use `auto_link_text()` in an action, you need to call `sfProjectConfiguration::getActive()->loadHelpers('Text')` first.
 89
 90#### Frequently Used Helpers
 91
 92You will learn about some helpers in detail in later chapters, in relation with the feature they are helping. Listing 7-4 gives a brief list of the default helpers that are used a lot, together with the HTML code they return.
 93
 94Listing 7-4 - Common Default Helpers
 95
 96    [php]
 97    // Helper group
 98    <?php use_helper('HelperName') ?>
 99    <?php use_helper('HelperName1', 'HelperName2', 'HelperName3') ?>
100
101    // Url group
102    <?php echo link_to('click me', 'mymodule/myaction') ?>
103    => <a href="/route/to/myaction">click me</a>  // Depends on the routing settings
104
105    // Asset group
106    <?php echo image_tag('myimage', 'alt=foo size=200x100') ?>
107     => <img src="/images/myimage.png" alt="foo" width="200" height="100"/>
108    <?php echo javascript_include_tag('myscript') ?>
109     => <script language="JavaScript" type="text/javascript" src="/js/myscript.js"></script>
110    <?php echo stylesheet_tag('style') ?>
111     => <link href="/stylesheets/style.css" media="screen" rel="stylesheet"type="text/css" />
112
113There are many other helpers in symfony, and it would take a full book to describe all of them. The best reference for helpers is the online [API documentation](http:// www.symfony-project.org/api/1_4/), where all the helpers are well documented, with their syntax, options, and examples.
114
115#### Adding Your Own Helpers
116
117Symfony ships with a lot of helpers for various purposes, but if you don't find what you need in the API documentation, you will probably want to create a new helper. This is very easy to do.
118
119Helper functions (regular PHP functions returning HTML code) should be saved in a file called `FooBarHelper.php`, where `FooBar` is the name of the helper group. Store the file in the `apps/frontend/lib/helper/` directory (or in any `helper/` directory created under one of the `lib/` folders of your project) so it can be found automatically by the `use_helper('FooBar')` helper for inclusion.
120
121>**TIP**
122>This system even allows you to override the existing symfony helpers. For instance, to redefine all the helpers of the `Text` helper group, just create a `TextHelper.php` file in your `apps/frontend/lib/helper/` directory. Whenever you call `use_helper('Text')`, symfony will use your helper group rather than its own. But be careful: as the original file is not even loaded, you must redefine all the functions of a helper group to override it; otherwise, some of the original helpers will not be available at all.
123
124### Page Layout
125
126The template shown in Listing 7-1 is not a valid XHTML document. The `DOCTYPE` definition and the `<html>` and `<body>` tags are missing. That's because they are stored somewhere else in the application, in a file called `layout.php`, which contains the page layout. This file, also called the global template, stores the HTML code that is common to all pages of the application to avoid repeating it in every template. The content of the template is integrated into the layout, or, if you change the point of view, the layout "decorates" the template. This is an application of the decorator design pattern, illustrated in Figure 7-1.
127
128>**TIP**
129>For more information about the decorator and other design patterns, see *Patterns of Enterprise Application Architecture* by Martin Fowler (Addison-Wesley, ISBN: 0-32112-742-0).
130
131Figure 7-1 - Decorating a template with a layout
132
133![Decorating a template with a layout](http://www.symfony-project.org/images/book/1_4/F0701.png "Decorating a template with a layout")
134
135Listing 7-5 shows the default page layout, located in the application `templates/` directory.
136
137Listing 7-5 - Default Layout, in `myproject/apps/frontend/templates/layout.php`
138
139    [php]
140    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
141    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
142      <head>
143        <?php include_javascripts() ?>
144        <?php include_stylesheets() ?>
145        <?php include_http_metas() ?>
146        <?php include_metas() ?>
147        <?php include_title() ?>
148        <link rel="shortcut icon" href="/favicon.ico" />
149      </head>
150      <body>
151        <?php echo $sf_content ?>
152      </body>
153    </html>
154
155The helpers called in the `<head>` section grab information from the response object and the view configuration. The `<body>` tag outputs the result of the template. With this layout, the default configuration, and the sample template in Listing 7-1, the processed view looks like Listing 7-6.
156
157Listing 7-6 - The Layout, the View Configuration, and the Template Assembled
158
159    [php]
160    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
161    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
162      <head>
163        <meta http-equiv="content-type" content="text/html; charset=utf-8" />
164        <meta name="title" content="symfony project" />
165        <meta name="robots" content="index, follow" />
166        <meta name="description" content="symfony project" />
167        <meta name="keywords" content="symfony, project" />
168        <title>symfony project</title>
169        <link rel="stylesheet" type="text/css" href="/css/main.css" />
170        <link rel="shortcut icon" href="/favicon.ico">
171      </head>
172      <body>
173        <h1>Welcome</h1>
174        <p>Welcome back, <?php echo $name ?>!</p>
175        <ul>What would you like to do?
176          <li><?php echo link_to('Read the last articles', 'article/read') ?></li>
177          <li><?php echo link_to('Start writing a new one', 'article/write') ?></li>
178        </ul>
179      </body>
180    </html>
181
182The global template can be entirely customized for each application. Add in any HTML code you need. This layout is often used to hold the site navigation, logo, and so on. You can even have more than one layout, and decide which layout should be used for each action. Don't worry about JavaScript and style sheet inclusion for now; the "View Configuration" section later in this chapter shows how to handle that.
183
184### Template Shortcuts
185
186In templates, a few symfony variables are always available. These shortcuts give access to the most commonly needed information in templates, through the core symfony objects:
187
188  * `$sf_context`: The whole context object (`instance of sfContext`)
189  * `$sf_request`: The request object (`instance of sfRequest`)
190  * `$sf_params` : The parameters of the request object
191  * `$sf_user`   : The current user session object (`instance of sfUser`)
192
193The previous chapter detailed useful methods of the `sfRequest` and `sfUser` objects. You can actually call these methods in templates through the `$sf_request` and `$sf_user` variables. For instance, if the request includes a `total` parameter, its value is available in the template with the following:
194
195    [php]
196    // Long version
197    <?php echo $sf_request->getParameter('total') ?>
198
199    // Shorter version
200    <?php echo $sf_params->get('total') ?>
201
202    // Equivalent to the following action code
203    echo $request->getParameter('total')
204
205Code Fragments
206--------------
207
208You may often need to include some HTML or PHP code in several pages. To avoid repeating that code, the PHP `include()` statement will suffice most of the time.
209
210For instance, if many of the templates of your application need to use the same fragment of code, save it in a file called `myFragment.php` in the global template directory (`myproject/apps/frontend/templates/`) and include it in your templates as follows:
211
212    [php]
213    <?php include(sfConfig::get('sf_app_template_dir').'/myFragment.php') ?>
214
215But this is not a very clean way to package a fragment, mostly because you can have different variable names between the fragment and the various templates including it. In addition, the symfony cache system (described in Chapter 12) has no way to detect an include, so the fragment cannot be cached independently from the template. Symfony provides three alternative types of intelligent code fragments to replace `include`s:
216
217  * If the logic is lightweight, you will just want to include a template file having access to some data you pass to it. For that, you will use a partial.
218  * If the logic is heavier (for instance, if you need to access the data model and/or modify the content according to the session), you will prefer to separate the presentation from the logic. For that, you will use a component.
219  * If the fragment is meant to replace a specific part of the layout, for which default content may already exist, you will use a slot.
220
221The inclusion of these fragments is achieved by helpers of the `Partial` group. These helpers are available from any symfony template, without initial declaration.
222
223### Partials
224
225A partial is a reusable chunk of template code. For instance, in a publication application, the template code displaying an article is used in the article detail page, and also in the list of the best articles and the list of latest articles. This code is a perfect candidate for a partial, as illustrated in Figure 7-2.
226
227Figure 7-2 - Reusing partials in templates
228
229![Reusing partials in templates](http://www.symfony-project.org/images/book/1_4/F0702.png "Reusing partials in templates")
230
231Just like templates, partials are files located in the `templates/` directory, and they contain HTML code with embedded PHP. A partial file name always starts with an underscore (`_`), and that helps to distinguish partials from templates, since they are located in the same `templates/` folders.
232
233A template can include partials whether it is in the same module, in another module, or in the global `templates/` directory. Include a partial by using the `include_partial()` helper, and specify the module and partial name as a parameter (but omit the leading underscore and the trailing `.php`), as described in Listing 7-7.
234
235Listing 7-7 - Including a Partial in a Template of the `mymodule` Module
236
237    [php]
238    // Include the frontend/modules/mymodule/templates/_mypartial1.php partial
239    // As the template and the partial are in the same module,
240    // you can omit the module name
241    <?php include_partial('mypartial1') ?>
242
243    // Include the frontend/modules/foobar/templates/_mypartial2.php partial
244    // The module name is compulsory in that case
245    <?php include_partial('foobar/mypartial2') ?>
246
247    // Include the frontend/templates/_mypartial3.php partial
248    // It is considered as part of the 'global' module
249    <?php include_partial('global/mypartial3') ?>
250
251Partials have access to the usual symfony helpers and template shortcuts. But since partials can be called from anywhere in the application, they do not have automatic access to the variables defined in the action calling the templates that includes them, unless passed explicitly as an argument. For instance, if you want a partial to have access to a `$total` variable, the action must hand it to the template, and then the template to the helper as a second argument of the `include_partial()` call, as shown in Listings 7-8, 7-9, and 7-10.
252
253Listing 7-8 - The Action Defines a Variable, in `mymodule/actions/actions.class.php`
254
255    [php]
256    class mymoduleActions extends sfActions
257    {
258      public function executeIndex()
259      {
260        $this->total = 100;
261      }
262    }
263
264Listing 7-9 - The Template Passes the Variable to the Partial, in `mymodule/templates/indexSuccess.php`
265
266    [php]
267    <p>Hello, world!</p>
268    <?php include_partial('mypartial', array('mytotal' => $total)) ?>
269
270Listing 7-10 - The Partial Can Now Use the Variable, in `mymodule/templates/_mypartial.php`
271
272    [php]
273    <p>Total: <?php echo $mytotal ?></p>
274
275>**TIP**
276>All the helpers so far were called by `<?php echo functionName() ?>`. The partial helper, however, is simply called by `<?php include_partial() ?>`, without `echo`, to make it behave similar to the regular PHP `include()` statement. If you ever need a function that returns the content of a partial without actually displaying it, use `get_partial()` instead. All the `include_` helpers described in this chapter have a `get_` counterpart that can be called together with an `echo` statement.
277
278>**TIP**
279>Instead of resulting in a template, an action can return a partial or a component. The `renderPartial()` and `renderComponent()` methods of the action class promote reusability of code. Besides, they take advantage of the caching abilities of the partials (see Chapter 12). The variables defined in the action will be automatically passed to the partial/component, unless you define an associative array of variables as a second parameter of the method.
280>
281>     [php]
282>     public function executeFoo()
283>     {
284>       // do things
285>       $this->foo = 1234;
286>       $this->bar = 4567;
287>
288>       return $this->renderPartial('mymodule/mypartial');
289>     }
290>
291>In this example, the partial will have access to `$foo` and `$bar`. If the action ends with the following line:
292>
293>       return $this->renderPartial('mymodule/mypartial', array('foo' => $this->foo));
294>
295>Then the partial will only have access to `$foo`.
296
297### Components
298
299In Chapter 2, the first sample script was split into two parts to separate the logic from the presentation. Just like the MVC pattern applies to actions and templates, you may need to split a partial into a logic part and a presentation part. In such a case, you should use a component.
300
301A component is like an action, except it's much faster. The logic of a component is kept in a class inheriting from `sfComponents`, located in an `actions/components.class.php` file. Its presentation is kept in a partial. Methods of the `sfComponents` class start with the word `execute`, just like actions, and they can pass variables to their presentation counterpart in the same way that actions can pass variables. Partials that serve as presentation for components are named by the component (without the leading `execute`, but with an underscore instead). Table 7-1 compares the naming conventions for actions and components.
302
303Table 7-1 - Action and Component Naming Conventions
304
305Convention               |  Actions              |  Components
306------------------------ | --------------------- | ----------------------
307Logic file               | `actions.class.php`   | `components.class.php`
308Logic class extends      | `sfActions`           | `sfComponents`
309Method naming            | `executeMyAction()`   | `executeMyComponent()`
310Presentation file naming | `myActionSuccess.php` | `_myComponent.php`
311
312>**TIP**
313>Just as you can separate actions files, the `sfComponents` class has an `sfComponent` counterpart that allows for single component files with the same type of syntax.
314
315For instance, suppose you have a sidebar displaying the latest news headlines for a given subject, depending on the user's profile, which is reused in several pages. The queries necessary to get the news headlines are too complex to appear in a simple partial, so they need to be moved to an action-like file--a component. Figure 7-3 illustrates this example.
316
317For this example, shown in Listings 7-11 and 7-12, the component will be kept in its own module (called `news`), but you can mix components and actions in a single module if it makes sense from a functional point of view.
318
319Figure 7-3 - Using components in templates
320
321![Using components in templates](http://www.symfony-project.org/images/book/1_4/F0703.png "Using components in templates")
322
323Listing 7-11 - The Components Class, in `modules/news/actions/components.class.php`
324
325    [php]
326    <?php
327
328    class newsComponents extends sfComponents
329    {
330      public function executeHeadlines()
331      {
332        $c = new Criteria();
333        $c->addDescendingOrderByColumn(NewsPeer::PUBLISHED_AT);
334        $c->setLimit(5);
335        $this->news = NewsPeer::doSelect($c);
336      }
337    }
338
339Listing 7-12 - The Partial, in `modules/news/templates/_headlines.php`
340
341    [php]
342    <div>
343      <h1>Latest news</h1>
344      <ul>
345      <?php foreach($news as $headline): ?>
346        <li>
347          <?php echo $headline->getPublishedAt() ?>
348          <?php echo link_to($headline->getTitle(),'news/show?id='.$headline->getId()) ?>
349        </li>
350      <?php endforeach ?>
351      </ul>
352    </div>
353
354Now, every time you need the component in a template, just call this:
355
356    [php]
357    <?php include_component('news', 'headlines') ?>
358
359Just like the partials, components accept additional parameters in the shape of an associative array. The parameters are available to the partial under their name, and in the component via the `$this` object. See Listing 7-13 for an example.
360
361Listing 7-13 - Passing Parameters to a Component and Its Template
362
363    [php]
364    // Call to the component
365    <?php include_component('news', 'headlines', array('foo' => 'bar')) ?>
366
367    // In the component itself
368    echo $this->foo;
369     => 'bar'
370
371    // In the _headlines.php partial
372    echo $foo;
373     => 'bar'
374
375You can include components in components, or in the global layout, as in any regular template. Like actions, components' `execute` methods can pass variables to the related partial and have access to the same shortcuts. But the similarities stop there. A component doesn't handle security or validation, cannot be called from the Internet (only from the application itself), and doesn't have various return possibilities. That's why a component is faster to execute than an action.
376
377### Slots
378
379Partials and components are great for reusability. But in many cases, code fragments are required to fill a layout with more than one dynamic zone. For instance, suppose that you want to add some custom tags in the `<head>` section of the layout, depending on the content of the action. Or, suppose that the layout has one major dynamic zone, which is filled by the result of the action, plus a lot of other smaller ones, which have a default content defined in the layout but can be overridden at the template level.
380
381For these situations, the solution is a slot. Basically, a slot is a placeholder that you can put in any of the view elements (in the layout, a template, or a partial). Filling this placeholder is just like setting a variable. The filling code is stored globally in the response, so you can define it anywhere (in the layout, a template, or a partial). Just make sure to define a slot before including it, and remember that the layout is executed after the template (this is the decoration process), and the partials are executed when they are called in a template. Does it sound too abstract? Let's see an example.
382
383Imagine a layout with one zone for the template and two slots: one for the sidebar and the other for the footer. The slot values are defined in the templates. During the decoration process, the layout code wraps the template code, and the slots are filled with the previously defined values, as illustrated in Figure 7-4. The sidebar and the footer can then be contextual to the main action. This is like having a layout with more than one "hole".
384
385Figure 7-4 - Layout slots defined in a template
386
387![Layout slots defined in a template](http://www.symfony-project.org/images/book/1_4/F0704.png "Layout slots defined in a template")
388
389Seeing some code will clarify things further. To include a slot, use the `include_slot()` helper. The `has_slot()` helper returns `true` if the slot has been defined before, providing a fallback mechanism as a bonus. For instance, define a placeholder for a `'sidebar'` slot in the layout and its default content as shown in Listing 7-14.
390
391Listing 7-14 - Including a `'sidebar'` Slot in the Layout
392
393    [php]
394    <div id="sidebar">
395    <?php if (has_slot('sidebar')): ?>
396      <?php include_slot('sidebar') ?>
397    <?php else: ?>
398      <!-- default sidebar code -->
399      <h1>Contextual zone</h1>
400      <p>This zone contains links and information
401      relative to the main content of the page.</p>
402    <?php endif; ?>
403    </div>
404
405As it's quite common to display some default content if a slot is not defined, the `include_slot` helper returns a Boolean indicating if the slot has been defined. Listing 7-15 shows how to take this return value into account to simplify the code.
406
407Listing 7-15 - Including a `'sidebar'` Slot in the Layout
408
409    [php]
410    <div id="sidebar">
411    <?php if (!include_slot('sidebar')): ?>
412      <!-- default sidebar code -->
413      <h1>Contextual zone</h1>
414      <p>This zone contains links and information
415      relative to the main content of the page.</p>
416    <?php endif; ?>
417    </div>
418
419Each template has the ability to define the contents of a slot (actually, even partials can do it). As slots are meant to hold HTML code, symfony offers a convenient way to define them: just write the slot code between a call to the `slot()` and `end_slot()` helpers, as in Listing 7-16.
420
421Listing 7-16 - Overriding the `'sidebar'` Slot Content in a Template
422
423    [php]
424    // ...
425
426    <?php slot('sidebar') ?>
427      <!-- custom sidebar code for the current template-->
428      <h1>User details</h1>
429      <p>name:  <?php echo $user->getName() ?></p>
430      <p>email: <?php echo $user->getEmail() ?></p>
431    <?php end_slot() ?>
432
433The code between the slot helpers is executed in the context of the template, so it has access to all the variables that were defined in the action. Symfony will automatically put the result of this code in the response object. It will not be displayed in the template, but made available for future `include_slot()` calls, like the one in Listing 7-14.
434
435Slots are very useful to define zones meant to display contextual content. They can also be used to add HTML code to the layout for certain actions only. For instance, a template displaying the list of the latest news might want to add a link to an RSS feed in the `<head>` part of the layout. This is achieved simply by adding a `'feed'` slot in the layout and overriding it in the template of the list.
436
437If the content of the slot is very short, as this is the case when defining a `title` slot for example, you can simply pass the content as a second argument of the `slot()` method as shown in Listing 7-17.
438
439Listing 7-17 - Using `slot()` to define a short Value
440
441    [php]
442    <?php slot('title', 'The title value') ?>
443
444>**SIDEBAR**
445>Where to find template fragments
446>
447>People working on templates are usually web designers, who may not know symfony very well and may have difficulties finding template fragments, since they can be scattered all over the application. These few guidelines will make them more comfortable with the symfony templating system.
448>
449>First of all, although a symfony project contains many directories, all the layouts, templates, and template fragments files reside in directories named `templates/`. So as far as a web designer is concerned, a project structure can be reduced to something like this:
450>
451>
452>     myproject/
453>       apps/
454>         application1/
455>           templates/       # Layouts for application 1
456>           modules/
457>             module1/
458>               templates/   # Templates and partials for module 1
459>             module2/
460>               templates/   # Templates and partials for module 2
461>             module3/
462>               templates/   # Templates and partials for module 3
463>
464>
465>All other directories can be ignored.
466>
467>When meeting an `include_partial()`, web designers just need to understand that only the first argument is important. This argument's pattern is `module_name/partial_name`, and that means that the presentation code is to be found in `modules/module_name/templates/_partial_name.php`.
468>
469>For the `include_component()` helper, module name and partial name are the first two arguments. As for the rest, a general idea about what helpers are and which helpers are the most common in templates should be enough to start designing templates for symfony applications.
470
471View Configuration
472------------------
473
474In symfony, a view consists of two distinct parts:
475
476  * The HTML presentation of the action result (stored in the template, in the layout, and in the template fragments)
477  * All the rest, including the following:
478
479    * Meta declarations: Keywords, description, or cache duration.
480    * Page title: Not only does it help users with several browser windows open to find yours, but it is also very important for search sites' indexing.
481    * File inclusions: JavaScript and style sheet files.
482    * Layout: Some actions require a custom layout (pop-ups, ads, and so on) or no layout at all (such as Ajax actions).
483
484In the view, all that is not HTML is called view configuration, and symfony provides two ways to manipulate it. The usual way is through the `view.yml` configuration file. It can be used whenever the values don't depend on the context or on database queries. When you need to set dynamic values, the alternative method is to set the view configuration via the `sfResponse` object attributes directly in the action.
485
486>**NOTE**
487>If you ever set a view configuration parameter both via the `sfResponse` object and via the `view.yml` file, the `sfResponse` definition takes precedence.
488
489### The `view.yml` File
490
491Each module can have one `view.yml` file defining the settings of its views. This allows you to define view settings for a whole module and per view in a single file. The first-level keys of the `view.yml` file are the module view names. Listing 7-18 shows an example of view configuration.
492
493Listing 7-18 - Sample Module-Level `view.yml`
494
495    editSuccess:
496      metas:
497        title: Edit your profile
498
499    editError:
500      metas:
501        title: Error in the profile edition
502
503    all:
504      stylesheets: [my_style]
505      metas:
506        title: My website
507
508>**CAUTION**
509>Be aware that the main keys in the `view.yml` file are view names, not action names. As a reminder, a view name is composed of an action name and an action termination. For instance, if the `edit` action returns `sfView::SUCCESS` (or returns nothing at all, since it is the default action termination), then the view name is `editSuccess`.
510
511The default settings for the module are defined under the `all:` key in the module `view.yml`. The default settings for all the application views are defined in the application `view.yml`. Once again, you recognize the configuration cascade principle:
512
513  * In `apps/frontend/modules/mymodule/config/view.yml`, the per-view definitions apply only to one view and override the module-level definitions.
514  * In `apps/frontend/modules/mymodule/config/view.yml`, the `all:` definitions apply to all the actions of the module and override the application-level definitions.
515  * In `apps/frontend/config/view.yml`, the `default:` definitions apply to all modules and all actions of the application.
516
517>**TIP**
518>Module-level `view.yml` files don't exist by default. The first time you need to adjust a view configuration parameter for a module, you will have to create an empty `view.yml` in its `config/` directory.
519
520After seeing the default template in Listing 7-5 and an example of a final response in Listing 7-6, you may wonder where the header values come from. As a matter of fact, they are the default view settings, defined in the application `view.yml` and shown in Listing 7-19.
521
522Listing 7-19 - Default Application-Level View Configuration, in `apps/frontend/config/view.yml`
523
524    default:
525      http_metas:
526        content-type: text/html
527
528      metas:
529        #title:        symfony project
530        #description:  symfony project
531        #keywords:     symfony, project
532        #language:     en
533        #robots:       index, follow
534
535      stylesheets:    [main]
536
537      javascripts:    []
538
539      has_layout:     true
540      layout:         layout
541
542Each of these settings will be described in detail in the "View Configuration Settings" section.
543
544### The Response Object
545
546Although part of the view layer, the response object is often modified by the action. Actions can access the symfony response object, called `sfResponse`, via the `getResponse()` method. Listing 7-20 lists some of the `sfResponse` methods often used from within an action.
547
548Listing 7-20 - Actions Have Access to the `sfResponse` Object Methods
549
550    [php]
551    class mymoduleActions extends sfActions
552    {
553      public function executeIndex()
554      {
555        $response = $this->getResponse();
556
557        // HTTP headers
558        $response->setContentType('text/xml');
559        $response->setHttpHeader('Content-Language', 'en');
560        $response->setStatusCode(403);
561        $response->addVaryHttpHeader('Accept-Language');
562        $response->addCacheControlHttpHeader('no-cache');
563
564        // Cookies
565        $response->setCookie($name, $content, $expire, $path, $domain);
566
567        // Metas and page headers
568        $response->addMeta('robots', 'NONE');
569        $response->addMeta('keywords', 'foo bar');
570        $response->setTitle('My FooBar Page');
571        $response->addStyleSheet('custom_style');
572        $response->addJavaScript('custom_behavior');
573      }
574    }
575
576In addition to the setter methods shown here, the `sfResponse` class has getters that return the current value of the response attributes.
577
578The header setters are very powerful in symfony. Headers are sent as late as possible (in the `sfRenderingFilter`), so you can alter them as much as you want and as late as you want. They also provide very useful shortcuts. For instance, if you don't specify a charset when you call `setContentType()`, symfony automatically adds the default charset defined in the `settings.yml` file.
579
580    [php]
581    $response->setContentType('text/xml');
582    echo $response->getContentType();
583     => 'text/xml; charset=utf-8'
584
585The status code of responses in symfony is compliant with the HTTP specification. Exceptions return a status 500, pages not found return a status 404, normal pages return a status 200, pages not modified can be reduced to a simple header with status code 304 (see Chapter 12 for details), and so on. But you can override these defaults by setting your own status code in the action with the `setStatusCode()` response method. You can specify a custom code and a custom message, or simply a custom code--in which case, symfony will add the most common message for this code.
586
587    [php]
588    $response->setStatusCode(404, 'This page does not exist');
589
590>**TIP**
591>Before sending the headers, symfony normalizes their names. So you don't need to bother about writing `content-language` instead of `Content-Language` in a call to `setHttpHeader()`, as symfony will understand the former and automatically transform it to the latter.
592
593### View Configuration Settings
594
595You may have noticed that there are two kinds of view configuration settings:
596
597  * The ones that have a unique value (the value is a string in the `view.yml` file and the response uses a `set` method for those)
598  * The ones with multiple values (for which `view.yml` uses arrays and the response uses an `add` method)
599
600Keep in mind that the configuration cascade erases the unique value settings but piles up the multiple values settings. This will become more apparent as you progress through this chapter.
601
602#### Meta Tag Configuration
603
604The information written in the `<meta>` tags in the response is not displayed in a browser but is useful for robots and search engines. It also controls the cache settings of every page. Define these tags under the `http_metas:` and `metas:` keys in `view.yml`, as in Listing 7-21, or with the `addHttpMeta()` and `addMeta()` response methods in the action, as in Listing 7-22.
605
606Listing 7-21 - Meta Definition As Key: Value Pairs in `view.yml`
607
608    http_metas:
609      cache-control: public
610
611    metas:
612      description:   Finance in France
613      keywords:      finance, France
614
615Listing 7-22 - Meta Definition As Response Settings in the Action
616
617    [php]
618    $this->getResponse()->addHttpMeta('cache-control', 'public');
619    $this->getResponse()->addMeta('description', 'Finance in France');
620    $this->getResponse()->addMeta('keywords', 'finance, France');
621
622Adding an existing key will replace its current content by default. For HTTP meta tags, you can add a third parameter and set it to `false` to have the `addHttpMeta()` method (as well as the `setHttpHeader()`) append the value to the existing one, rather than replacing it.
623
624    [php]
625    $this->getResponse()->addHttpMeta('accept-language', 'en');
626    $this->getResponse()->addHttpMeta('accept-language', 'fr', false);
627    echo $this->getResponse()->getHttpHeader('accept-language');
628     => 'en, fr'
629
630In order to have these meta tags appear in the final document, the `include_http_metas()` and `include_metas()` helpers must be called in the `<head>` section (this is the case in the default layout; see Listing 7-5). Symfony automatically aggregates the settings from all the `view.yml` files (including the default one shown in Listing 7-18) and the response attribute to output proper `<meta>` tags. The example in Listing 7-21 ends up as shown in Listing 7-23.
631
632Listing 7-23 - Meta Tags Output in the Final Page
633
634    [php]
635    <meta http-equiv="content-type" content="text/html; charset=utf-8" />
636    <meta http-equiv="cache-control" content="public" />
637    <meta name="robots" content="index, follow" />
638    <meta name="description" content="Finance in France" />
639    <meta name="keywords" content="finance, France" />
640
641As a bonus, the HTTP header of the response is also impacted by the `http-metas:` definition, even if you don't have any `include_http_metas()` helpers in the layout, or if you have no layout at all. For instance, if you need to send a page as plain text, define the following `view.yml`:
642
643    http_metas:
644      content-type: text/plain
645
646    has_layout: false
647
648#### Title Configuration
649
650The page title is a key part to search engine indexing. It is also very useful with modern browsers that provide tabbed browsing. In HTML, the title is both a tag and meta information of the page, so the `view.yml` file sees the `title:` key as a child of the `metas:` key. Listing 7-24 shows the title definition in `view.yml`, and Listing 7-25 shows the definition in the action.
651
652Listing 7-24 - Title Definition in `view.yml`
653
654    indexSuccess:
655      metas:
656        title: Three little piggies
657
658Listing 7-25 - Title Definition in the Action--Allows for Dynamic Titles
659
660    [php]
661    $this->getResponse()->setTitle(sprintf('%d little piggies', $number));
662
663In the `<head>` section of the final document, the title definition sets the `<meta name="title">` tag if the `include_metas()` helper is present, and the `<title>` tag if the `include_title()` helper is present. If both are included (as in the default layout of Listing 7-5), the title appears twice in the document source (see Listing 7-6), which is harmless.
664
665#### File Inclusion Configuration
666
667Adding a specific style sheet or JavaScript file to a view is easy, as Listing 7-26 demonstrates.
668
669Listing 7-26 - Asset File Inclusion
670
671    [yml]
672    // In the view.yml
673    indexSuccess:
674      stylesheets: [mystyle1, mystyle2]
675      javascripts: [myscript]
676      
677-
678
679    [php]
680    // In the action
681    $this->getResponse()->addStylesheet('mystyle1');
682    $this->getResponse()->addStylesheet('mystyle2');
683    $this->getResponse()->addJavascript('myscript');
684
685    // In the Template
686    <?php use_stylesheet('mystyle1') ?>
687    <?php use_stylesheet('mystyle2') ?>
688    <?php use_javascript('myscript') ?>
689    
690In each case, the argument is a file name. If the file has a logical extension (`.css` for a style sheet and `.js` for a JavaScript file), you can omit it. If the file has a logical location (`/css/` for a style sheet and `/js/` for a JavaScript file), you can omit it as well. Symfony is smart enough to figure out the correct extension or location.
691
692Like the meta and title definitions, the file inclusion definitions require the usage of the `include_javascripts()` and `include_stylesheets()` helpers in the template or layout to be included. This means that the previous settings will output the HTML code of Listing 7-27.
693
694Listing 7-27 - File Inclusion Result
695
696    [php]
697    <head>
698    ...
699    <link rel="stylesheet" type="text/css" media="screen" href="/css/mystyle1.css" />
700    <link rel="stylesheet" type="text/css" media="screen" href="/css/mystyle2.css" />
701    <script language="javascript" type="text/javascript" src="/js/myscript.js">
702    </script>
703    </head>
704
705Remember that the configuration cascade principle applies, so any file inclusion defined in the application `view.yml` makes it appear in every page of the application. Listings 7-28, 7-29, and 7-30 demonstrate this principle.
706
707Listing 7-28 - Sample Application `view.yml`
708
709    default:
710      stylesheets: [main]
711
712Listing 7-29 - Sample Module `view.yml`
713
714    indexSuccess:
715      stylesheets: [special]
716
717    all:
718      stylesheets: [additional]
719
720Listing 7-30 - Resulting `indexSuccess` View
721
722    [php]
723    <link rel="stylesheet" type="text/css" media="screen" href="/css/main.css" />
724    <link rel="stylesheet" type="text/css" media="screen" href="/css/additional.css" />
725    <link rel="stylesheet" type="text/css" media="screen" href="/css/special.css" />
726
727If you need to remove a file defined at a higher level, just add a minus sign (`-`) in front of the file name in the lower-level definition, as shown in Listing 7-31.
728
729Listing 7-31 - Sample Module `view.yml` That Removes a File Defined at the Application Level
730
731    indexSuccess:
732      stylesheets: [-main, special]
733
734    all:
735      stylesheets: [additional]
736
737To remove all style sheets or JavaScript files, use `-*` as a file name, as shown in Listing 7-32.
738
739Listing 7-32 - Sample Module `view.yml` That Removes all Files Defined at the Application Level
740
741    indexSuccess:
742      stylesheets: [-*]
743      javascripts: [-*]
744
745You can be more accurate and define an additional parameter to force the position where to include the file (first or last position), as shown in Listing 7-33. This works for both style sheets and JavaScript files.
746
747Listing 7-33 - Defining the Position of the Included Asset
748
749    [yml]
750    // In the view.yml
751    indexSuccess:
752      stylesheets: [special: { position: first }]
753
754-
755    
756    [php]
757    // In the action
758    $this->getResponse()->addStylesheet('special', 'first');
759    
760    // In the template
761    <?php use_stylesheet('special', 'first') ?>
762
763You can also decide to bypass the transformation of the asset file name, so that the resulting `<link>` or `<script>` tags refer to the exact location specified, as show in Listing 7-34.
764
765Listing 7-34 - Style Sheet Inclusion with Raw Name
766
767    [yml]
768    // In the view.yml
769    indexSuccess:
770      stylesheets: [main, paper: { raw_name: true }]
771
772-
773    
774    [php]
775    // In the Action
776    $this->getResponse()->addStylesheet('main', '', array('raw_name' => true));
777    
778    // In the template
779    <?php use_stylesheet('main', '', array('raw_name' => true)) ?>
780    
781    // Resulting View
782    <link rel="stylesheet" type="text/css" href="main" />
783
784To specify media for a style sheet inclusion, you can change the default style sheet tag options, as shown in Listing 7-35.
785
786Listing 7-35 - Style Sheet Inclusion with Media
787
788    [yml]
789    // In the view.yml
790    indexSuccess:
791      stylesheets: [main, paper: { media: print }]
792
793-
794    
795    [php]
796    // In the Action
797    $this->getResponse()->addStylesheet('paper', '', array('media' => 'print'));
798    
799    // In the template
800    <?php use_stylesheet('paper', '', array('media' => 'print')) ?>
801    
802    // Resulting View
803    <link rel="stylesheet" type="text/css" media="print" href="/css/paper.css" />
804
805#### Layout Configuration
806
807According to the graphical charter of your website, you may have several layouts. Classic websites have at least two: the default layout and the pop-up layout.
808
809You have already seen that the default layout is `myproject/apps/frontend/templates/layout.php`. Additional layouts must be added in the same global `templates/` directory. If you want a view to use a `frontend/templates/my_layout.php` file, use the syntax shown in Listing 7-36.
810
811Listing 7-36 - Layout Definition
812
813    [yml]
814    // In view.yml
815    indexSuccess:
816      layout: my_layout
817
818-
819
820    [php]
821    // In the action
822    $this->setLayout('my_layout');
823    
824    // In the template
825    <?php decorate_with('my_layout') ?>
826
827Some views don't need any layout at all (for instance, plain text pages or RSS feeds). In that case, set `has_layout` to `false`, as shown in Listing 7-37.
828
829Listing 7-37 - Layout Removal 
830
831    [yml]
832    // In `view.yml`
833    indexSuccess:
834      has_layout: false
835    
836-
837
838    [php]
839    // In the Action
840    $this->setLayout(false);
841    
842    // In the template
843    <?php decorate_with(false) ?>
844
845>**NOTE**
846>Ajax actions views have no layout by default.
847
848Output Escaping
849---------------
850
851When you insert dynamic data in a template, you must be sure about the data integrity. For instance, if data comes from forms filled in by anonymous users, there is a risk that it may include malicious scripts intended to launch cross-site scripting (XSS) attacks. You must be able to escape the output data, so that any HTML tag it contains becomes harmless.
852
853As an example, suppose that a user fills an input field with the following value:
854
855    [php]
856    <script>alert(document.cookie)</script>
857
858If you echo this value without caution, the JavaScript will execute on every browser and allow for much more dangerous attacks than just displaying an alert. This is why you must escape the value before displaying it, so that it becomes something like this:
859
860    [php]
861    &lt;script&gt;alert(document.cookie)&lt;/script&gt;
862
863You could escape your output manually by enclosing every unsure value in a call to `htmlspecialchars()`, but that approach would be very repetitive and error-prone. Instead, symfony provides a special system, called output escaping, which automatically escapes every variable output in a template. It is activated by default in the application `settings.yml`.
864
865### Activating Output Escaping
866
867Output escaping is configured globally for an application in the `settings.yml` file. Two parameters control the way that output escaping works: the strategy determines how the variables are made available to the view, and the method is the default escaping function applied to the data.
868
869Basically, all you need to do to activate output escaping is to set the `escaping_strategy` parameter to `true` (which is the default), as shown in Listing 7-38.
870
871Listing 7-38 - Activating Output Escaping, in `frontend/config/settings.yml`
872
873    all:
874      .settings:
875        escaping_strategy: true
876        escaping_method:   ESC_SPECIALCHARS
877
878This will add `htmlspecialchars()` to all variable output by default. For instance, suppose that you define a `test` variable in an action as follows:
879
880    [php]
881    $this->test = '<script>alert(document.cookie)</script>';
882
883With output escaping turned on, echoing this variable in the template will output the escaped data:
884
885    [php]
886    echo $test;
887     => &lt;script&gt;alert(document.cookie)&lt;/script&gt;
888
889In addition, every template has access to an `$sf_data` variable, which is a container object referencing all the escaped variables. So you can also output the test variable with the following:
890
891    [php]
892    echo $sf_data->get('test');
893    => &lt;script&gt;alert(document.cookie)&lt;/script&gt;
894
895>**TIP**
896>The $sf_data object implements the Array interface, so instead of using the `$sf_data->get('myvariable')`, you can retrieve escaped values by calling `$sf_data['myvariable']`. But it …

Large files files are truncated, but you can click here to view the full file