|
3
|
1 |
Overriding Default FOSUserBundle Templates |
|
|
2 |
========================================== |
|
|
3 |
|
|
|
4 |
As you start to incorporate FOSUserBundle into your application, you will probably |
|
|
5 |
find that you need to override the default templates that are provided by |
|
|
6 |
the bundle. Although the template names are not configurable, the Symfony2 |
|
|
7 |
framework provides two ways to override the templates of a bundle. |
|
|
8 |
|
|
|
9 |
1. Define a new template of the same name in the `app/Resources` directory |
|
|
10 |
2. Create a new bundle that is defined as a child of `FOSUserBundle` |
|
|
11 |
|
|
|
12 |
### Example: Overriding The Default layout.html.twig |
|
|
13 |
|
|
|
14 |
It is highly recommended that you override the `Resources/views/layout.html.twig` |
|
|
15 |
template so that the pages provided by the FOSUserBundle have a similar look and |
|
|
16 |
feel to the rest of your application. An example of overriding this layout template |
|
|
17 |
is demonstrated below using both of the overriding options listed above. |
|
|
18 |
|
|
|
19 |
Here is the default `layout.html.twig` provided by the FOSUserBundle: |
|
|
20 |
|
|
|
21 |
``` twig |
|
|
22 |
<!DOCTYPE html> |
|
|
23 |
<html> |
|
|
24 |
<head> |
|
|
25 |
<meta charset="UTF-8" /> |
|
|
26 |
</head> |
|
|
27 |
<body> |
|
|
28 |
<div> |
|
|
29 |
{% if is_granted("IS_AUTHENTICATED_REMEMBERED") %} |
|
|
30 |
{{ 'layout.logged_in_as'|trans({'%username%': app.user.username}, 'FOSUserBundle') }} | |
|
|
31 |
<a href="{{ path('fos_user_security_logout') }}"> |
|
|
32 |
{{ 'layout.logout'|trans({}, 'FOSUserBundle') }} |
|
|
33 |
</a> |
|
|
34 |
{% else %} |
|
|
35 |
<a href="{{ path('fos_user_security_login') }}">{{ 'layout.login'|trans({}, 'FOSUserBundle') }}</a> |
|
|
36 |
{% endif %} |
|
|
37 |
</div> |
|
|
38 |
|
|
|
39 |
{% for key, message in app.session.getFlashes() %} |
|
|
40 |
<div class="{{ key }}"> |
|
|
41 |
{{ message|trans({}, 'FOSUserBundle') }} |
|
|
42 |
</div> |
|
|
43 |
{% endfor %} |
|
|
44 |
|
|
|
45 |
<div> |
|
|
46 |
{% block fos_user_content %} |
|
|
47 |
{% endblock fos_user_content %} |
|
|
48 |
</div> |
|
|
49 |
</body> |
|
|
50 |
</html> |
|
|
51 |
``` |
|
|
52 |
|
|
|
53 |
As you can see its pretty basic and doesn't really have much structure, so you will |
|
|
54 |
want to replace it with a layout file that is appropriate for your application. The |
|
|
55 |
main thing to note in this template is the block named `fos_user_content`. This is |
|
|
56 |
the block where the content from each of the different bundle's actions will be |
|
|
57 |
displayed, so you must make sure to include this block in the layout file you will |
|
|
58 |
use to override the default one. |
|
|
59 |
|
|
|
60 |
The following Twig template file is an example of a layout file that might be used |
|
|
61 |
to override the one provided by the bundle. |
|
|
62 |
|
|
|
63 |
``` twig |
|
|
64 |
{% extends 'AcmeDemoBundle::layout.html.twig' %} |
|
|
65 |
|
|
|
66 |
{% block title %}Acme Demo Application{% endblock %} |
|
|
67 |
|
|
|
68 |
{% block content %} |
|
|
69 |
{% block fos_user_content %}{% endblock %} |
|
|
70 |
{% endblock %} |
|
|
71 |
``` |
|
|
72 |
|
|
|
73 |
This example extends the layout template from a fictional application bundle named |
|
|
74 |
`AcmeDemoBundle`. The `content` block is where the main content of each page is rendered. |
|
|
75 |
This is why the `fos_user_content` block has been placed inside of it. This will |
|
|
76 |
lead to the desired effect of having the output from the FOSUserBundle actions |
|
|
77 |
integrated into our applications layout, preserving the look and feel of the |
|
|
78 |
application. |
|
|
79 |
|
|
|
80 |
**a) Define New Template In app/Resources** |
|
|
81 |
|
|
|
82 |
The easiest way to override a bundle's template is to simply place a new one in |
|
|
83 |
your `app/Resources` folder. To override the layout template located at |
|
|
84 |
`Resources/views/layout.html.twig` in the `FOSUserBundle` directory, you would place |
|
|
85 |
you new layout template at `app/Resources/FOSUserBundle/views/layout.html.twig`. |
|
|
86 |
|
|
|
87 |
As you can see the the pattern for overriding templates in this way is to |
|
|
88 |
create a folder with the name of the bundle class in the `app/Resources` directory. |
|
|
89 |
Then add your new template to this folder, preserving the directory structure from the |
|
|
90 |
original bundle. |
|
|
91 |
|
|
|
92 |
**b) Create A Child Bundle And Override Template** |
|
|
93 |
|
|
|
94 |
**Note:** |
|
|
95 |
|
|
|
96 |
``` |
|
|
97 |
This method is more complicated than the one outlined above. Unless you are |
|
|
98 |
planning to override the controllers as well as the templates, it is recommended |
|
|
99 |
that you use the other method. |
|
|
100 |
``` |
|
|
101 |
|
|
|
102 |
As listed above, you can also create a bundle defined as child of FOSUserBundle |
|
|
103 |
and place the new template in the same location that is resides in the FOSUserBundle. |
|
|
104 |
The first thing you want to do is override the `getParent` method to your bundle |
|
|
105 |
class. |
|
|
106 |
|
|
|
107 |
``` php |
|
|
108 |
// src/Acme/UserBundle/AcmeUserBundle.php |
|
|
109 |
<?php |
|
|
110 |
|
|
|
111 |
namespace Acme\UserBundle; |
|
|
112 |
|
|
|
113 |
use Symfony\Component\HttpKernel\Bundle\Bundle; |
|
|
114 |
|
|
|
115 |
class AcmeUserBundle extends Bundle |
|
|
116 |
{ |
|
|
117 |
public function getParent() |
|
|
118 |
{ |
|
|
119 |
return 'FOSUserBundle'; |
|
|
120 |
} |
|
|
121 |
} |
|
|
122 |
``` |
|
|
123 |
|
|
|
124 |
By returning the name of the bundle in the `getParent` method of your bundle class, |
|
|
125 |
you are telling the Symfony2 framework that your bundle is a child of the FOSUserBundle. |
|
|
126 |
|
|
|
127 |
Now that you have declared your bundle as a child of the FOSUserBundle, you can override |
|
|
128 |
the parent bundle's templates. To override the layout template, simply create a new file |
|
|
129 |
in the `src/Acme/UserBundle/Resources/views` directory named `layout.html.twig`. Notice |
|
|
130 |
how this file resides in the same exact path relative to the bundle directory as it |
|
|
131 |
does in the FOSUserBundle. |
|
|
132 |
|
|
|
133 |
After overriding a template in your child bundle, you must clear the cache for the override |
|
|
134 |
to take effect, even in a development environment. |
|
|
135 |
|
|
|
136 |
Overriding all of the other templates provided by the FOSUserBundle can be done |
|
|
137 |
in a similar fashion using either of the two methods shown in this document. |
|
|
138 |
|
|
|
139 |
### Configuring A Templating Engine Other Than Twig |
|
|
140 |
|
|
|
141 |
You can configure a templating engine other than Twig using the bundle's configuration. |
|
|
142 |
Below is an example configuration for using the PHP templating engine. |
|
|
143 |
|
|
|
144 |
``` yaml |
|
|
145 |
fos_user: |
|
|
146 |
# ... |
|
|
147 |
template: |
|
|
148 |
engine: php |
|
|
149 |
``` |
|
|
150 |
|
|
|
151 |
The FOSUserBundle only provides default templates for the Twig templating engine, |
|
|
152 |
so you will have to create all of the templates that you are using. The names and |
|
|
153 |
locations will be the same except that the file extension will be `.php` instead of |
|
|
154 |
`.twig` |