vendor/symfony/form/Symfony/Component/Form/FormRendererEngineInterface.php

   1 <?php
   2
   3 /*
   4  * This file is part of the Symfony package.
   5  *
   6  * (c) Fabien Potencier <fabien@symfony.com>
   7  *
   8  * For the full copyright and license information, please view the LICENSE
   9  * file that was distributed with this source code.
  10  */
  11
  12 namespace Symfony\Component\Form;
  13
  14 /**
  15  * Adapter for rendering form templates with a specific templating engine.
  16  *
  17  * @author Bernhard Schussek <bschussek@gmail.com>
  18  */
  19 interface FormRendererEngineInterface
  20 {
  21     /**
  22      * Sets the theme(s) to be used for rendering a view and its children.
  23      *
  24      * @param FormView $view   The view to assign the theme(s) to.
  25      * @param mixed    $themes The theme(s). The type of these themes
  26      *                         is open to the implementation.
  27      */
  28     public function setTheme(FormView $view, $themes);
  29
  30     /**
  31      * Returns the resource for a block name.
  32      *
  33      * The resource is first searched in the themes attached to $view, then
  34      * in the themes of its parent view and so on, until a resource was found.
  35      *
  36      * The type of the resource is decided by the implementation. The resource
  37      * is later passed to {@link renderBlock()} by the rendering algorithm.
  38      *
  39      * @param FormView $view      The view for determining the used themes.
  40      *                            First the themes attached directly to the
  41      *                            view with {@link setTheme()} are considered,
  42      *                            then the ones of its parent etc.
  43      * @param string   $blockName The name of the block to render.
  44      *
  45      * @return mixed The renderer resource or false, if none was found.
  46      */
  47     public function getResourceForBlockName(FormView $view, $blockName);
  48
  49     /**
  50      * Returns the resource for a block hierarchy.
  51      *
  52      * A block hierarchy is an array which starts with the root of the hierarchy
  53      * and continues with the child of that root, the child of that child etc.
  54      * The following is an example for a block hierarchy:
  55      *
  56      * <code>
  57      * form_widget
  58      * text_widget
  59      * url_widget
  60      * </code>
  61      *
  62      * In this example, "url_widget" is the most specific block, while the other
  63      * blocks are its ancestors in the hierarchy.
  64      *
  65      * The second parameter $hierarchyLevel determines the level of the hierarchy
  66      * that should be rendered. For example, if $hierarchyLevel is 2 for the
  67      * above hierarchy, the engine will first look for the block "url_widget",
  68      * then, if that does not exist, for the block "text_widget" etc.
  69      *
  70      * The type of the resource is decided by the implementation. The resource
  71      * is later passed to {@link renderBlock()} by the rendering algorithm.
  72      *
  73      * @param FormView          $view               The view for determining the
  74      *                                              used themes. First the themes
  75      *                                              attached directly to the view
  76      *                                              with {@link setTheme()} are
  77      *                                              considered, then the ones of
  78      *                                              its parent etc.
  79      * @param array             $blockNameHierarchy The block name hierarchy, with
  80      *                                              the root block at the beginning.
  81      * @param integer           $hierarchyLevel     The level in the hierarchy at
  82      *                                              which to start looking. Level 0
  83      *                                              indicates the root block, i.e.
  84      *                                              the first element of
  85      *                                              $blockNameHierarchy.
  86      *
  87      * @return mixed The renderer resource or false, if none was found.
  88      */
  89     public function getResourceForBlockNameHierarchy(FormView $view, array $blockNameHierarchy, $hierarchyLevel);
  90
  91     /**
  92      * Returns the hierarchy level at which a resource can be found.
  93      *
  94      * A block hierarchy is an array which starts with the root of the hierarchy
  95      * and continues with the child of that root, the child of that child etc.
  96      * The following is an example for a block hierarchy:
  97      *
  98      * <code>
  99      * form_widget
 100      * text_widget
 101      * url_widget
 102      * </code>
 103      *
 104      * The second parameter $hierarchyLevel determines the level of the hierarchy
 105      * that should be rendered.
 106      *
 107      * If we call this method with the hierarchy level 2, the engine will first
 108      * look for a resource for block "url_widget". If such a resource exists,
 109      * the method returns 2. Otherwise it tries to find a resource for block
 110      * "text_widget" (at level 1) and, again, returns 1 if a resource was found.
 111      * The method continues to look for resources until the root level was
 112      * reached and nothing was found. In this case false is returned.
 113      *
 114      * The type of the resource is decided by the implementation. The resource
 115      * is later passed to {@link renderBlock()} by the rendering algorithm.
 116      *
 117      * @param FormView          $view               The view for determining the
 118      *                                              used themes. First the themes
 119      *                                              attached directly to the view
 120      *                                              with {@link setTheme()} are
 121      *                                              considered, then the ones of
 122      *                                              its parent etc.
 123      * @param array             $blockNameHierarchy The block name hierarchy, with
 124      *                                              the root block at the beginning.
 125      * @param integer           $hierarchyLevel     The level in the hierarchy at
 126      *                                              which to start looking. Level 0
 127      *                                              indicates the root block, i.e.
 128      *                                              the first element of
 129      *                                              $blockNameHierarchy.
 130      *
 131      * @return integer|Boolean The hierarchy level or false, if no resource was found.
 132      */
 133     public function getResourceHierarchyLevel(FormView $view, array $blockNameHierarchy, $hierarchyLevel);
 134
 135     /**
 136      * Renders a block in the given renderer resource.
 137      *
 138      * The resource can be obtained by calling {@link getResourceForBlock()}
 139      * or {@link getResourceForBlockHierarchy()}. The type of the resource is
 140      * decided by the implementation.
 141      *
 142      * @param FormView          $view      The view to render.
 143      * @param mixed             $resource  The renderer resource.
 144      * @param string            $blockName The name of the block to render.
 145      * @param array             $variables The variables to pass to the template.
 146      *
 147      * @return string The HTML markup.
 148      */
 149     public function renderBlock(FormView $view, $resource, $blockName, array $variables = array());
 150 }