Lines Matching refs:to
6 This section describes how to extends Twig for versions **older than
16 The first section of this chapter describes how to extend Twig easily. If
17 you want to reuse your changes in different projects or if you want to
24 Twig won't be able to recompile your templates when the PHP code is
30 different possible extension points and when to use them.
34 * ``{{ }}``: used to print the result of an expression evaluation;
36 * ``{% %}``: used to execute statements.
38 To understand why Twig exposes so many extension points, let's see how to
39 implement a *Lorem ipsum* generator (it needs to know the number of words to
59 In fact, you rarely need to create tags; and that's good news because tags are
68 Again, it works, but it looks weird. A filter transforms the passed value to
69 something else but here we use the value to indicate the number of words to
70 generate (so, ``40`` is an argument of the filter, not the value we want to
80 extension point to use. And you can use it anywhere an expression is accepted:
89 to generate lorem ipsum text:
98 Keep in mind the following when you want to extend Twig:
132 arguments passed to the filter (within parentheses ``()``) as extra arguments.
141 When compiling this template to PHP, Twig looks for the PHP callable
143 filter, and it is simply mapped to the PHP ``strtolower()`` function. After
144 compilation, the generated PHP code is roughly equivalent to:
150 As you can see, the ``'TWIG'`` string is passed as a first argument to the PHP
159 In this case, the extra arguments are passed to the function after the main
160 argument, and the compiled code is equivalent to:
166 Let's see how to create a new filter.
186 first argument passed to the ``Twig_Filter_Function`` constructor is the name
187 of the PHP function to call, here ``str_rot13``, a native PHP function.
189 Let's say I now want to be able to add a prefix before the converted string:
206 argument to the ``project_compute_rot13()`` function.
213 class. The ``Twig_Filter_Function`` class can also be used to register such
227 if you want access to the current environment instance in your filter, set the
228 ``needs_environment`` option to ``true``::
232 Twig will then pass the current environment as the first argument to the
248 or JavaScript code), you will want the raw output to be printed. In such a
253 Some filters may need to work on input that is already escaped or safe, for
254 example when adding (safe) HTML tags to originally unsafe output. In such a
255 case, set the ``pre_escape`` option to escape the input data before it is run
291 arguments. For instance, a call to ``'foo'|a_path_b()`` will result in the
304 When compiling this template to PHP, Twig looks for the PHP callable
306 function, and it is simply mapped to the PHP ``constant()`` function. After
307 compilation, the generated PHP code is roughly equivalent to:
313 Adding a function is similar to adding a filter. This can be done by calling the
358 arguments. For instance, a call to ``a_path_b('foo')`` will result in the
365 possibility to define new language constructs. This is also the most complex
366 feature as you need to understand how Twig's internals work.
386 Three steps are needed to define a new tag:
390 * Defining a Node class (responsible for converting the parsed code to PHP);
428 The ``getTag()`` method must return the tag we want to parse, here ``set``.
434 The parsing process is simplified thanks to a bunch of methods you can call
439 * ``next()``: Moves to the next token in the stream, *but returns the old one*.
447 the token is returned and the stream moves to the next token.
456 Reading the existing ``TokenParser`` classes is the best way to learn all
497 * ``addDebugInfo()``: Adds the line of the original template file related to
511 The main motivation for writing an extension is to move often used code into a
520 Most of the time, it is useful to create a single extension for your project,
521 to host all the specific tags and filters you want to add to Twig.
525 When packaging your code into an extension, Twig is smart enough to
526 recompile your templates whenever you make a change to it (when the
546 * Returns the token parser instances to add to the existing list.
553 * Returns the node visitor instances to add to the existing list.
560 * Returns a list of filters to add to the existing list.
567 * Returns a list of tests to add to the existing list.
574 * Returns a list of functions to add to the existing list.
581 * Returns a list of operators to add to the existing list.
588 * Returns a list of global variables to add to the existing list.
604 way, you just need to implement the ``getName()`` method as the
626 extensions must be registered explicitly to be available in your templates.
634 Of course, you need to first load the extension file by either using
680 To add a filter to an extension, you need to override the ``getFilters()``
681 method. This method must return an array of filters to add to the Twig
706 when defining a filter to use a method::
727 method to call.
729 Using methods for filters is a great way to package your filter without
738 want to override::
772 ``getTokenParsers()`` method. This method must return an array of tags to add
773 to the Twig environment::
787 responsible for parsing the tag and compiling it to PHP.
792 The ``getOperators()`` methods allows to add new operators. Here is how to add
816 The ``getTests()`` methods allows to add new test functions::