[TASK] Sync CMS Fluid with Flow Fluid 1.1 (part1)
[Packages/TYPO3.CMS.git] / typo3 / sysext / fluid / Classes / Core / ViewHelper / Facets / CompilableInterface.php
1 <?php
2 namespace TYPO3\CMS\Fluid\Core\ViewHelper\Facets;
3
4 /* *
5 * This script is backported from the TYPO3 Flow package "TYPO3.Fluid". *
6 * *
7 * It is free software; you can redistribute it and/or modify it under *
8 * the terms of the GNU Lesser General Public License, either version 3 *
9 * of the License, or (at your option) any later version. *
10 * *
11 * The TYPO3 project - inspiring people to share! *
12 * */
13
14 /**
15 * If a ViewHelper implements CompilableInterface, it can directly influence the way
16 * the syntax tree is compiled to a static PHP file.
17 *
18 * For now, this class is NO API.
19 *
20 * There a two ways of using the Compilable Interface.
21 *
22 * Implementing renderStatic()
23 * ===========================
24 * A ViewHelper which implements CompilableInterface and the renderStatic method
25 * is called *statically* through the renderStatic method; and no instance of the
26 * ViewHelper is created.
27 *
28 * This is a case which you can implement if you do not access any *internal state*
29 * in the ViewHelper. This means the following should be true:
30 *
31 * - you do not access $this->arguments, but only the function arguments of render()
32 * - you do not call $this->renderChildren()
33 *
34 * If you have performance problems because the calling overhead of a ViewHelper
35 * is too big, you should implement renderStatic().
36 *
37 * Implementing compile()
38 * ======================
39 *
40 * Some ViewHelpers want to directly manipulate the PHP code which is created in
41 * the compilation run. This is, however, only necessary in very special cases,
42 * like in the AbstractConditionViewHelper or when a ViewHelper is potentially
43 * called thousands of times.
44 *
45 * A ViewHelper which wants to directly influence the resulting PHP code must implement
46 * the CompilableInterface, and only implement the compile() method.
47 */
48 interface CompilableInterface {
49
50 /**
51 * Here follows a more detailed description of the arguments of this function:
52 *
53 * $arguments contains a plain array of all arguments this ViewHelper has received,
54 * including the default argument values if an argument has not been specified
55 * in the ViewHelper invocation.
56 *
57 * $renderChildrenClosure is a closure you can execute instead of $this->renderChildren().
58 * It returns the rendered child nodes, so you can simply do $renderChildrenClosure() to execute
59 * it. It does not take any parameters.
60 *
61 * $renderingContext contains references to the TemplateVariableContainer, the
62 * ViewHelperVariableContainer and the ControllerContext.
63 *
64 * @param array $arguments
65 * @param \Closure $renderChildrenClosure
66 * @param \TYPO3\CMS\Fluid\Core\Rendering\RenderingContextInterface $renderingContext
67 * @return string the resulting string which is directly shown
68 */
69 static public function renderStatic(array $arguments, \Closure $renderChildrenClosure, \TYPO3\CMS\Fluid\Core\Rendering\RenderingContextInterface $renderingContext);
70
71 /**
72 * This method is called on compilation time.
73 *
74 * It has to return a *single* PHP statement without semi-colon or newline
75 * at the end, which will be embedded at various places.
76 *
77 * Furthermore, it can append PHP code to the variable $initializationPhpCode.
78 * In this case, all statements have to end with semi-colon and newline.
79 *
80 * Outputting new variables
81 * ========================
82 * If you want create a new PHP variable, you need to use
83 * $templateCompiler->variableName('nameOfVariable') for this, as all variables
84 * need to be globally unique.
85 *
86 * Return Value
87 * ============
88 * Besides returning a single string, it can also return the constant
89 * \TYPO3\CMS\Fluid\Core\Compiler\TemplateCompiler::SHOULD_GENERATE_VIEWHELPER_INVOCATION
90 * which means that after the $initializationPhpCode, the ViewHelper invocation
91 * is built as normal. This is especially needed if you want to build new arguments
92 * at run-time, as it is done for the AbstractConditionViewHelper.
93 *
94 * @param string $argumentsVariableName Name of the variable in which the ViewHelper arguments are stored
95 * @param string $renderChildrenClosureVariableName Name of the closure which can be executed to render the child nodes
96 * @param string $initializationPhpCode
97 * @param \TYPO3\CMS\Fluid\Core\Parser\SyntaxTree\AbstractNode $syntaxTreeNode
98 * @param \TYPO3\CMS\Fluid\Core\Compiler\TemplateCompiler $templateCompiler
99 * @return string
100 */
101 public function compile($argumentsVariableName, $renderChildrenClosureVariableName, &$initializationPhpCode, \TYPO3\CMS\Fluid\Core\Parser\SyntaxTree\AbstractNode $syntaxTreeNode, \TYPO3\CMS\Fluid\Core\Compiler\TemplateCompiler $templateCompiler);
102 }
103
104 ?>