You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: the-basics/layouts-and-views/views/README.md
+77-23Lines changed: 77 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,46 @@
1
1
# Views
2
2
3
-
Views are HTML content that can be rendered inside of a layout or by themselves. They can be either rendered on demand or by being set by an event handler. Views can also produce any type of content apart from HTML like JSON/XML/WDDX via our view renderer that we will discover also. So get ready for some rendering goodness!
4
-
5
-
## Setting Views For Rendering
6
-
7
-
Usually, event handlers are the objects in charge of setting views for rendering. However, ANY object that has access to the request context object can do this also. This is done by using the `setView()` method in the request context object.
3
+
Views are HTML content that can be rendered inside a layout or by themselves. They can be rendered on-demand or set by an event handler. Views can also produce content apart from HTML, like JSON/XML/WDDX, via our view renderer, which we will discover. So get ready for some rendering goodness!
4
+
5
+
## Setting Views For Rendering - `setView()`
6
+
7
+
Event handlers are usually the ones responsible for setting views for rendering. However, it's important to understand that ANY object with access to the request context object can also perform this task. This knowledge will keep you informed about the rendering process. The `setView()` method in the request context object is the tool that enables this functionality.
8
+
9
+
```cfscript
10
+
/**
11
+
* Set the view to render in this request. Private Request Collection Name: currentView, currentLayout
12
+
*
13
+
* @view The name of the view to set. If a layout has been defined it will assign it, else if will assign the default layout. No extension please
14
+
* @args An optional set of arguments that will be available when the view is rendered
15
+
* @layout You can override the rendering layout of this setView() call if you want to. Else it defaults to implicit resolution or another override.
16
+
* @module The explicit module view
17
+
* @noLayout Boolean flag, wether the view sent in will be using a layout or not. Default is false. Uses a pre set layout or the default layout.
18
+
* @cache True if you want to cache the rendered view.
19
+
* @cacheTimeout The cache timeout in minutes
20
+
* @cacheLastAccessTimeout The last access timeout in minutes
21
+
* @cacheSuffix Add a cache suffix to the view cache entry. Great for multi-domain caching or i18n caching.
22
+
* @cacheProvider The cache provider you want to use for storing the rendered view. By default we use the 'template' cache provider
23
+
* @name This triggers a rendering region. This will be the unique name in the request for specifying a rendering region, you can then render it by passing the unique name to the view();
24
+
*
25
+
* @return RequestContext
26
+
*/
27
+
function setView(
28
+
view,
29
+
struct args = {},
30
+
layout,
31
+
module = "",
32
+
boolean noLayout = false,
33
+
boolean cache = false,
34
+
cacheTimeout = "",
35
+
cacheLastAccessTimeout = "",
36
+
cacheSuffix = "",
37
+
cacheProvider = "template",
38
+
name
39
+
)
40
+
```
8
41
9
42
{% hint style="info" %}
10
-
Setting a view does not mean that it gets rendered immediately. It means that it is deposited in the request context. The framework will later on in the execution processpick those variables up and do the actual rendering. To do immediate rendering you will use the inline rendering methods describe later on.
43
+
Setting a view does not mean that it gets rendered immediately. This means that it is deposited in the context of the request. Later on in the execution process, the framework will pick those variables up and do the actual rendering. To do immediate rendering, you will use the inline rendering methods described later.
11
44
{% endhint %}
12
45
13
46
{% code title="handlers/main.cfc" %}
@@ -27,15 +60,15 @@ component
27
60
```
28
61
{% endcode %}
29
62
30
-
We use the `setView()` method to set the view `views/general/index.cfm` to be rendered. Now the cool thing about this, is that we can override the view to be rendered anytime during the flow of the request. So the last process to execute the `setView()` method is the one that counts. Also notice a few things:
63
+
We use the `setView()` method to set the view `views/general/index.cfm` to be rendered. The cool thing about this is that we can override the view to be rendered anytime during the request flow. So, the last process to execute the `setView()` method is the one that counts. Also, notice a few things:
31
64
32
-
* No `.cfm`extension is needed.
65
+
* No extension is needed.
33
66
* You can traverse directories by using `/` like normal `cfinclude` notation.
34
-
* The view can exist in the conventions directory `views` or in your configured external locations
35
-
* You did not specify a layout for the view, so the application's default layout (`main.cfm`) will be used.
67
+
* The view can exist in the conventions directory `views` or your configured external locations
68
+
* You did not specify a layout for the view, so the application's default layout (`Main`) will be used.
36
69
37
70
{% hint style="danger" %}
38
-
It is best practice that view locations should simulate the event. So if the event is **general.index**, there should be a **general** folder in the root **views** folder with a view called **index.cfm.**
71
+
It is best practice that view locations should simulate the event. So, if the event is **general.index**, there should be a **general** folder in the root **views** folder with a view called **index.cfm/bxm**
39
72
{% endhint %}
40
73
41
74
**Let's look at the view code:**
@@ -45,16 +78,15 @@ It is best practice that view locations should simulate the event. So if the eve
I am using our cool HTML Helper class that is smart enough to render tables, data, HTML 5 elements etc and even bind to ColdFusion ORM entities.
85
+
I am using our cool HTML Helper class, which is smart enough to render tables, data, HTML 5 elements, etc., and even bind to ColdFusion ORM entities.
54
86
55
87
### Views With No Layout
56
88
57
-
So what happens if I DO NOT want the view to be rendered within a layout? Am I doomed? Of course not, just use the same method with the `noLayout` argument or `event.noLayout()` method:
89
+
So what happens if I DO NOT want the view rendered within a layout? Am I doomed? Of course not, use the same method with the `noLayout` argument or `event.noLayout()` method:
58
90
59
91
```javascript
60
92
component{
@@ -106,7 +138,7 @@ If you need the set a view to be rendered from a specific ColdBox Module then us
106
138
```javascript
107
139
component name="general"{
108
140
109
-
functionindex(event,rc,prc){
141
+
functionindex(event,rc,prc){
110
142
111
143
// call some model for data and put into the request collection
112
144
prc.myQuery=getInstance('MyService').getData();
@@ -118,9 +150,31 @@ component name="general"{
118
150
}
119
151
```
120
152
153
+
### View Regions
154
+
155
+
The `setView()` method also has a `name` argument, which you can use to denote a rendering region. This will not affect the main set view rendered by the framework. This will set up the arguments to render the view, and then YOU will use the `#view( name : "myRegion" )#` code to render it wherever you like. The purpose of this method is to encapsulate rendering mechanics from views and let the handlers control it.
156
+
157
+
```cfscript
158
+
function index( event, rc, prc ){
159
+
...
160
+
event.setView(
161
+
name : "userLogins",
162
+
args : { data : userService.getLatestLogins() },
163
+
.. Any other view arguments
164
+
)
165
+
...
166
+
}
167
+
```
168
+
169
+
Now that you have set the named region, you can evaluate it and render it it using the `view()`method
170
+
171
+
```cfscript
172
+
<div id="latestLogins">#view( name : "userLogins" )#</div>
173
+
```
174
+
121
175
## Render Nothing
122
176
123
-
You can also tell the renderer to not render back anything to the user by using the `event.noRender()` method. Maybe you just took some input and need to gracefully shutdown the request into the infamous white screen of death.
177
+
You can also tell the renderer not to render anything back to the user by using the `event.noRender()` method. Maybe you just took some input and need to gracefully shut down the request into the infamous white screen of death.
124
178
125
179
```javascript
126
180
component name="general"{
@@ -137,25 +191,25 @@ component name="general"{
137
191
138
192
## Implicit Views
139
193
140
-
You can also omit the explicit `event.setView()` if you want, ColdBox will then look for the view according to the executing event's syntax by convention. So if the incoming event is called `general.index` and no view is explicitly defined in your handler, ColdBox will look for a view in the `general` folder called `index.cfm`. That is why we recommend trying to match event resolution to view resolution even if you use or not implicit views.
194
+
You can also omit the explicit `event.setView()` if you want, ColdBox will then look for the view according to the executing event's syntax by convention. So if the incoming event is called `general.index` and no view is explicitly defined in your handler, ColdBox will look for a view in the `general` folder called `index.cfm`. We recommend matching event resolution to view resolution, even if you use implicit views.
141
195
142
196
{% hint style="success" %}
143
-
**Tip:** This feature is more for conventions purists than anything else. However, we do recommend as best practice to use explicitly declare the view to be rendered when working with team environments as everybody will know what happens.
197
+
**Tip:** This feature is more for convention purists than anything else. However, we do recommend, as best practice, explicitly declaring the view to be rendered when working with team environments, as everybody will know what happens.
144
198
{% endhint %}
145
199
146
-
```javascript
200
+
```cfscript
147
201
component name="general"{
148
202
149
-
functionindex(event,rc,prc){
203
+
function index(event,rc,prc){
150
204
// call some model for data and put into the request collection
151
-
prc.myQuery=getInstance('MyService').getData();
205
+
prc.myQuery = getInstance('MyService').getData();
152
206
}
153
207
154
208
}
155
209
```
156
210
157
211
{% hint style="danger" %}
158
-
**Caution** If using implicit views, please note that the **name** of the view will **ALWAYS** be in lower case. So please be aware of this **limitation**. I would suggest creating URL Mappings with explicit event declarations so case and location can be controlled. When using implicit views you will also loose fine rendering control.
212
+
**Caution:** If using implicit views, please note that the **name** of the view will **ALWAYS** be in lowercase. So please be aware of this **limitation**. I would suggest creating URL Mappings with explicit event declarations to control case and location. When using implicit views, you will also lose fine rendering control.
The ColdBox rendering engine can also be tweaked to use **case-insensitive** or **sensitive** implicit views by using the `coldbox.caseSensitiveImplicitViews` directive in your `config/ColdBox.cfc`. The default is to turn all implicit views to lower case, so the value is always **false**.
225
+
The ColdBox rendering engine can also be tweaked to use **case-insensitive** or **sensitive** implicit views by using the `coldbox.caseSensitiveImplicitViews` directive in your `config/ColdBox.cfc`. The default is to turn all implicit views to lowercase, so the value is always **false**.
Copy file name to clipboardExpand all lines: the-basics/layouts-and-views/views/rendering-views.md
+105-3Lines changed: 105 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,111 @@
1
1
# Rendering Views
2
2
3
-
We have now seen how to set views to be rendered from our handlers. However, we can use some cool methods to render views and layouts on-demand. These methods exist in the **Renderer** and several facade methods exist in the super type so you can call it from any handler, interceptor, view or layout. 
3
+
## Rendering Methods
4
+
5
+
We have now seen how to set views to be rendered from our handlers. However, we can use some cool methods to render views and layouts on demand. These methods exist in the **Renderer,** and several facade methods exist in the supertype, so you can call it from any handler, interceptor, view, or layout.
4
6
5
7
1.`view()`
6
8
2.`externalView()`
7
9
3.`layout()`
8
10
9
-
Check out the latest [API Docs](http://apidocs.ortussolutions.com/coldbox/current) for the latest arguments:
11
+
Check out the latest [API Docs](http://apidocs.ortussolutions.com/coldbox/current) for the latest arguments.
12
+
13
+
### view()
14
+
15
+
```cfscript
16
+
/**
17
+
* Render out a view
18
+
*
19
+
* @view The the view to render, if not passed, then we look in the request context for the current set view.
20
+
* @args A struct of arguments to pass into the view for rendering, will be available as 'args' in the view.
21
+
* @module The module to render the view from explicitly
22
+
* @cache Cached the view output or not, defaults to false
23
+
* @cacheTimeout The time in minutes to cache the view
24
+
* @cacheLastAccessTimeout The time in minutes the view will be removed from cache if idle or requested
25
+
* @cacheSuffix The suffix to add into the cache entry for this view rendering
26
+
* @cacheProvider The provider to cache this view in, defaults to 'template'
27
+
* @collection A collection to use by this Renderer to render the view as many times as the items in the collection (Array or Query)
28
+
* @collectionAs The name of the collection variable in the partial rendering. If not passed, we will use the name of the view by convention
29
+
* @collectionStartRow The start row to limit the collection rendering with
30
+
* @collectionMaxRows The max rows to iterate over the collection rendering with
31
+
* @collectionDelim A string to delimit the collection renderings by
32
+
* @prePostExempt If true, pre/post view interceptors will not be fired. By default they do fire
33
+
* @name The name of the rendering region to render out, Usually all arguments are coming from the stored region but you override them using this function's arguments.
34
+
* @viewVariables A struct of variables to incorporate into the view's variables scope.
This will inject a [provider](https://wirebox.ortusbooks.com/advanced-topics/providers) of a **Renderer** into your model objects. Remember that renderers are transient objects so you cannot treat them as singletons. The provider is a proxy to the transient object, but you can use it just like the normal object:
152
+
This will inject a [provider](https://wirebox.ortusbooks.com/advanced-topics/providers) of a **Renderer** into your model objects. Remember that renderers are transient objects so you cannot treat them as singletons. The provider is a proxy to the transient object, but you can use it just like the normal object:
0 commit comments