1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<div class="intro component" style="overflow: hidden;">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <img alt="Screen capture of the Console UI"
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith src="{{componentAssets}}/images/small.png"
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith height="203" width="200" style="border: 0 none; float: right; margin-left: 2em;">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith The Console tool provides a display to read log messages emitted by the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith YUI logging subsytem. With this tool, you can tap into the rich
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith event-driven messages included with the YUI Library's debug files.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith This messaging allows you to get a fuller picture of the inner workings
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith of any YUI Library component.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Additionally, when building your own Widgets, utilities or
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith applications, you can include your own log statements and use the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Console to aid in development and debugging. As a simple message
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith display mechanism, you can also repurpose Console through extention or
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith configuration to listen to a different input source and display
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith messages differently.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith{{>getting-started}}
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h3 id="sam">Trigger the CSS skin</h3>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith For the default "Sam" skin to apply to the Console UI, you'll
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith need to apply the <code>yui3-skin-sam</code> class name to an element that
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith is a parent of the element in which the Console lives. You can usually
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith accomplish this simply by putting the class on the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code><body></code> tag:
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<body class="yui3-skin-sam">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith For more information on skinning YUI components and making use of default
323482948b5894e8aaca139d1a8d7819b7e6b926Luke Smith skins, see our
323482948b5894e8aaca139d1a8d7819b7e6b926Luke Smith <a href="http://yuilibrary.com/yui/docs/tutorials/understanding-skinning/">Understanding
323482948b5894e8aaca139d1a8d7819b7e6b926Luke Smith YUI Skins</a> tutorial.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h2 id="logging">The YUI logging subsystem</h2>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith The entry point to YUI's logging subsystem is the YUI instance's <code>log(..)</code> method.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// message category source
249e4018d7634fb9dc0c49976e034993f8fa065cLuke SmithY.log("Hello world!", "info", "myapp");
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith If the YUI instance is configured with <code>debug</code> set to
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>true</code> (the default), any calls to <code>Y.log(..)</code> will
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith be printed to the browser's native <code>console</code> if it has one, and
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith broadcast through the <code>yui:log</code> event.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith When a Console is instantiated, the native console reporting of YUI log
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith messages is disabled in favor of reporting in the Console UI. If you wish
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith to preserve native console reporting, set the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>useBrowserConsole</code> configuration attribute to <code>true</code>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith during Console construction.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h2 id="using">Using the Console Widget</h2>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h3 id="setup">Instantiating and configuring a Console</h3>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4>Instantiation</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Creating an instance of Console is very easy; there are no required
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith configuration attributes, and it is typically rendered without reference to
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith an existing DOM element.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke SmithYUI({..}).use('console', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // Console has no required configuration
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith var yconsole = new Y.Console();
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // In fact, you often don't even need to store the instance
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith new Y.Console().render();
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith /* YOUR CODE HERE */
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith By default, Console instances are positioned absolutely in the top right
ac09af27b374780c2e388a3e0aa7c329c6b637f4Eric Ferraiuolo corner of the page. As seen below and in the examples, this is configurable by
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith setting the <code>style</code> attribute.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="config">Common configuration attributes</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Below are some common configuration attributes. Refer to the API docs for
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith a complete list of configuration options.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Attribute</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Description</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Default</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>logLevel</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Set to "warn" or "error" to omit messages of lesser severity</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>"info"</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>newestOnTop</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Set to false to place new messages <em>below</em> prior messages</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>true</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>consoleLimit</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Limit the number of messages displayed in the UI</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>300</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>height</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Specify the height of the Console. Useful for displaying more messages</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>"300px"</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>style</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Relationship of the Console to the page content. Supported values are "inline", "block", and "separate"</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>"separate" (absolute positioned in the top right corner)</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="buffer">The print loop</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Incoming log messages are buffered and printed in a scheduled batch cycle
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith to lessen the impact to the normal operation of the page. The print loop
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith renders a fixed number of buffered messages at a time.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith The print loop behavior can be configured with the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>printTimeout</code> and <code>printLimit</code> configuration
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith attributes. The former controls the millisecond timeout between iterations
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith of the print loop. The latter limits the number of entries to add to the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Console in each iteration of the print loop. By default their respective
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith values are 100 and 50.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="universal">Share a Console between YUI instances</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Console behaves like any other YUI module and remains sandboxed inside the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith particular YUI instance that spawned it. However, it is possible to create
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith a universal Console to report the activity in the logging subsystems of
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith every YUI instance on the page.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith To support cross YUI instance communication, a shared global EventTarget
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith named <code>Y.Global</code> is exposed on every YUI instance, and
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>yui:log</code> events are configured to bubble to this
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith EventTarget.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Console has attributes <code>logSource</code> and <code>logEvent</code>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith that can be used to link the Console instance up to an entirely different
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith messaging subsystem. By setting the Console's <code>logSource</code> to
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>Y.Global</code> and leaving the <code>logEvent</code> alone, the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith single Console instance will receive log messages from every YUI instance
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith on the page.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke SmithYUI().use('console','overlay', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // Create a universal Console
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith /* YOUR CODE HERE */
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith YUI().use('dd', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // Y.log statements here will be reported in the Console generated in the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // other YUI instance.
ac09af27b374780c2e388a3e0aa7c329c6b637f4Eric Ferraiuolo Look at the <a href="console-global.html">Creating a
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith universal Console</a> example for reference.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h3 id="display">Console display</h3>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4>Anatomy of the Console</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith The Console has a very simple display, split into a header, body, and
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<img src="{{componentAssets}}/images/console_anatomy.png" alt="visual demarcation of Console's header, body, and footer">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith The default placement of a Console is absolutely positioned in the top
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith right corner of the page. This can be configured with the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>style</code> attribute. The <a
ac09af27b374780c2e388a3e0aa7c329c6b637f4Eric Ferraiuolo href="console-basic.html">Creating a Console for
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith debugging</a> example illustrates how to accomplish this.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="anatomy">Anatomy of a message</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Incoming log messages are normalized to objects with the following
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Property</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Description</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>message</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>The message text</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>category</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>The category or log level of the message (e.g. "info", "warn", or "note")</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>source</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>The name of the source module</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>localTime</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>The time the message was received</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>elapsedTime</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>The time elapsed since the last message was received</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>totalTime</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>The time elapsed since the Console was instantiated</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith These message objects are eventually rendered into the Console body like
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<img src="{{componentAssets}}/images/message_anatomy.png" alt="visual demarcation of the various parts of a Console entry">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Log messages from the standard <code>logLevel</code> categories
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith "info", "warn", and "error" get special
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith visual treatment. Specifically, the category is omitted from the message
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith meta and "warn" and "error" messages include an icon
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith and specific coloring.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<img src="{{componentAssets}}/images/info_warn_error.png" alt="One of each info, warn, and error type messages">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h3 id="controls">Console interaction</h3>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="collapse">Collapsing, expanding, hiding and showing</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Collapse and expand the Console with the Collapse/Expand button in the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith header or by setting the <code>collapsed</code> attribute to
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>true</code> or calling the instance's <code>collapse()</code> and
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>expand()</code> methods.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<img src="{{componentAssets}}/images/collapsed.png" alt="A collapsed Console">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Calling the instance's <code>hide()</code> method will entirely remove the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith UI from the page. <code>show()</code> will cause it to reappear.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="pause">Pausing</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Pause the Console with either the checkbox in the Console footer or by
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith setting the <code>paused</code> attribute.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith When paused, messages will accumulate in the buffer, but will not be
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith displayed until the Console is unpaused.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="clear">Clearing and resetting</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Flush the body of messages by clicking the Clear button in the Console
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith footer or calling the instance's <code>clearConsole()</code> method.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Clearing the Console will also flush the buffered messages not yet
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Calling the instance's <code>reset()</code> method will clear the Console,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith flush the buffer, unpause, and reseed the Console's
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>startTime</code>.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h3 id="filter">Filtering Console messages</h3>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Log messages can typically be filtered in two ways: by category (or
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>logLevel</code>) and by source. Category filtering is only available
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith at the Console level, but source filtering can be accomplished at the YUI
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith config level or the Console level (via the <a
ac09af27b374780c2e388a3e0aa7c329c6b637f4Eric Ferraiuolo href="../console-filters/index.html">ConsoleFilters plugin</a>). Each approach below
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith has a varying degree of impact to your page's performance.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="debug_files">Using debug files</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith All YUI module files come in three flavors:
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <li><code><em>module</em>-min.js</code> (min version)</li>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <li><code><em>module</em>.js</code> (raw version)</li>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <li><code><em>module</em>-debug.js</code> (debug version)</li>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Of these, only the debug version includes <code>Y.log(..)</code>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith statements. Explicitly including <code><script></code> tags in your
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith source pointing to either the raw or min version of a module will
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith effectively filter out messages from that module. The combo service
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith supports combining any mixture of min, raw, and debug files as well.
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith<script src="http://yui.yahooapis.com/{{yuiVersion}}/build/yui/yui-min.js"></script>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<!-- Include debug messages from the node module -->
14ea8dcb06b6d844dd99b7e18cca99172bea0cfdLuke Smith<script src="http://yui.yahooapis.com/{{yuiVersion}}/build/node/node-debug.js"></script>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke SmithYUI().use('overlay', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // Overlay requires Node. Any other missing dependencies are automatically
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // loaded, excluding node-min.js since the node module is already provided
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // by the inline script tag.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith is has the least impact on page performance.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="yui_config">Choose which modules log</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith There are five YUI instance configurations that affect the logging
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith subsystem behavior:
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Property</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Example</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Role</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>debug</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>Y.config.debug = false;</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>If <code>false</code>, calls to <code>Y.log(..)</code> do nothing</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>filter</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>Y.config.filter = 'raw';</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Set to "raw" or "debug" to specify a default version of all included modules. Default value is "min"</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>filters</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><pre><code>Y.config.filters = {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smithevent: 'debug',
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith};</code></pre></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Like <code>filter</code> but can be used to specify file version on a per-module basis.</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>logInclude</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><pre><code>Y.config.logInclude = {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith};</code></pre></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Allow only log messages assigned to the specified sources to propagate. Note a single module may use multiple sources.</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>logExclude</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><pre><code>Y.config.logExclude = {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smithattribute: true
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith};</code></pre></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>Prevent log messages from the specified sources from propagating. Typically either <code>logInclude</code> or <code>logExclude</code> is configured, not both.</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// Setting debug to true is unnecessary, but is included for illustration.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// Setting filter to 'raw' facilitates stepping through module code during
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// debugging. Specifying 'debug' filters for slider and dd will result in all
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// log statements from those modules being included.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith debug: true,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith useBrowserConsole: false,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith filter: 'raw',
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith slider: 'debug',
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith}).use('slider', 'console', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// Request the debug version of all loaded files, but only allow log statements
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// from the sources 'node' and 'dom-screen'.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith useBrowserConsole: false,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith filter: 'debug',
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith logInclude: {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith "dom-screen": true
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith}).use('slider', 'console', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Specifying the <code>filters</code> config to include only debug versions
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith of the modules you want log messages from is effectively the same as the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith prior option, and has the same effect on page performance. Specifying a
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith "debug" filter and filtering sources via <code>logInclude</code>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith or <code>logExclude</code> has a greater impact because the calls to
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>Y.log(..)</code> are still present in all modules, even though they
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith will be ignored.
ac09af27b374780c2e388a3e0aa7c329c6b637f4Eric Ferraiuolo Look at the <a href="console-yui-config.html">YUI
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith configuration to filter log messages</a> example for reference.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="log_level"><code>logLevel</code></h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Most log statements in YUI 3 modules are "info" messages.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Changing the <code>logLevel</code> configuration for your Console instance
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith will limit the messages that display in the Console. Obviously, the debug
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith files must be used for this as well.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith useBrowserConsole: false,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith filter: 'debug' // use all debug files
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith}).use('overlay', 'console', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // Only allow 'warn' or 'error' messages to display
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith new Y.Console({ logLevel: 'warn' }).render();
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Console will actually default its <code>logLevel</code> attribute from the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith so named YUI configuration property if it is specified. Note that unlike
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith the attributes listed in the previous option, setting the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>logLevel</code> in the YUI config will not alter the behavior of the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith logging subsystem. The configuration is simply used as a default value for
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith instantiated Consoles.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// Include debug version of the dom module, but only broadcast log messages
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith// from the 'dom-screen' source that are warnings or errors.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith useBrowserConsole: false,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith filters: { dom: 'debug' },
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith logInclude: { 'dom-screen': true },
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith logLevel: 'warn' // this has no affect on Y.log statements
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith}).use('dd','console', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // With the YUI config above, these are now equivalent
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith var consoleA = new Y.Console();
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith var consoleB = new Y.Console({ logLevel: 'warn' });
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>logLevel</code> filtering, as with any filtering occurring at the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Console, has a greater impact on page performance, since all messages,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith regardless of their category, are being broadcast from the logging
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith subsystem to the Console before any preventative action is taken.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="entry">Preventing the Console's <code>entry</code> event</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Within Console, messages are transfered to the print loop buffer via an
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <code>entry</code> event. For fine grained control over which messages
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith reach the Console body, implementers can subscribe to the event and prevent
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith messages from being displayed by calling <code>preventDefault()</code> on
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smithvar yconsole = new Y.Console();
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smithyconsole.on('entry', function (e) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // the normalized message object is stored on the event in the 'message'
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith // property.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith if (/Frank/.test(e.message.message)) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith e.preventDefault(); // we don't talk about Frank here.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith The signature of the normalized message is <a href="#anatomy">noted
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith This approach affords the most flexibility, as you can filter by
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith arbitrarily complex criteria, and is the only option here not limited to
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith comparing the category or source.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith This flexibility comes at a cost, though. Because the subscriber code is
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith necessarily executed for every log message received, there is a greater
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith impact on page performance .
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h4 id="console-filters">ConsoleFilters plugin</h4>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<img src="{{componentAssets}}/images/console_filters.png" alt="Console with the ConsoleFilters UI added" style="float: right; margin-left: 2em;">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith For runtime display filtering by both category and source, the <a
ac09af27b374780c2e388a3e0aa7c329c6b637f4Eric Ferraiuolo href="../console-filters/index.html">ConsoleFilters plugin</a> can be added to the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke SmithYUI({..}).use('console-filters', function (Y) {
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith newestOnTop: false,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith }).render();
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith var yconsole = new Y.Console({..});
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<p style="clear: right;">
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith The ConsoleFilters plugin adds a set of checkboxes to the Console footer,
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith one for each category and source currently reported. Only those messages
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith that match one of the checked categories and sources will be displayed.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith Unlike any of the prior options, messages filtered from the display by the
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith ConsoleFilters plugin can be redisplayed by rechecking the corresponding
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith category or source checkbox.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith This approach has the greatest affect on page performance because in order
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith to support reassembling the Console contents in real time, all Console
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith messages are stored in memory and more conditional logic is inserted into
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith the path from log statement to Console display.
ac09af27b374780c2e388a3e0aa7c329c6b637f4Eric Ferraiuolo Look at the <a href="../console-filters/console-filters-intro.html">ConsoleFilters
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith plugin</a> example.
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith<h3 id="events">Console events</h3>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith In addition to the standard <code><em>attribute</em>Change</code> events
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith and others common to all Widgets, Console broadcasts the following
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Event</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>When</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <th>Payload</th>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>reset</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>In response to calls to an instance's <code>reset()</code> method. The default function for the event performs the reset detailed above.</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>none</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td><code>entry</code></td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>In response to messages being received from the <code>yui:log</code>. The default function for the event sends the normalized message object to the print loop buffer.</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith <td>{ message : (<a href="#anatomy">normalized message object</a>) }</td>
249e4018d7634fb9dc0c49976e034993f8fa065cLuke Smith This is not an exhaustive list. See the <a href="{{apiDocs}}/module_console.html">API docs</a> for a complete listing.