8000 Merge branch '2.0' · web-dev/symfony-docs@77cf9e0 · GitHub
[go: up one dir, main page]
Skip to content

Commit 77cf9e0

Browse files
weaverryanweaverryan
committed
Merge branch '2.0'
2 parents 964b3d2 + 14481fc commit 77cf9e0

File tree

9 files changed

+152
-15
lines changed

9 files changed

+152
-15
lines changed

‎book/doctrine.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1196,7 +1196,7 @@ in general, see Doctrine's `Lifecycle Events documentation`_
11961196
.. sidebar:: Lifecycle Callbacks and Event Listeners
11971197

11981198
Notice that the ``setCreatedValue()`` method receives no arguments. This
1199-
is always the case for lifecylce callbacks and is intentional: lifecycle
1199+
is always the case for lifecycle callbacks and is intentional: lifecycle
12001200
callbacks should be simple methods that are concerned with internally
12011201
transforming data in the entity (e.g. setting a created/updated field,
12021202
generating a slug value).

‎book/forms.rst

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -565,13 +565,10 @@ the correct values of a number of field options.
565565
(i.e. is the field ``nullable``). This is very useful, as your client-side
566566
validation will automatically match your validation rules.
567567

568-
* ``min_length``: If the field is some sort of text field, then the ``min_length``
569-
option can be guessed from the validation constrains (if ``MinLength``
570-
or ``Min`` is used) or from the Doctrine metadata (via the field's length).
571-
572-
* ``max_length``: Similar to ``min_length``, the maximum length can also
573-
be guessed.
574-
568+
* ``max_length``: If the field is some sort of text field, then the ``max_length``
569+
option can be guessed from the validation constraints (if ``MaxLength`` or ``Max``
570+
is used) or from the Doctrine metadata (via the field's length).
571+
575572
.. note::
576573

577574
These field options are *only* guessed if you're using Symfony to guess
@@ -580,7 +577,7 @@ the correct values of a number of field options.
580577
If you'd like to change one of the guessed values, you can override it by
581578
passing the option in the options field array::
582579

583-
->add('task', null, array('min_length' => 4))
580+
->add('task', null, array('max_length' => 4))
584581

585582
.. index::
586583
single: Forms; Rendering in a Template

‎book/service_container.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,15 @@ The end result is exactly the same as before - the difference is only in
222222
to look for parameters with those names. When the container is built, it
223223
looks up the value of each parameter and uses it in the service definition.
224224

225+
.. note::
226+
227+
The percent sign inside a parameter or argument, as part of the string, must
228+
be escaped with another percent sign:
229+
230+
.. code-block:: xml
231+
232+
<argument type="string">http://symfony.com/?foo=%%s&bar=%%d</argument>
233+
225234
The purpose of parameters is to feed information into services. Of course
226235
there was nothing wrong with defining the service without using any parameters.
227236
Parameters, however, have several advantages:

‎book/templating.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1388,6 +1388,7 @@ Learn more from the Cookbook
13881388

13891389
* :doc:`/cookbook/templating/PHP`
13901390
* :doc:`/cookbook/controller/error_pages`
1391+
* :doc:`/cookbook/templating/twig_extension`
13911392

13921393
.. _`Twig`: http://twi 6D4E g.sensiolabs.org
13931394
.. _`KnpBundles.com`: http://knpbundles.com

‎cookbook/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ Cookbook
7272

7373
templating/global_variables
7474
templating/PHP
75+
templating/twig_extension
7576

7677
logging/monolog
7778
logging/monolog_email

‎cookbook/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@
9393

9494
* :doc:`/cookbook/templating/global_variables`
9595
* :doc:`/cookbook/templating/PHP`
96+
* :doc:`/cookbook/templating/twig_extension`
9697

9798
* **Logging**
9899

‎cookbook/templating/twig_extension.rst

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
.. index::
2+
single: Twig extensions
3+
4+
How to write a custom Twig Extension
5+
====================================
6+
7+
The main motivation for writing an extension is to move often used code
8+
into a reusable class like adding support for internationalization.
9+
An extension can define tags, filters, tests, operators, global variables,
10+
functions, and node visitors.
11+
12+
Creating an extension also makes for a better separation of code that is
13+
executed at compilation time and code needed at runtime. As such, it makes
14+
your code faster.
15+
16+
.. tip::
17+
18+
Before writing your own extensions, have a look at the `Twig official extension repository`_.
19+
20+
Create the Extension Class
21+
--------------------------
22+
23+
To get your custom functionality you must first create a Twig Extension class.
24+
As an example we will create a price filter to format a given number into price::
25+
26+
// src/Acme/DemoBundle/Twig/AcmeExtension.php
27+
28+
namespace Acme\DemoBundle\Twig;
29+
30+
use Twig_Extension;
31+
use Twig_Filter_Method;
32+
use Twig_Function_Method;
33+
34+
class AcmeExtension extends Twig_Extension
35+
{
36+
public function getFilters()
37+
{
38+
return array(
39+
'price' => new Twig_Filter_Method($this, 'priceFilter'),
40+
);
41+
}
42+
43+
public function priceFilter($number, $decimals = 0, $decPoint = '.', $thousandsSep = ',')
44+
{
45+
$price = number_format($number, $decimals, $decPoint, $thousandsSep);
46+
$price = '$' . $price;
47+
48+
return $price;
49+
}
50+
51+
public function getName()
52+
{
53+
return 'acme_extension';
54+
}
55+
}
56+
57+
.. tip::
58+
59+
Along with custom filters, you can also add custom `functions` and register `global variables`.
60+
61+
Register an Extension as a Service
62+
----------------------------------
63+
64+
Now you must let Service Container know about your newly created Twig Extension:
65+
66+
.. configuration-block::
67+
68+
.. code-block:: xml
69+
70+
<!-- src/Acme/DemoBundle/Resources/config/services.xml -->
71+
<services>
72+
<service id="acme.twig.acme_extension" class="Acme\DemoBundle\Twig\AcmeExtension">
73+
<tag name="twig.extension" />
74+
</service>
75+
</services>
76+
77+
.. code-block:: yaml
78+
79+
# src/Acme/DemoBundle/Resources/config/services.yml
80+
services:
81+
acme.twig.acme_extension:
82+
class: Acme\DemoBundle\Twig\AcmeExtension
83+
tags:
84+
- { name: twig.extension }
85+
86+
.. code-block:: php
87+
88+
// src/Acme/DemoBundle/Resources/config/services.php
89+
use Symfony\Component\DependencyInjection\Definition;
90+
91+
$acmeDefinition = new Definition('\Acme\DemoBundle\Twig\AcmeExtension');
92+
$acmeDefinition->addTag('twig.extension');
93+
$container->setDefinition('acme.twig.acme_extension', $acmeDefinition);
94+
95+
.. note::
96+
97+
Keep in mind that Twig Extensions are not lazily loaded. This means that
98+
there's a higher chance that you'll get a **CircularReferenceException**
99+
or a **ScopeWideningInjectionException** if any services
100+
(or your Twig Extension in this case) are dependent on the request service.
101+
For more information take a look at :doc:`/cookbook/service_container/scopes`.
102+
103+
Using the custom Extension
104+
--------------------------
105+
106+
Using your newly created Twig Extension is no different than any other:
107+
108+
.. code-block:: jinja
109+
110+
{# outputs $5,500.00 #}
111+
{{ '5500' | price }}
112+
113+
Passing other arguments to your filter:
114+
115+
.. code-block:: jinja
116+
117+
{# outputs $5500,2516 #}
118+
{{ '5500.25155' | price(4, ',', '') }}
119+
120+
Learning further
121+
----------------
122+
123+
For a more in-depth look into Twig Extensions, please take a look at the `Twig extensions documentation`_.
124+
125+
.. _`Twig official extension repository`: http://github.com/fabpot/Twig-extensions
126+
.. _`Twig extensions documentation`: http://twig.sensiolabs.org/doc/extensions.html
127+
.. _`global variables`: http://twig.sensiolabs.org/doc/extensions.html#globals
128+
.. _`functions`: http://twig.sensiolabs.org/doc/extensions.html#functions

‎reference/configuration/framework.rst

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -115,12 +115,12 @@ templating
115115
assets_base_urls
116116
................
117117

118-
**default**: ``{ http: [], https: [] }``
118+
**default**: ``{ http: [], ssl: [] }``
119119

120120
This option allows you to define base URL's to be used for assets referenced
121-
from ``http`` and ``https`` pages. A string value may be provided in lieu of a
122-
single-element array. If multiple base URL's are provided, Symfony2 will select
123-
one from the collection each time it generates an asset's path.
121+
from ``http`` and ``ssl`` (``https``) pages. A string value may be provided in
122+
lieu of a single-element array. If multiple base URL's are provided, Symfony2
123+
will select one from the collection each time it generates an asset's path.
124124

125125
For your convenience, ``assets_base_urls`` can be set directly with a string or
126126
array of strings, which will be automatically organized into collections of base

‎reference/forms/types/collection.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -204,7 +204,7 @@ type
204204

205205
This is the field type for each item in this collection (e.g. ``text``, ``choice``,
206206
etc). For example, if you have an array of email addresses, you'd use the
207-
:doc`email</reference/forms/types/email>` type. If you want to embed
207+
:doc:`email</reference/forms/types/email>` type. If you want to embed
208208
a collection of some other form, create a new instance of your form type
209209
and pass it as this option.
210210

@@ -214,7 +214,7 @@ options
214214
**type**: ``array`` **default**: ``array()``
215215

216216
This is the array that's passed to the form type specified in the `type`_
217-
option. For example, if you used the :doc`choice</reference/forms/types/choice>`
217+
option. For example, if you used the :doc:`choice</reference/forms/types/choice>`
218218
type as your `type`_ option (e.g. for a collection of drop-down menus), then
219219
you'd need to at least pass the ``choices`` option to the underlying type::
220220

0 commit comments

Comments
 (0)
0