View Configuration
Overview
The View is made of:
- one part resulting of the action execution (the template)
- all the rest (headers, metas, file inclusions, slots and layout)
Symfony offers two convenient ways to modify the components of the View that are not part of the template.
The two ways to modify the view
Apart from the template itself, which integrates the variables calculated in the action into the view, every action needs control over other parts of the view:
- meta declarations: keywords, description or cache duration
- 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
- file inclusions: javascript and stylesheet files
- slots inclusions: navigation bar, header, footer, breadcrumb, etc.
- layout: some actions require a custom layout (popups, ads, ajax, etc.)
Ideally, all these parameters should be defined in a configuration file, so that the action can deal only with application logic and leave presentation to the view. However, in many cases, these parameters have dynamic values (for instance, page titles often show the title of articles) and cannot be kept in static configuration files. That's why symfony provides two ways to modify them:
- the
view.yml file, in which these parameters can be set at the application, module and action levels
- the view helpers, which are methods accessible from within the action.
According to the nature of the values that you need to give to these parameters, you will prefer one method or another. It is recommended that you keep as much configuration in the view.yml files as possible, since it separates clearly logic from presentation.
Note: the view.yml solution offers the advantage of inheritance and specialization. If you have to use the helpers in the action but you don't want to repeat them for every action, use the preExecute() and postExecute() methods of the module class to avoid repeating helpers for every action of a module.
View.yml structure
The scope of a view.yml varies according to the place where it is stored:
- in
myproject/apps/myapp/config/, the definitions will apply to all modules and all actions of the application
- in
myproject/apps/myapp/modules/mymodule/config/, the definitions will apply only to one module and override the application-level definitions
In addition, for the module-level files, you have the ability to specify custom definitions for a specific view (pair action/result of the action):
view1:
...
view2:
...
all:
...
The next sections will detail how the parameter definitions in this file can affect the view:
- http-metas: (associative array)
- metas: (associative array)
- title: page_name (string)
- stylesheets: [stylesheet1, stylesheet2, ...] (array)
- javascripts: [javascript1, javascript2, ...] (array)
- layout: layout_name (string)
- slots: (associative array)
- slot_name: [module, action] (array)
Default configuration
The default global template, created when you initialize an application, is called layout.php. It is located in myproject/apps/myapp/templates/ and looks like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-200000126/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<?php echo include_http_metas() ?>
<?php echo include_metas() ?>
<?php echo include_title() ?>
<link rel="shortcut icon" href="/favicon.ico">
</head>
<body>
<?php echo $content ?>
</body>
</html>
The default settings of the view, set in the application view configuration file myproject/apps/myapp/config/view.yml, are:
all:
http_metas:
content-type: text/html; charset=utf-8
metas:
title: symfony project
robots: index, follow
description: symfony project
keywords: symfony, project
stylesheets: [main]
javascripts: [ ]
has_layout: on
layout: layout
components: {}
When applied to the layout, these settings produce the following <head> section:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/2000/REC-xhtml1-200000126/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<meta name="title" content="symfony project" />
<meta name="robots" content="index, follow" />
<meta name="description" content="symfony project" />
<meta name="keywords" content="symfony, project" />
<title>symfony project</title>
<link rel="stylesheet" type="text/css" media="screen" href="/css/main.css" />
<link rel="shortcut icon" href="/favicon.ico">
</head>
<body>
<?php echo $content ?>
</body>
</html>
Besides the obvious use of the parameter definitions in the view.yml, this example shows that the <head> section of a page can be modified even if the code for this section is normally in a file shared by all modules.
View configuration could stop at that point if you wish. There is no absolute necessity to define view parameters for each module, since the default behaviors of actions will manage for you the choice of the template to be used. However, as soon as your application uses more than one layout, custom javascripts or stylesheets, or if the interface shows common components on every page, writing view.yml files for your modules will save you time and ease your work.
Note: If you want to create custom layouts, you can use the include_ functions to get the values of the head parameters and take advantage of the configuration files.
Meta configuration
The information written in the meta tags is not displayed but is useful for robots and search engines. It also controls the cache settings of every page.
To set these parameters for a modules, use these keys in a view.yml file:
http_metas:
$key: $value
metas:
$key: $value
To modify these settings from within an action, use these methods:
$this->getResponse()->addHttpMeta($key, $value)
$this->getResponse()->addMeta($key, $value)
Adding an existing key will replace its current content.
Let's image that you display an article about finance in France that will not change. You can write in the view configuration file:
http_metas:
cache-control:public
metas:
description: Finance in France
keywords: finance, France
Or, alternatively, call in the action:
$this->getResponse()->addHttpMeta('cache-control', 'public');
$this->getResponse()->addMeta('description','Finance in France');
$this->getResponse()->addMeta('keywords', 'finance, France');
When the template is included in the layout, the include_ helpers of the <head> part will give:
<meta http-equiv="cache-control" content="public">
<meta name="description" content="Finance in France" />
<meta name="keywords" content="finance, France" />
As a bonus, the HTTP header of the HTML file will also contain the http-metas setting. This means this if you need to modify the HTTP headers, the http-metas section of the view.yml is the solution, even if you don't have any <?php echo include_http_metas() ?> in the layout -- or if you have no layout. For instance, if you need to send a page as plain text, type:
http_metas:
content-type: text/plain
has_layout: false
Title configuration
Page title is a key part to search engine indexing; it is also very useful with modern browsers that provide tabbed-browsing.
To have a custom title for every page, take advantage of the <?php echo include_title() ?> call in the <head> part of the layout.
If your title only depends on the view, you should specify title in the view.yml:
indexSuccess:
metas:
title: Description
indexError:
metas:
title: Problem while displaying the description
listSuccess:
metas:
title: Result list
On the other hand, if an action can result in a page with various titles, you should use the setTitle($title) function:
$this->getResponse()->setTitle($title);
File inclusion configuration
Basic syntax
To include a specific stylesheet or a specific javascript file in the view configuration file, use:
stylesheets: [$css]
javascripts: [$js]
To do it from an action, use:
$this->getResponse()->addStylesheet($css);
$this->getResponse()->addJavascript($js);
In each case, the argument is a file name. If it has a logical extension (.css for a stylesheet and .js for a javascript), you can omit it. If it has a logical location (/css/ for a stylesheet and /js/ for a javascript), you can also omit it.
For instance, in an action called subscribe using a calendar widget, the view could be configured with:
subscribeSuccess:
stylesheets: [calendar/skins/aqua/theme]
javascripts: [calendar/calendar_stripped, calendar/calendar-en, calendar/calendar-setup_stripped]
Alternatively, you could require the files from the action with:
$this->getResponse()->addStylesheet('calendar/skins/aqua/theme');
$this->getResponse()->addJavascript('calendar/calendar_stripped');
$this->getResponse()->addJavascript('calendar/calendar-en');
$this->getResponse()->addJavascript('calendar/calendar-setup_stripped');
The <head> of the resulting view would then show:
<link rel="stylesheet" type="text/css" media="screen" href="/js/calendar/skins/aqua/theme.css" />
<script language="javascript" type="text/javascript" src="/js/calendar/calendar_stripped.js"></script>
<script language="javascript" type="text/javascript" src="/js/calendar/lang/calendar-en.js"></script>
<script language="javascript" type="text/javascript" src="/js/calendar/calendar-setup_stripped.js"></script>
Note: In previous versions of symfony, this type of inclusion was only possible if you included calls to the include_stylesheets() and include_javascripts() helpers in the <head> section of the layout. This is not necessary anymore, and the use of these helpers is deprecated.
Addition, removal, ordering
When you mention a stylesheet or a JavaScript in a view.yml, it appears in the response <head> in addition to the ones already defined and after them. The addition of these files follows the usual cascade definition, and the order of inclusion is from the most general to the most particular.
For instance, if your application view.yml stipulates:
default:
stylesheets: [main]
And if you have, in your module config/view.yml:
indexSuccess:
stylesheets: [special]
all:
stylesheets: [additional]
Then the <head> of the resulting indexSuccess view will show:
<link rel="stylesheet" type="text/css" media="screen" href="/css/main.css" />
<link rel="stylesheet" type="text/css" media="screen" href="/css/additional.css" />
<link rel="stylesheet" type="text/css" media="screen" href="/css/special.css" />
The same applies for the JavaScript inclusions. This allows you to override global settings at the module and view level.
To give you more control over this cascade, you can remove an already included stylesheet or JavaScript by prefixing its name with a minus sign ('-') in the view.yml
# adds a new stylesheet and removes the default one (as defined in the global view.yml)
indexSuccess:
stylesheets: [special, -main]
To remove all stylesheets or JavaScripts, use the following syntax:
# remove all stylesheets and JavaScripts
indexSuccess:
stylesheets: [-*]
javascripts: [-*]
You can be more accurate from within an action and define an additional parameter to force the position where to include the file (first or last position):
$this->getResponse()->addStylesheet('special', 'first');
Media specific stylesheet
To specify a media for a stylesheet inclusion, you can change the default stylesheet tag options:
stylesheets: [main, main_for_print: { media: print }]
or
$this->getResponse()->addStylesheet('main_for_print', '', array('media' => 'print'));
Layout configuration
According to the graphical charter of your website, you may have several layouts. Classical websites have at least two: the default layout, and the popup layout.
You already saw that the default layout is myproject/apps/myapp/templates/layout.php. You don't need to set it in the application-level view configuration. Additional layouts have to be added in the same directory.
If you need to use a different layout for a view, use:
layout: $layoutname
Or in the action:
$this->setLayout($layoutname);
For instance, if all the actions of the rules module use the content.php layout, except the securitypolicy action for which you need the popup.php layout, you can write:
securitypolicySuccess:
layout: popup
all:
layout: content
The same is possible in the Actions.class.php file:
class rulesActions extends sfActions
{
public function preExecute()
{
$this->setLayout('content');
}
public function executeSecuritypolicy()
{
$this->setLayout('popup');
...
}
}
Some views don't need any layout at all (for instance plain text pages). In that case, use:
has_layout: false
Or, in the action:
$this->setLayout(false);
Component slots configuration
Common interface components with dynamic content (breadcrumbs, navigation bars, etc.) that require the execution of a component (the "light" version of an action) are published in component slots in symfony. The definition in the view.yml looks like:
components:
$componentname: [$module, $action]
Imagine that you have a layout with a zone for contextual advices:
...
<div id="adviceBlock">
<?php include_component_slot('advices') ?>
</div>
...
You also have a module advice with contextual components forIndex and forList. Now, if you want to associate a contextual component with the views of a module article with actions index and list, you could write the following myproject/apps/myapp/modules/article/config/view.yml:
indexSuccess:
components:
advices: [advice, forIndex]
listSuccess:
components:
advices: [advice, forList]
How about template configuration?
Though you could expect to see a way to set a custom template with one of the two ways described here, there is none.
The reason is that when you need to set a custom template for an action, you should do either a redirect or a forward of this action to another one. The context will be much cleaner and the logic of your application will be preserved.
|
