|
525
|
1 |
<!DOCTYPE html> |
|
|
2 |
<html lang="en"> |
|
|
3 |
<head> |
|
|
4 |
<meta charset="utf-8"> |
|
|
5 |
<title>View</title> |
|
|
6 |
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic"> |
|
|
7 |
<link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css"> |
|
|
8 |
<link rel="stylesheet" href="../assets/css/main.css"> |
|
|
9 |
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css"> |
|
|
10 |
<link rel="shortcut icon" type="image/png" href="../assets/favicon.png"> |
|
|
11 |
<script src="../../build/yui/yui-min.js"></script> |
|
|
12 |
|
|
|
13 |
</head> |
|
|
14 |
<body> |
|
|
15 |
<!-- |
|
|
16 |
<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a> |
|
|
17 |
--> |
|
|
18 |
<div id="doc"> |
|
|
19 |
<div id="hd"> |
|
|
20 |
<h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1> |
|
|
21 |
</div> |
|
|
22 |
|
|
|
23 |
<a href="#toc" class="jump">Jump to Table of Contents</a> |
|
|
24 |
|
|
|
25 |
|
|
|
26 |
<h1>View</h1> |
|
|
27 |
<div class="yui3-g"> |
|
|
28 |
<div class="yui3-u-3-4"> |
|
|
29 |
<div id="main"> |
|
|
30 |
<div class="content"><div class="intro"> |
|
|
31 |
<p> |
|
|
32 |
A View represents a renderable piece of an application's user interface, and provides hooks for easily subscribing to and handling delegated DOM events on a view's container element. |
|
|
33 |
</p> |
|
|
34 |
|
|
|
35 |
<p> |
|
|
36 |
Views provide a generic structure for template- or DOM-based rendering. Views are template-agnostic, meaning that there's no actual template language built in, so you're welcome to use any template language you want (or none at all). |
|
|
37 |
</p> |
|
|
38 |
|
|
|
39 |
<p> |
|
|
40 |
A common practice is to associate a View instance with a <a href="../model/index.html">Model</a> instance so that the view is automatically re-rendered whenever the data in the model changes, but this relationship is not required. A view may also be used standalone, associated with a <a href="../model-list/index.html">Model List</a>, or may even contain nested views. |
|
|
41 |
</p> |
|
|
42 |
|
|
|
43 |
<p> |
|
|
44 |
The <code>Y.View</code> class is meant to be extended by a custom class that defines a custom <code>render()</code> method and any necessary DOM event handlers. |
|
|
45 |
</p> |
|
|
46 |
</div> |
|
|
47 |
|
|
|
48 |
<h2 id="getting-started">Getting Started</h2> |
|
|
49 |
|
|
|
50 |
<p> |
|
|
51 |
To include the source files for View and its dependencies, first load |
|
|
52 |
the YUI seed file if you haven't already loaded it. |
|
|
53 |
</p> |
|
|
54 |
|
|
|
55 |
<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre> |
|
|
56 |
|
|
|
57 |
|
|
|
58 |
<p> |
|
|
59 |
Next, create a new YUI instance for your application and populate it with the |
|
|
60 |
modules you need by specifying them as arguments to the <code>YUI().use()</code> method. |
|
|
61 |
YUI will automatically load any dependencies required by the modules you |
|
|
62 |
specify. |
|
|
63 |
</p> |
|
|
64 |
|
|
|
65 |
<pre class="code prettyprint"><script> |
|
|
66 |
// Create a new YUI instance and populate it with the required modules. |
|
|
67 |
YUI().use('view', function (Y) { |
|
|
68 |
// View is available and ready for use. Add implementation |
|
|
69 |
// code here. |
|
|
70 |
}); |
|
|
71 |
</script></pre> |
|
|
72 |
|
|
|
73 |
|
|
|
74 |
<p> |
|
|
75 |
For more information on creating YUI instances and on the |
|
|
76 |
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the |
|
|
77 |
documentation for the <a href="../yui/index.html">YUI Global Object</a>. |
|
|
78 |
</p> |
|
|
79 |
|
|
|
80 |
|
|
|
81 |
<h2 id="upgrading-from-yui-34x">Upgrading from YUI 3.4.x</h2> |
|
|
82 |
|
|
|
83 |
<p> |
|
|
84 |
A beta version of View was first introduced in YUI 3.4.0. If you're using View in YUI 3.4.0 or 3.4.1, you'll need to make the following changes to your code when upgrading: |
|
|
85 |
</p> |
|
|
86 |
|
|
|
87 |
<ul> |
|
|
88 |
<li> |
|
|
89 |
<p> |
|
|
90 |
The <code>container</code>, <code>model</code>, and <code>modelList</code> properties are now attributes. If you were accessing them as properties, update your code to access them as attributes instead. For example, <code>var model = myView.model</code> becomes <code>var model = myView.get('model')</code>, and <code>myView.model = thing</code> becomes <code>myView.set('model', thing);</code>. |
|
|
91 |
</p> |
|
|
92 |
</li> |
|
|
93 |
|
|
|
94 |
<li> |
|
|
95 |
<p> |
|
|
96 |
The <code>container</code> attribute now treats string values as CSS selectors. Previously, it assumed string values represented raw HTML. To get the same functionality as the old behavior, pass your HTML string through <code>Y.Node.create()</code> before passing it to <code>container</code>. For example, <code>new Y.View({container: '<div/>'})</code> becomes <code>new Y.View({container: Y.Node.create('<div/>')})</code>. |
|
|
97 |
</p> |
|
|
98 |
</li> |
|
|
99 |
|
|
|
100 |
<li> |
|
|
101 |
<p> |
|
|
102 |
Destroying a view no longer also destroys the view's container node by default. To destroy a view's container node when destroying the view, pass <code>{remove: true}</code> to the view's <code>destroy()</code> method. |
|
|
103 |
</p> |
|
|
104 |
</li> |
|
|
105 |
</ul> |
|
|
106 |
|
|
|
107 |
<h2 id="using-view">Using View</h2> |
|
|
108 |
|
|
|
109 |
<h3 id="instantiating-view">Instantiating View</h3> |
|
|
110 |
|
|
|
111 |
<p> |
|
|
112 |
The most basic way to use View is to create an instance of the <code>Y.View</code> class, pass in some configuration attributes, and override the <code>render()</code> method at the instance level to define how your view will be rendered. |
|
|
113 |
</p> |
|
|
114 |
|
|
|
115 |
<p class="tip"> |
|
|
116 |
To demonstrate how to associate a Model with a View, this example uses an instance of the <code>Y.PieModel</code> class that's used in the examples in the <a href="../model/">Model User Guide</a>. |
|
|
117 |
</p> |
|
|
118 |
|
|
|
119 |
<p class="tip"> |
|
|
120 |
Jump to the <a href="#view-attributes">View Attributes</a> section below to learn more about the <code>container</code>, <code>model</code>, and <code>template</code> attributes used in this example. |
|
|
121 |
</p> |
|
|
122 |
|
|
|
123 |
<pre class="code prettyprint">var pie = new Y.PieModel({type: 'apple'}), |
|
|
124 |
|
|
|
125 |
pieView = new Y.View({ |
|
|
126 |
// Override the default container attribute. |
|
|
127 |
container: Y.Node.create('<div class="pie"/>'), |
|
|
128 |
|
|
|
129 |
// Specify an optional model to associate with the view. |
|
|
130 |
model: pie, |
|
|
131 |
|
|
|
132 |
// Provide an optional template that will be used to render the view. The |
|
|
133 |
// template can be anything we want, but in this case we'll use a string |
|
|
134 |
// that will be processed with Y.Lang.sub(). |
|
|
135 |
template: '{slices} slice(s) of {type} pie remaining.' |
|
|
136 |
}); |
|
|
137 |
|
|
|
138 |
// Override the render() method to define how the view will be rendered. |
|
|
139 |
pieView.render = function () { |
|
|
140 |
var container = this.get('container'), |
|
|
141 |
html = Y.Lang.sub(this.template, this.get('model').toJSON()); |
|
|
142 |
|
|
|
143 |
// Render this view's HTML into the container element. |
|
|
144 |
container.setHTML(html); |
|
|
145 |
|
|
|
146 |
// Append the container element to the DOM if it's not on the page already. |
|
|
147 |
if (!container.inDoc()) { |
|
|
148 |
Y.one('body').append(container); |
|
|
149 |
} |
|
|
150 |
|
|
|
151 |
return this; |
|
|
152 |
}; |
|
|
153 |
|
|
|
154 |
// Render the view. |
|
|
155 |
pieView.render();</pre> |
|
|
156 |
|
|
|
157 |
|
|
|
158 |
<p> |
|
|
159 |
This renders the following HTML to the page: |
|
|
160 |
</p> |
|
|
161 |
|
|
|
162 |
<pre class="code prettyprint"><div class="pie"> |
|
|
163 |
6 slice(s) of apple pie remaining. |
|
|
164 |
</div></pre> |
|
|
165 |
|
|
|
166 |
|
|
|
167 |
<p> |
|
|
168 |
Creating an instance of the base <code>Y.View</code> class like this makes it easy to get up and running with a simple view, but probably isn't the best way to create more complex views that need to handle DOM events, re-render automatically on model changes, etc. |
|
|
169 |
</p> |
|
|
170 |
|
|
|
171 |
<p> |
|
|
172 |
For more complex use cases, it's usually better to create a custom View subclass by <a href="#extending-yview">Extending <code>Y.View</code></a>. |
|
|
173 |
</p> |
|
|
174 |
|
|
|
175 |
<h3 id="extending-yview">Extending <code>Y.View</code></h3> |
|
|
176 |
|
|
|
177 |
<p> |
|
|
178 |
The first step in creating a custom View class is to extend <code>Y.View</code>. This allows you to override the <code>render()</code> method and default View attributes to implement the desired behavior for your view, while also adding your own methods to handle DOM events and provide other custom view functionality. |
|
|
179 |
</p> |
|
|
180 |
|
|
|
181 |
<p> |
|
|
182 |
If you want, you can establish a relationship between your view and a <a href="../model/index.html">Model</a> or <a href="../model-list/index.html">Model List</a> instance by attaching event handlers to them in a custom <code>initializer()</code> method. The initializer is typically where you would subscribe to model change events to be notified when you need to re-render your view. |
|
|
183 |
</p> |
|
|
184 |
|
|
|
185 |
<p> |
|
|
186 |
This example demonstrates how to create a <code>Y.PieView</code> class that displays the current state of a <code>Y.PieModel</code> instance like the one defined in the <a href="../model/index.html">Model</a> user guide. It's functionally similar to the example shown in <a href="#instantiating-view">Instantiating View</a>, but adds the ability to handle a DOM event with a custom event handler, and automatically re-renders the view whenever the associated model changes. |
|
|
187 |
</p> |
|
|
188 |
|
|
|
189 |
<pre class="code prettyprint">// Create a new Y.PieView class that extends Y.View and renders the current |
|
|
190 |
// state of a Y.PieModel instance. |
|
|
191 |
Y.PieView = Y.Base.create('pieView', Y.View, [], { |
|
|
192 |
// Add prototype methods and properties for your View here if desired. These |
|
|
193 |
// will be available to all instances of your View. You may also override |
|
|
194 |
// existing default methods and properties of Y.View. |
|
|
195 |
|
|
|
196 |
// Specify delegated DOM events to attach to the container. |
|
|
197 |
events: { |
|
|
198 |
'.eat': {click: 'eatSlice'} |
|
|
199 |
}, |
|
|
200 |
|
|
|
201 |
// Provide a template that will be used to render the view. The template can |
|
|
202 |
// be anything we want, but in this case we'll use a string that will be |
|
|
203 |
// processed with Y.Lang.sub(). |
|
|
204 |
template: '{slices} slice(s) of {type} pie remaining. ' + |
|
|
205 |
'<button class="eat">Eat a Slice!</button>', |
|
|
206 |
|
|
|
207 |
// The initializer function will run when a view is instantiated. This is a |
|
|
208 |
// good time to subscribe to change events on a model instance. |
|
|
209 |
initializer: function () { |
|
|
210 |
var model = this.get('model'); |
|
|
211 |
|
|
|
212 |
// Re-render this view when the model changes, and destroy this view when |
|
|
213 |
// the model is destroyed. |
|
|
214 |
model.after('change', this.render, this); |
|
|
215 |
model.after('destroy', this.destroy, this); |
|
|
216 |
}, |
|
|
217 |
|
|
|
218 |
// The render function is responsible for rendering the view to the page. It |
|
|
219 |
// will be called whenever the model changes. |
|
|
220 |
render: function () { |
|
|
221 |
var container = this.get('container'), |
|
|
222 |
html = Y.Lang.sub(this.template, this.get('model').toJSON()); |
|
|
223 |
|
|
|
224 |
// Render this view's HTML into the container element. |
|
|
225 |
container.setHTML(html); |
|
|
226 |
|
|
|
227 |
// Append the container element to the DOM if it's not on the page already. |
|
|
228 |
if (!container.inDoc()) { |
|
|
229 |
Y.one('body').append(container); |
|
|
230 |
} |
|
|
231 |
|
|
|
232 |
return this; |
|
|
233 |
}, |
|
|
234 |
|
|
|
235 |
// The eatSlice function will handle click events on this view's "Eat a Slice" |
|
|
236 |
// button. |
|
|
237 |
eatSlice: function (e) { |
|
|
238 |
// Call the pie model's eatSlice() function. This will consume a slice of |
|
|
239 |
// pie (if there are any left) and update the model, thus causing the view |
|
|
240 |
// to re-render to reflect the new model data. |
|
|
241 |
this.get('model').eatSlice(); |
|
|
242 |
} |
|
|
243 |
}, { |
|
|
244 |
// Specify attributes and static properties for your View here. |
|
|
245 |
|
|
|
246 |
ATTRS: { |
|
|
247 |
// Override the default container attribute. |
|
|
248 |
container: { |
|
|
249 |
valueFn: function () { |
|
|
250 |
return Y.Node.create('<div class="pie"/>'); |
|
|
251 |
} |
|
|
252 |
} |
|
|
253 |
} |
|
|
254 |
});</pre> |
|
|
255 |
|
|
|
256 |
|
|
|
257 |
<p> |
|
|
258 |
After defining the <code>Y.PieView</code> class and the <code>Y.PieModel</code> class (see the <a href="../model/index.html">Model</a> user guide), we can instantiate a new PieView and associate it with a PieModel instance. |
|
|
259 |
</p> |
|
|
260 |
|
|
|
261 |
<pre class="code prettyprint">var pie = new Y.PieModel({type: 'apple'}), |
|
|
262 |
pieView = new Y.PieView({model: pie}); |
|
|
263 |
|
|
|
264 |
pieView.render();</pre> |
|
|
265 |
|
|
|
266 |
|
|
|
267 |
<p> |
|
|
268 |
This renders the following HTML to the page: |
|
|
269 |
</p> |
|
|
270 |
|
|
|
271 |
<pre class="code prettyprint"><div class="pie"> |
|
|
272 |
6 slice(s) of apple pie remaining. <button class="eat">Eat a Slice!</button> |
|
|
273 |
</div></pre> |
|
|
274 |
|
|
|
275 |
|
|
|
276 |
<p> |
|
|
277 |
If the user clicks the "Eat a Slice!" button, the model will be updated and the view will re-render itself: |
|
|
278 |
</p> |
|
|
279 |
|
|
|
280 |
<pre class="code prettyprint"><div class="pie"> |
|
|
281 |
5 slice(s) of apple pie remaining. <button class="eat">Eat a Slice!</button> |
|
|
282 |
</div></pre> |
|
|
283 |
|
|
|
284 |
|
|
|
285 |
<h3 id="views-models-and-addtarget">Views, Models, and <code>addTarget()</code></h3> |
|
|
286 |
|
|
|
287 |
<p> |
|
|
288 |
In <a href="#extending-yview">Extending <code>Y.View</code></a>, the view's <code>initializer()</code> set two event listeners directly on the model: |
|
|
289 |
</p> |
|
|
290 |
|
|
|
291 |
<pre class="code prettyprint">var model = this.get('model'); |
|
|
292 |
model.after('change', this.render, this); |
|
|
293 |
model.after('destroy', this.destroy, this);</pre> |
|
|
294 |
|
|
|
295 |
|
|
|
296 |
<p> |
|
|
297 |
Alternatively, you can use |
|
|
298 |
<a href="http://yuilibrary.com/yui/docs/api/classes/View.html#method_addTarget">addTarget()</a> |
|
|
299 |
to create a bubbling chain. |
|
|
300 |
In the example below, the view automatically receives events from the model, |
|
|
301 |
which means you can now choose to set change event listeners on the view. |
|
|
302 |
</p> |
|
|
303 |
|
|
|
304 |
<pre class="code prettyprint">Y.PieView = Y.Base.create('pieView', Y.View, [], { |
|
|
305 |
|
|
|
306 |
... |
|
|
307 |
|
|
|
308 |
initializer: function () { |
|
|
309 |
var model = this.get('model'); |
|
|
310 |
|
|
|
311 |
// If this view has a model, bubble model events to the view. |
|
|
312 |
model && model.addTarget(this); |
|
|
313 |
|
|
|
314 |
// If the model gets swapped out, reset targets accordingly. |
|
|
315 |
this.after('modelChange', function (ev) { |
|
|
316 |
ev.prevVal && ev.prevVal.removeTarget(this); |
|
|
317 |
ev.newVal && ev.newVal.addTarget(this); |
|
|
318 |
}); |
|
|
319 |
|
|
|
320 |
// Re-render this view when the model changes. |
|
|
321 |
this.after('*:change', this.render, this); |
|
|
322 |
}, |
|
|
323 |
|
|
|
324 |
...</pre> |
|
|
325 |
|
|
|
326 |
|
|
|
327 |
<p> |
|
|
328 |
The <code>modelChange</code> listener is not strictly necessary, but it does make your code more robust. |
|
|
329 |
If you decide to swap in another model instance sometime after initialization, |
|
|
330 |
this listener ensures that the new model gets wired up properly to the view. |
|
|
331 |
</p> |
|
|
332 |
|
|
|
333 |
<h3 id="view-properties">View Properties</h3> |
|
|
334 |
|
|
|
335 |
<p> |
|
|
336 |
The following properties are meaningful to View classes and subclasses. |
|
|
337 |
</p> |
|
|
338 |
|
|
|
339 |
<table> |
|
|
340 |
<thead> |
|
|
341 |
<tr> |
|
|
342 |
<th>Property</th> |
|
|
343 |
<th>Default Value</th> |
|
|
344 |
<th>Description</th> |
|
|
345 |
</tr> |
|
|
346 |
</thead> |
|
|
347 |
<tbody> |
|
|
348 |
<tr> |
|
|
349 |
<td><code>containerTemplate</code></td> |
|
|
350 |
<td><code>'<div/>'</code></td> |
|
|
351 |
<td> |
|
|
352 |
<p> |
|
|
353 |
HTML template for this view's container element. This will be used to |
|
|
354 |
create the container if no custom container is specified when the view |
|
|
355 |
is created. |
|
|
356 |
</p> |
|
|
357 |
</td> |
|
|
358 |
</tr> |
|
|
359 |
|
|
|
360 |
<tr> |
|
|
361 |
<td><code>events</code></td> |
|
|
362 |
<td><code>{}</code></td> |
|
|
363 |
<td> |
|
|
364 |
<p> |
|
|
365 |
A map of CSS selectors to DOM events that should be handled by your view. Under the hood, event delegation is used so that the actual events are attached to the view's container element. This means you can freely re-render the contents of the container without having to worry about detaching and re-attaching events. |
|
|
366 |
</p> |
|
|
367 |
|
|
|
368 |
<p> |
|
|
369 |
See <a href="#handling-dom-events">Handling DOM Events</a> for more details. |
|
|
370 |
</p> |
|
|
371 |
</td> |
|
|
372 |
</tr> |
|
|
373 |
|
|
|
374 |
<tr> |
|
|
375 |
<td><code>template</code></td> |
|
|
376 |
<td><code>''</code></td> |
|
|
377 |
<td> |
|
|
378 |
<p> |
|
|
379 |
Reference to a template for this view. |
|
|
380 |
</p> |
|
|
381 |
|
|
|
382 |
<p> |
|
|
383 |
This is a convenience property that has no default behavior of its own. It's only provided as a convention to allow you to store whatever you wish to use as a template, whether that's an HTML string, a <code>Y.Node</code> instance, a Mustache template, or anything else your heart desires. |
|
|
384 |
</p> |
|
|
385 |
|
|
|
386 |
<p> |
|
|
387 |
How this template gets used is entirely up to you and your custom <code>render()</code> method. See <a href="#rendering-a-view">Rendering a View</a> for more details. |
|
|
388 |
</p> |
|
|
389 |
</td> |
|
|
390 |
</tr> |
|
|
391 |
</tbody> |
|
|
392 |
</table> |
|
|
393 |
|
|
|
394 |
<p class="tip"> |
|
|
395 |
The View class uses both properties and attributes. What's the difference? In short, properties are best for storing data that might be useful to multiple instances of a View, whereas attributes are best for storing data that pertains only to a specific instance. |
|
|
396 |
</p> |
|
|
397 |
|
|
|
398 |
<h3 id="view-attributes">View Attributes</h3> |
|
|
399 |
|
|
|
400 |
<p> |
|
|
401 |
View classes and subclasses provide the following attributes. |
|
|
402 |
</p> |
|
|
403 |
|
|
|
404 |
<table> |
|
|
405 |
<thead> |
|
|
406 |
<tr> |
|
|
407 |
<th>Attribute</th> |
|
|
408 |
<th>Default Value</th> |
|
|
409 |
<th>Description</th> |
|
|
410 |
</tr> |
|
|
411 |
</thead> |
|
|
412 |
<tbody> |
|
|
413 |
<tr> |
|
|
414 |
<td><code>container</code></td> |
|
|
415 |
<td><code><div></code> Node</td> |
|
|
416 |
<td> |
|
|
417 |
<p> |
|
|
418 |
A DOM element, <code>Y.Node</code> instance, or selector string representing an element that will contain the view's rendered content. The view's DOM events will be attached to this container so that they don't have to be re-attached if the view is re-rendered. |
|
|
419 |
</p> |
|
|
420 |
|
|
|
421 |
<p> |
|
|
422 |
If you specify a container element that isn't already on the page, then you'll need to append it to the page yourself. You can do this in the <code>render()</code> method the first time the view is rendered. |
|
|
423 |
</p> |
|
|
424 |
|
|
|
425 |
<p> |
|
|
426 |
Note that if you are extending a view and want to set a default value for the <code>container</code> attribute in <code>ATTRS</code>, you must use <code>valueFn</code>: |
|
|
427 |
</p> |
|
|
428 |
|
|
|
429 |
<pre class="code prettyprint">ATTRS: { |
|
|
430 |
container: { |
|
|
431 |
valueFn: function () { /* return a Y.Node */ } |
|
|
432 |
} |
|
|
433 |
}</pre> |
|
|
434 |
|
|
|
435 |
<p> |
|
|
436 |
The view's constructor will ignore any assignments using the <code>value</code> property. The reason for this is that <code>container</code> already supplies its own <code>valueFn</code>, which <a href="/yui/docs/attribute/#configuration">takes priority over <code>value</code></a>. |
|
|
437 |
</p> |
|
|
438 |
</td> |
|
|
439 |
</tr> |
|
|
440 |
</tbody> |
|
|
441 |
</table> |
|
|
442 |
|
|
|
443 |
<p> |
|
|
444 |
Views also support ad-hoc attributes, meaning you can simply pass an object hash to a view's constructor and attributes will automatically be created for the keys you specify. |
|
|
445 |
</p> |
|
|
446 |
|
|
|
447 |
<pre class="code prettyprint">// Instantiate a view and setting some ad-hoc attributes. |
|
|
448 |
var view = new Y.View({foo: 'foo', bar: 'bar'}); |
|
|
449 |
|
|
|
450 |
view.get('foo'); // => "foo" |
|
|
451 |
view.get('bar'); // => "bar"</pre> |
|
|
452 |
|
|
|
453 |
|
|
|
454 |
<h3 id="handling-dom-events">Handling DOM Events</h3> |
|
|
455 |
|
|
|
456 |
<p> |
|
|
457 |
The <code>events</code> property of a view class allows you to specify a mapping of CSS selectors to DOM events that should be handled by your view. |
|
|
458 |
</p> |
|
|
459 |
|
|
|
460 |
<p> |
|
|
461 |
Under the hood, event delegation is used so that the actual events are attached to the view's container element. This means you can freely re-render the contents of the container without having to worry about detaching and re-attaching events. |
|
|
462 |
</p> |
|
|
463 |
|
|
|
464 |
<p> |
|
|
465 |
Event handlers may be specified as functions or as strings that map to function names on the view instance or its prototype. |
|
|
466 |
</p> |
|
|
467 |
|
|
|
468 |
<pre class="code prettyprint">var Y.MyView = Y.Base.create('myView', Y.View, [], { |
|
|
469 |
events: { |
|
|
470 |
// Call `this.toggle()` whenever the element with the id "toggle-button" |
|
|
471 |
// is clicked. |
|
|
472 |
'#toggle-button': {click: 'toggle'}, |
|
|
473 |
|
|
|
474 |
// Call `this.hoverOn()` when the mouse moves over any element with the |
|
|
475 |
// "hoverable" class, and `this.hoverOff()` when the mouse moves out of |
|
|
476 |
// any element with the "hoverable" class. |
|
|
477 |
'.hoverable': { |
|
|
478 |
mouseover: 'hoverOn', |
|
|
479 |
mouseout : 'hoverOff' |
|
|
480 |
} |
|
|
481 |
}, |
|
|
482 |
|
|
|
483 |
hoverOff: function (e) { |
|
|
484 |
// ... handle the mouseout event ... |
|
|
485 |
}, |
|
|
486 |
|
|
|
487 |
hoverOn: function (e) { |
|
|
488 |
// ... handle the mouseover event ... |
|
|
489 |
}, |
|
|
490 |
|
|
|
491 |
toggle: function (e) { |
|
|
492 |
// ... handle the click event ... |
|
|
493 |
} |
|
|
494 |
});</pre> |
|
|
495 |
|
|
|
496 |
|
|
|
497 |
<p> |
|
|
498 |
The <code>this</code> object in view event handlers will always refer to the current view instance. If you'd prefer <code>this</code> to refer to something else, use <code>Y.bind()</code> to bind a custom <code>this</code> object. |
|
|
499 |
</p> |
|
|
500 |
|
|
|
501 |
<p> |
|
|
502 |
At instantiation time, you can provide an <code>events</code> config property to add or override event handlers for individual view instances. |
|
|
503 |
</p> |
|
|
504 |
|
|
|
505 |
<pre class="code prettyprint">// Overriding or adding event handlers on a per-instance basis. |
|
|
506 |
var myView = new Y.MyView({ |
|
|
507 |
events: { |
|
|
508 |
// Replace the #toggle-button click handler with a custom one. |
|
|
509 |
'#toggle-button': { |
|
|
510 |
click: function (e) { |
|
|
511 |
// ... custom click handler ... |
|
|
512 |
} |
|
|
513 |
}, |
|
|
514 |
|
|
|
515 |
// Add a handler for focus events on elements with the "focusable" class. |
|
|
516 |
'.focusable': { |
|
|
517 |
focus: function (e) { |
|
|
518 |
// ... custom focus handler ... |
|
|
519 |
} |
|
|
520 |
} |
|
|
521 |
} |
|
|
522 |
});</pre> |
|
|
523 |
|
|
|
524 |
|
|
|
525 |
<h3 id="rendering-a-view">Rendering a View</h3> |
|
|
526 |
|
|
|
527 |
<p> |
|
|
528 |
A view's default <code>render()</code> method is completely empty. It's up to you to override this method and fill it with your own rendering logic. |
|
|
529 |
</p> |
|
|
530 |
|
|
|
531 |
<p> |
|
|
532 |
The ultimate goal of your <code>render()</code> function is to put some HTML into the view's container element and ensure that the container is on the page. How you choose to do this is entirely up to you. |
|
|
533 |
</p> |
|
|
534 |
|
|
|
535 |
<p> |
|
|
536 |
You might choose to use plain old DOM manipulation to create the elements for your view, or you might store an HTML string in your view's <code>template</code> property and then render that, or you might even store a full-blown template (perhaps using <a href="http://www.handlebarsjs.com/">Handlebars</a> or <a href="http://mustache.github.com/">Mustache</a>). The View component intentionally avoids dictating how you render things, so you're free to do whatever you like best. |
|
|
537 |
</p> |
|
|
538 |
|
|
|
539 |
<p> |
|
|
540 |
<strong>Note:</strong> Ideally your <code>render()</code> method should also return <code>this</code> at the end to allow chaining, but that's up to you. |
|
|
541 |
</p> |
|
|
542 |
|
|
|
543 |
<p> |
|
|
544 |
In general, it makes sense to <a href="#associating-a-view-with-a-model-or-model-list">associate a view with a Model or Model List instance</a> so that you can update the view when related data changes. You can do this either by re-rendering the entire view (this is the easiest way) or by modifying only the parts of the view that have changed (harder, but possibly more performant). |
|
|
545 |
</p> |
|
|
546 |
|
|
|
547 |
<p> |
|
|
548 |
Again, which route you choose to take is entirely up to you. |
|
|
549 |
</p> |
|
|
550 |
|
|
|
551 |
<h3 id="associating-a-view-with-a-model-or-model-list">Associating a View with a Model or Model List</h3> |
|
|
552 |
|
|
|
553 |
<p> |
|
|
554 |
When instantiating a view, you may pass a <code>model</code> attribute in the config object that references a <a href="../model/index.html">Model</a> instance you wish to associate with the view. |
|
|
555 |
</p> |
|
|
556 |
|
|
|
557 |
<pre class="code prettyprint">// Associate a PieModel instance with a PieView instance. |
|
|
558 |
var pie = new Y.PieModel({type: 'apple'}), |
|
|
559 |
pieView = new Y.PieView({model: pie});</pre> |
|
|
560 |
|
|
|
561 |
|
|
|
562 |
<p> |
|
|
563 |
This attribute is entirely optional. There's no requirement that views be associated with models, but if you do intend to associate your view with a model, then specifying that model instance at instantiation time will cause a reference to be stored for convenience. |
|
|
564 |
</p> |
|
|
565 |
|
|
|
566 |
<p> |
|
|
567 |
There's no special magic under the hood that will link the model to your view; you'll still need to manually subscribe to any model events you want to handle in your view's <code>initializer()</code> function (see the example in <a href="#extending-yview">Extending <code>Y.View</code></a>). |
|
|
568 |
</p> |
|
|
569 |
|
|
|
570 |
<p> |
|
|
571 |
Instead of specifying a model association, you could also choose to associate your view with a <a href="../model-list/index.html">Model List</a>, or even with nothing at all. It's entirely up to you. |
|
|
572 |
</p> |
|
|
573 |
|
|
|
574 |
<p> |
|
|
575 |
To associate a view with a <a href="../model-list/index.html">Model List</a> instead of a Model, use the <code>modelList</code> config attribute. In your view's initializer, attach event listeners to list events to re-render the view when the list's contents change or when the data of one of the models in the list changes. |
|
|
576 |
</p> |
|
|
577 |
|
|
|
578 |
<pre class="code prettyprint">// Create a custom View subclass that's associated with a Model List. |
|
|
579 |
var Y.PieListView = Y.Base.create('pieListView', Y.View, [], { |
|
|
580 |
// ... other prototype properties and methods ... |
|
|
581 |
|
|
|
582 |
initializer: function () { |
|
|
583 |
var list = this.get('modelList'); |
|
|
584 |
|
|
|
585 |
// Re-render this view when a model is added to or removed from the model |
|
|
586 |
// list. |
|
|
587 |
list.after(['add', 'remove', 'reset'], this.render, this); |
|
|
588 |
|
|
|
589 |
// We'll also re-render the view whenever the data of one of the models in |
|
|
590 |
// the list changes. |
|
|
591 |
list.after('*:change', this.render, this); |
|
|
592 |
} |
|
|
593 |
|
|
|
594 |
// ... other prototype properties and methods ... |
|
|
595 |
});</pre> |
|
|
596 |
|
|
|
597 |
|
|
|
598 |
<p> |
|
|
599 |
Then pass in a Model List instance when instantiating your view. |
|
|
600 |
</p> |
|
|
601 |
|
|
|
602 |
<pre class="code prettyprint">var pies = new Y.PieList(), |
|
|
603 |
pieListView = new Y.PieListView({modelList: pies}); |
|
|
604 |
|
|
|
605 |
// When we add a pie to the list, the view will be re-rendered. |
|
|
606 |
pies.add({type: 'banana cream'});</pre> |
|
|
607 |
|
|
|
608 |
|
|
|
609 |
<p> |
|
|
610 |
The <code>model</code> and <code>modelList</code> attributes are really just ad-hoc attributes that are created on demand, so using "model" and "modelList" as the names is just a convention and not a baked-in requirement. Feel free to store your models and model lists under different attribute names if you want. |
|
|
611 |
</p> |
|
|
612 |
|
|
|
613 |
<h2 id="view-extensions">View Extensions</h2> |
|
|
614 |
|
|
|
615 |
<h3 id="yviewnodemap">Y.View.NodeMap</h3> |
|
|
616 |
|
|
|
617 |
<p> |
|
|
618 |
The <a href="http://yuilibrary.com/yui/docs/api/classes/View.NodeMap.html">NodeMap</a> extension adds a static <code>getByNode()</code> method to a View subclass that returns the View instance associated with a given Node instance (much like <code>Y.Widget.getByNode()</code> does for widgets). The Node may be a View container or a child of a View container. |
|
|
619 |
</p> |
|
|
620 |
|
|
|
621 |
<p> |
|
|
622 |
This functionality is provided by an optional extension because it requires you to manually call <code>destroy()</code> on your views when you're done using them in order to avoid memory leaks due to long-lived internal references. |
|
|
623 |
</p> |
|
|
624 |
|
|
|
625 |
<p> |
|
|
626 |
To use this extension, load the <code>view-node-map</code> module and pass <code>Y.View.NodeMap</code> in the extensions array when creating a View subclass. |
|
|
627 |
</p> |
|
|
628 |
|
|
|
629 |
<pre class="code prettyprint"><div id="container"> |
|
|
630 |
<div id="child"></div> |
|
|
631 |
</div> |
|
|
632 |
|
|
|
633 |
<script> |
|
|
634 |
YUI().use('view', 'view-node-map', function (Y) { |
|
|
635 |
// Create a custom View subclass that mixes in the Y.View.NodeMap extension. |
|
|
636 |
Y.PieView = Y.Base.create('pieView', Y.View, [Y.View.NodeMap]); |
|
|
637 |
|
|
|
638 |
// Create a new instance of the custom View. |
|
|
639 |
var pieView = new Y.PieView({container: '#container'}); |
|
|
640 |
|
|
|
641 |
// Look up the View instance by its container. |
|
|
642 |
Y.PieView.getByNode('#container'); // returns the pieView instance |
|
|
643 |
|
|
|
644 |
// ...or by a child of its container. |
|
|
645 |
Y.PieView.getByNode('#child'); // also returns the pieView instance |
|
|
646 |
}); |
|
|
647 |
</script></pre> |
|
|
648 |
|
|
|
649 |
|
|
|
650 |
<h2 id="views-vs-widgets">Views vs. Widgets</h2> |
|
|
651 |
|
|
|
652 |
<p> |
|
|
653 |
While <code>Y.View</code> and <a href="../widget/index.html"><code>Y.Widget</code></a> may seem similar on the surface, they're intended for different purposes, even though they have some overlap. |
|
|
654 |
</p> |
|
|
655 |
|
|
|
656 |
<p> |
|
|
657 |
In a nutshell: a view is meant to be used as an internal piece of a component or application, and is not intended to be exposed to external developers as an API or a reusable component itself. A widget, on the other hand, is meant to be a reusable component with a public API. |
|
|
658 |
</p> |
|
|
659 |
|
|
|
660 |
<p> |
|
|
661 |
Views are well suited for rendering portions of web pages, whether large or small, since they're lightweight and can be easily associated with Models and Model Lists. A view may even be responsible for creating and rendering widgets on a page, but the view is an internal piece of an application or component and is not meant to be used externally. |
|
|
662 |
</p> |
|
|
663 |
|
|
|
664 |
<p> |
|
|
665 |
Widgets are well suited for representing self-contained interactive controls or objects that behave like first-class HTML elements. A widget might actually use views to provide a visual representation and even handle some DOM events — but only as internal plumbing. The widget itself is responsible for providing a reusable public API. |
|
|
666 |
</p> |
|
|
667 |
</div> |
|
|
668 |
</div> |
|
|
669 |
</div> |
|
|
670 |
|
|
|
671 |
<div class="yui3-u-1-4"> |
|
|
672 |
<div class="sidebar"> |
|
|
673 |
|
|
|
674 |
<div id="toc" class="sidebox"> |
|
|
675 |
<div class="hd"> |
|
|
676 |
<h2 class="no-toc">Table of Contents</h2> |
|
|
677 |
</div> |
|
|
678 |
|
|
|
679 |
<div class="bd"> |
|
|
680 |
<ul class="toc"> |
|
|
681 |
<li> |
|
|
682 |
<a href="#getting-started">Getting Started</a> |
|
|
683 |
</li> |
|
|
684 |
<li> |
|
|
685 |
<a href="#upgrading-from-yui-34x">Upgrading from YUI 3.4.x</a> |
|
|
686 |
</li> |
|
|
687 |
<li> |
|
|
688 |
<a href="#using-view">Using View</a> |
|
|
689 |
<ul class="toc"> |
|
|
690 |
<li> |
|
|
691 |
<a href="#instantiating-view">Instantiating View</a> |
|
|
692 |
</li> |
|
|
693 |
<li> |
|
|
694 |
<a href="#extending-yview">Extending <code>Y.View</code></a> |
|
|
695 |
</li> |
|
|
696 |
<li> |
|
|
697 |
<a href="#views-models-and-addtarget">Views, Models, and <code>addTarget()</code></a> |
|
|
698 |
</li> |
|
|
699 |
<li> |
|
|
700 |
<a href="#view-properties">View Properties</a> |
|
|
701 |
</li> |
|
|
702 |
<li> |
|
|
703 |
<a href="#view-attributes">View Attributes</a> |
|
|
704 |
</li> |
|
|
705 |
<li> |
|
|
706 |
<a href="#handling-dom-events">Handling DOM Events</a> |
|
|
707 |
</li> |
|
|
708 |
<li> |
|
|
709 |
<a href="#rendering-a-view">Rendering a View</a> |
|
|
710 |
</li> |
|
|
711 |
<li> |
|
|
712 |
<a href="#associating-a-view-with-a-model-or-model-list">Associating a View with a Model or Model List</a> |
|
|
713 |
</li> |
|
|
714 |
</ul> |
|
|
715 |
</li> |
|
|
716 |
<li> |
|
|
717 |
<a href="#view-extensions">View Extensions</a> |
|
|
718 |
<ul class="toc"> |
|
|
719 |
<li> |
|
|
720 |
<a href="#yviewnodemap">Y.View.NodeMap</a> |
|
|
721 |
</li> |
|
|
722 |
</ul> |
|
|
723 |
</li> |
|
|
724 |
<li> |
|
|
725 |
<a href="#views-vs-widgets">Views vs. Widgets</a> |
|
|
726 |
</li> |
|
|
727 |
</ul> |
|
|
728 |
</div> |
|
|
729 |
</div> |
|
|
730 |
|
|
|
731 |
|
|
|
732 |
|
|
|
733 |
|
|
|
734 |
|
|
|
735 |
<div class="sidebox"> |
|
|
736 |
<div class="hd"> |
|
|
737 |
<h2 class="no-toc">Examples That Use This Component</h2> |
|
|
738 |
</div> |
|
|
739 |
|
|
|
740 |
<div class="bd"> |
|
|
741 |
<ul class="examples"> |
|
|
742 |
|
|
|
743 |
|
|
|
744 |
<li data-description="A basic todo list built with the Model, Model List, and View components."> |
|
|
745 |
<a href="../app/app-todo.html">Todo List</a> |
|
|
746 |
</li> |
|
|
747 |
|
|
|
748 |
|
|
|
749 |
|
|
|
750 |
<li data-description="An application to browse through the contributors of a GitHub project."> |
|
|
751 |
<a href="../app/app-contributors.html">GitHub Contributors</a> |
|
|
752 |
</li> |
|
|
753 |
|
|
|
754 |
|
|
|
755 |
</ul> |
|
|
756 |
</div> |
|
|
757 |
</div> |
|
|
758 |
|
|
|
759 |
</div> |
|
|
760 |
</div> |
|
|
761 |
</div> |
|
|
762 |
</div> |
|
|
763 |
|
|
|
764 |
<script src="../assets/vendor/prettify/prettify-min.js"></script> |
|
|
765 |
<script>prettyPrint();</script> |
|
|
766 |
|
|
|
767 |
<script> |
|
|
768 |
YUI.Env.Tests = { |
|
|
769 |
examples: [], |
|
|
770 |
project: '../assets', |
|
|
771 |
assets: '../assets/view', |
|
|
772 |
name: 'view', |
|
|
773 |
title: 'View', |
|
|
774 |
newWindow: '', |
|
|
775 |
auto: false |
|
|
776 |
}; |
|
|
777 |
YUI.Env.Tests.examples.push('app-todo'); |
|
|
778 |
YUI.Env.Tests.examples.push('app-contributors'); |
|
|
779 |
|
|
|
780 |
</script> |
|
|
781 |
<script src="../assets/yui/test-runner.js"></script> |
|
|
782 |
|
|
|
783 |
|
|
|
784 |
|
|
|
785 |
</body> |
|
|
786 |
</html> |