YUI 3: Console Filters Plugin [beta]
The Console Filters plugin provides controls for visually filtering Console messages by category and source. The plugin creates two sets of checkboxes in the Console footer, one for known categories, the other for known sources. Only messages matching a checked category and source will be displayed.
More Information
- Examples: Console Filters Node Plugin in action.
- API Documentation: View the full API documentation for the Console Filters Node Plugin.
- Download: Console Filters Node Plugin as part of the full YUI Library.
- Free Hosting on our fast edge servers with combo-loading.
- License: BSD.
Getting Started
Include Dependencies
The easiest way to include the source files for Plugin.ConsoleFilters and its dependencies is to add the YUI seed file to your page, using the following script tag, and allow the YUI instance to download any additional files which may be required:
The YUI instance will automatically pull down Plugin.ConsoleFilters's source files and any missing dependencies when the console-filters module is used. This helps you avoid having to manually manage the list of files needed on your page to support multiple components while also optimizing your initial page weight by loading files only when they are required.
If you do want to include file dependencies manually on your page, the YUI Dependency Configurator can be used to determine the list of files you need to include in order to use Plugin.ConsoleFilters.
The YUI Instance
Once you have the YUI seed file on your page (yui-min.js), you can
create a new YUI instance for your application to use and populate it
with the modules you need, specified as the first set of arguments to the
use method:
The last argument passed to use is a callback function. The callback function will be invoked as soon as the YUI instance is done downloading any required files missing from your page. Once those files are loaded, your local YUI instance will be supplemented with the classes which make up the console-filters module and any modules it depends on. A reference to the populated YUI instance (Y) is passed back to your callback function. Within your callback, then, you can start writing your application code based on your own custom instance of YUI.
For more information on creating instances of YUI and the
use method, see the
YUI Global object documentation.
Trigger the CSS skin
For the default "Sam" skin to apply to the Console UI, you'll need to apply the yui-skin-sam class name to an element that is a parent of the element in which the Console lives. You can usually accomplish this simply by putting the class on the <body> tag:
For more information on skinning YUI components and making use of default skins, see our Understanding YUI Skins article.
Using the Console Filters Node Plugin
The Console Filters plugin adds a set of controls to the Console footer to allow interactive control of which log messages are displayed. It differs from other means of Console filtering by supporting display-only filtering. Messages that are filtered from view are not destroyed, and can be shown again by changing the filters.
Adding and configuring Plugin.ConsoleFilters
The Console Filters plugin has no required configuration or markup. All you need to do is plug it into your Console instance and the additional functionality will be available.
Configuration
ConsoleFilters manages a category attribute for known categories and a source attribute for known sources. The value of these attributes is an object literal with an entry for each category or source, respectively, mapping to a boolean indicating whether or not to display associated messages.
These attributes will be updated whenever a message with an unknown category or source is received by the Console. When a new category or source is received, its initial visibility is set according to the value of the defaultVisibility attribute.
The ConsoleFilters UI
The Console Filters plugin adds two groups of checkboxes to the Console footer. The upper set is for known categories; the lower for known sources.
As new categories or sources are received by the Console, corresponding checkboxes are added to the respective group. You can see this in the Using the ConsoleFilters plugin example.
Interacting with the Console Filters plugin
Checking and unchecking the filter checkboxes will cause the Console body to repopulate with only those messages that match both a checked category and a checked source.
Typically, interaction with the Console Filters plugin occurs via the UI. However, it does provide an API under the filter namespace on your Console instance. Through this API you can get or set any of the attributes noted above or use the following convenience methods:
hideCategory(cat1, cat2, ...catN)showCategory(cat1, cat2, ...catN)hideSource(src1, src2, ...srcN)showSource(src1, src2, ...srcN)
Updating the attributes via set or any of the hide or show methods will check or uncheck the corresponding checkbox in the UI.
Events
The Console Filters plugin does not emit any events other than the corresponding change events for its attributes.
categoryChangesourceChangedefaultVisibilityChange
Support & Community
Forums & Blog
YUI 3 discussion forums are hosted on YUILibrary.com.
In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.
Filing Bugs & Feature Requests
The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.
