Skip to content

Commit 7a36628

Browse files
authored
Merge pull request #7359 from kenjis/improve-view_renderer.rst
docs: Improve view_renderer.rst
2 parents d97b04b + a55690a commit 7a36628

File tree

1 file changed

+30
-8
lines changed

1 file changed

+30
-8
lines changed

user_guide_src/source/outgoing/view_renderer.rst

Lines changed: 30 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,27 +6,32 @@ View Renderer
66
:local:
77
:depth: 2
88

9+
***********************
910
Using the View Renderer
1011
***********************
1112

12-
The ``view()`` function is a convenience function that grabs an instance of the
13+
The :php:func:`view()` function is a convenience function that grabs an instance of the
1314
``renderer`` service, sets the data, and renders the view. While this is often
1415
exactly what you want, you may find times where you want to work with it more directly.
1516
In that case you can access the View service directly:
1617

1718
.. literalinclude:: view_renderer/001.php
19+
:lines: 2-
1820

1921
Alternately, if you are not using the ``View`` class as your default renderer, you
2022
can instantiate it directly:
2123

2224
.. literalinclude:: view_renderer/002.php
25+
:lines: 2-
2326

2427
.. important:: You should create services only within controllers. If you need
2528
access to the View class from a library, you should set that as a dependency
2629
in your library's constructor.
2730

2831
Then you can use any of the three standard methods that it provides:
29-
**render(viewpath, options, save)**, **setVar(name, value, context)** and **setData(data, context)**.
32+
:php:meth:`render() <CodeIgniter\\View\\View::render()>`,
33+
:php:meth:`setVar() <CodeIgniter\\View\\View::setVar()>` and
34+
:php:meth:`setData() <CodeIgniter\\View\\View::setData()>`.
3035

3136
What It Does
3237
============
@@ -45,13 +50,28 @@ script. You will have to give each escaped value a unique parameter name.
4550
No special meaning is attached to parameters whose value is an array. It is up
4651
to you to process the array appropriately in your PHP code.
4752

53+
Setting View Parameters
54+
=======================
55+
56+
The :php:meth:`setVar() <CodeIgniter\\View\\View::setVar()>` method sets a view parameter.
57+
58+
.. literalinclude:: view_renderer/008.php
59+
:lines: 2-
60+
61+
The :php:meth:`setData() <CodeIgniter\\View\\View::setData()>` method sets multiple view
62+
parameters at once.
63+
64+
.. literalinclude:: view_renderer/007.php
65+
:lines: 2-
66+
4867
Method Chaining
4968
===============
5069

5170
The ``setVar()`` and ``setData()`` methods are chainable, allowing you to combine a
5271
number of different calls together in a chain:
5372

5473
.. literalinclude:: view_renderer/003.php
74+
:lines: 2-
5575

5676
Escaping Data
5777
=============
@@ -63,9 +83,10 @@ escape the data for. See below for context descriptions.
6383
If you don't want the data to be escaped, you can pass ``null`` or ``'raw'`` as the final parameter to each function:
6484

6585
.. literalinclude:: view_renderer/004.php
86+
:lines: 2-
6687

6788
If you choose not to escape data, or you are passing in an object instance, you can manually escape the data within
68-
the view with the ``esc()`` function. The first parameter is the string to escape. The second parameter is the
89+
the view with the :php:func:`esc()` function. The first parameter is the string to escape. The second parameter is the
6990
context to escape the data for (see below)::
7091

7192
<?= esc($object->getStat()) ?>
@@ -99,9 +120,10 @@ Several options can be passed to the ``render()`` or ``renderString()`` methods:
99120
- ``cache_name`` - the ID used to save/retrieve a cached view result; defaults to the viewpath; ignored for ``renderString()``
100121
- ``saveData`` - true if the view data parameters should be retained for subsequent calls
101122

102-
.. note:: ``saveData`` as defined by the interface must be a boolean, but implementing
123+
.. note:: ``saveData()`` as defined by the interface must be a boolean, but implementing
103124
classes (like ``View`` below) may extend this to include ``null`` values.
104125

126+
***************
105127
Class Reference
106128
***************
107129

@@ -110,7 +132,6 @@ Class Reference
110132
.. php:class:: View
111133
112134
.. php:method:: render($view[, $options[, $saveData = false]])
113-
:noindex:
114135
115136
:param string $view: File name of the view source
116137
:param array $options: Array of options, as key/value pairs
@@ -121,9 +142,9 @@ Class Reference
121142
Builds the output based upon a file name and any data that has already been set:
122143

123144
.. literalinclude:: view_renderer/005.php
145+
:lines: 2-
124146

125147
.. php:method:: renderString($view[, $options[, $saveData = false]])
126-
:noindex:
127148
128149
:param string $view: Contents of the view to render, for instance content retrieved from a database
129150
:param array $options: Array of options, as key/value pairs
@@ -134,14 +155,14 @@ Class Reference
134155
Builds the output based upon a view fragment and any data that has already been set:
135156

136157
.. literalinclude:: view_renderer/006.php
158+
:lines: 2-
137159

138160
.. warning:: This could be used for displaying content that might have been stored in a database,
139161
but you need to be aware that this is a potential security vulnerability,
140162
and that you **must** validate any such data, and probably escape it
141163
appropriately!
142164

143165
.. php:method:: setData([$data[, $context = null]])
144-
:noindex:
145166
146167
:param array $data: Array of view data strings, as key/value pairs
147168
:param string $context: The context to use for data escaping.
@@ -151,6 +172,7 @@ Class Reference
151172
Sets several pieces of view data at once:
152173

153174
.. literalinclude:: view_renderer/007.php
175+
:lines: 2-
154176

155177
Supported escape contexts: ``html``, ``css``, ``js``, ``url``, or ``attr`` or ``raw``.
156178
If ``'raw'``, no escaping will happen.
@@ -159,7 +181,6 @@ Class Reference
159181
until the view is rendered.
160182

161183
.. php:method:: setVar($name[, $value = null[, $context = null]])
162-
:noindex:
163184
164185
:param string $name: Name of the view data variable
165186
:param mixed $value: The value of this view data
@@ -170,6 +191,7 @@ Class Reference
170191
Sets a single piece of view data:
171192

172193
.. literalinclude:: view_renderer/008.php
194+
:lines: 2-
173195

174196
Supported escape contexts: ``html``, ``css``, ``js``, ``url``, ``attr`` or ``raw``.
175197
If ``'raw'``, no escaping will happen.

0 commit comments

Comments
 (0)