|
| 1 | +############# |
| 2 | +View Renderer |
| 3 | +############# |
| 4 | + |
| 5 | +The ``view()`` function is a convenience method that grabs an instance of the ``renderer`` service, |
| 6 | +sets the data, and renders the view. While this is often exactly what you want, you may find times where you |
| 7 | +want to work with it more directly. In that case you can access the View service directly:: |
| 8 | + |
| 9 | + $renderer = \Config\Services::renderer(); |
| 10 | + |
| 11 | +.. important:: You should create services only within controllers. If you need access to the View class |
| 12 | + from a library, you should set that as a dependency in the constructor. |
| 13 | + |
| 14 | +Then you can use any of the three standard methods that it provides: |
| 15 | +**render(viewpath, options, save)**, **setVar(name, value, context)** and **setData(data, context)**. |
| 16 | + |
| 17 | +Method Chaining |
| 18 | +=============== |
| 19 | + |
| 20 | +The `setVar()` and `setData()` methods are chainable, allowing you to combine a number of different calls together in a chain:: |
| 21 | + |
| 22 | + service('renderer')->setVar('one', $one) |
| 23 | + ->setVar('two', $two) |
| 24 | + ->render('myView'); |
| 25 | + |
| 26 | +Escaping Data |
| 27 | +============= |
| 28 | + |
| 29 | +When you pass data to the ``setVar()`` and ``setData()`` functions you have the option to escape the data to protect |
| 30 | +against cross-site scripting attacks. As the last parameter in either method, you can pass the desired context to |
| 31 | +escape the data for. See below for context descriptions. |
| 32 | + |
| 33 | +If you don't want the data to be escaped, you can pass `null` or `raw` as the final parameter to each function:: |
| 34 | + |
| 35 | + $renderer->setVar('one', $one, 'raw'); |
| 36 | + |
| 37 | +If you choose not to escape data, or you are passing in an object instance, you can manually escape the data within |
| 38 | +the view with the ``esc()`` function. The first parameter is the string to escape. The second parameter is the |
| 39 | +context to escape the data for (see below):: |
| 40 | + |
| 41 | + <?= esc($object->getStat()) ?> |
| 42 | + |
| 43 | +Escaping Contexts |
| 44 | +----------------- |
| 45 | + |
| 46 | +By default, the ``esc()`` and, in turn, the ``setVar()`` and ``setData()`` functions assume that the data you want to |
| 47 | +escape is intended to be used within standard HTML. However, if the data is intended for use in Javascript, CSS, |
| 48 | +or in an href attribute, you would need different escaping rules to be effective. You can pass in the name of the |
| 49 | +context as the second parameter. Valid contexts are 'html', 'js', 'css', 'url', and 'attr':: |
| 50 | + |
| 51 | + <a href="<?= esc($url, 'url') ?>" data-foo="<?= esc($bar, 'attr') ?>">Some Link</a> |
| 52 | + |
| 53 | + <script> |
| 54 | + var siteName = '<?= esc($siteName, 'js') ?>'; |
| 55 | + </script> |
| 56 | + |
| 57 | + <style> |
| 58 | + body { |
| 59 | + background-color: <?= esc('bgColor', 'css') ?> |
| 60 | + } |
| 61 | + </style> |
| 62 | + |
| 63 | +*************** |
| 64 | +Class Reference |
| 65 | +*************** |
| 66 | + |
| 67 | +.. php:interface:: CodeIgniter\\View\\RendererableInterface |
| 68 | +
|
| 69 | + .. php:method:: render($view[, $options[, $saveData=false]]]) |
| 70 | +
|
| 71 | + :param string $view: File name of the view source |
| 72 | + :param array $options: Array of options, as key/value pairs |
| 73 | + :param boolean $saveData: If true, will save data for use with any other calls, if false, will clean the data after rendering the view. |
| 74 | + :returns: The rendered text for the chosen view |
| 75 | + :rtype: string |
| 76 | + |
| 77 | + Builds the output based upon a file name and any data that has already been set:: |
| 78 | + |
| 79 | + echo $renderer->render('myview'); |
| 80 | + |
| 81 | + Options supported: |
| 82 | + |
| 83 | + - ``cache`` - the time in seconds, to save a view's results |
| 84 | + - ``cache_name`` - the ID used to save/retrieve a cached view result; defaults to the viewpath |
| 85 | + - ``saveData`` - true if the view data parameter should be retained for subsequent calls |
| 86 | + |
| 87 | + |
| 88 | + .. php:method:: setData([$data[, $context=null]]) |
| 89 | +
|
| 90 | + :param array $data: Array of view data strings, as key/value pairs |
| 91 | + :param string $context: The context to use for data escaping. |
| 92 | + :returns: The Renderer, for method chaining |
| 93 | + :rtype: CodeIgniter\\View\\RenderableInterface. |
| 94 | + |
| 95 | + Sets several pieces of view data at once:: |
| 96 | + |
| 97 | + $renderer->setData(['name'=>'George', 'position'=>'Boss']); |
| 98 | + |
| 99 | + Supported escape contexts: html, css, js, url, or attr or raw. |
| 100 | + If 'raw', no escaping will happen. |
| 101 | + |
| 102 | + .. php:method:: setVar($name[, $value=null[, $context=null]]) |
| 103 | +
|
| 104 | + :param string $name: Name of the view data variable |
| 105 | + :param mixed $value: The value of this view data |
| 106 | + :param string $context: The context to use for data escaping. |
| 107 | + :returns: The Renderer, for method chaining |
| 108 | + :rtype: CodeIgniter\\View\\RenderableInterface. |
| 109 | + |
| 110 | + Sets a single piece of view data:: |
| 111 | + |
| 112 | + $renderer->setVar('name','Joe','html'); |
| 113 | + |
| 114 | + Supported escape contexts: html, css, js, url, attr or raw. |
| 115 | + If 'raw', no escaping will happen. |
| 116 | + |
0 commit comments