#

Jump to Table of Contents

# TabView

The TabView widget is a UI control that enables the user switch between content panels.

## Getting Started

To include the source files for TabView and its dependencies, first load the YUI seed file if you haven't already loaded it.

    <script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the `YUI().use()` method. YUI will automatically load any dependencies required by the modules you specify.

    <script>
    // Create a new YUI instance and populate it with the required modules.
    YUI().use('tabview', function (Y) {
        // TabView is available and ready for use. Add implementation
        // code here.
    });
    </script>

For more information on creating YUI instances and on the `use()` method, see the documentation for the YUI Global Object.

## Anatomy of a TabView

### Minimum Markup Requirement

Note: be sure to add the `yui3-skin-sam` classname to the page's `<body>` element or to a parent element of the widget in order to apply the default CSS skin. See Understanding Skinning.

    <body class="yui3-skin-sam"> <!-- You need this skin class -->

A `TabView` consists of a list of links that target a content element.

The basic markup needed to create from HTML is the following:

    <div id="demo">
        <ul>
            <li><a href="#foo">foo</a></li>
            <li><a href="#bar">bar</a></li>
            <li><a href="#baz">baz</a></li>
        </ul>
        <div>
            <div id="foo">foo content</div>
            <div id="bar">bar content</div>
            <div id="baz">baz content</div>
        </div>
    </div>

### Rendered Markup

After a `TabView` is rendered, the final markup becomes:

    <div class="yui3-widget yui3-tabview">
        <div id="demo" class="yui3-tabview-content">
            <ul class="yui3-tabview-list">
                <li class="yui3-tab yui3-widget yui3-tab-selected">
                    <a href="#foo" class="yui3-tab-label yui3-tab-content">foo</a>
                </li>
                <li class="yui3-tab yui3-widget">
                    <a href="#bar" class="yui3-tab-label yui3-tab-content">bar</a>
                </li>
                <li class="yui3-tab yui3-widget">
                    <a href="#baz" class="yui3-tab-label yui3-tab-content">baz</a>
                </li>
            </ul>
            <div class="yui3-tabview-panel">
                <div id="foo" class="yui3-tab-panel">foo content</div>
                <div id="bar" class="yui3-tab-panel">bar content</div>
                <div id="baz" class="yui3-tab-panel">baz content</div>
            </div>
        </div>
    </div>

## Creating and Configuring a TabView

A `TabView` instance can be created from existing markup on the page, or dynamically using JavaScript.

### From Existing Markup

To create from existing markup, first conform to the basic markup pattern, then create a new `TabView` instance, pointing to the existing `srcNode`, and render.

    <div id="demo">
        <ul>
            <li><a href="#foo">foo</a></li>
            <li><a href="#bar">bar</a></li>
            <li><a href="#baz">baz</a></li>
        </ul>
        <div>
            <div id="foo">foo content</div>
            <div id="bar">bar content</div>
            <div id="baz">baz content</div>
        </div>
    </div>

    <script>
    YUI().use('tabview', function(Y) {
        var tabview = new Y.TabView({
            srcNode: '#demo'
        });

        tabview.render();
    });
    </script>

### From JavaScript

To create purely from JavaScript, all that is required is passing the `TabView` constructor a list of `children` containing their respective `label` and attributes, and call render. As with all YUI `Widget`s, render takes an optional container to render into, or defaults to the `body` element.

    <div id="demo"></div>
    <script>
    YUI().use('tabview', function(Y) {
        var tabview = new Y.TabView({
            children: [{
                label: 'foo',
                content: '<p>foo content</p>'
            }, {
                label: 'bar',
                content: '<p>bar content</p>'
            }, {
                label: 'baz',
                content: '<p>baz content</p>'
            }]
        });

        tabview.render('#demo');
    });
    </script>

## Skinning TabView

The `TabView` comes with a basic skin by default. This can be easily customized using the rich set of classNames.

For a more polished look and feel, we also ship with the "sam skin", which can be applied by adding the `yui3-skin-sam` className to some ancestor:

    <body class="yui3-skin-sam">
    ...
    <div id="demo">
        <ul>
            <li><a href="#foo">foo</a></li>
            <li><a href="#bar">bar</a></li>
            <li><a href="#baz">baz</a></li>
        </ul>
        <div>
            <div id="foo">foo content</div>
            <div id="bar">bar content</div>
            <div id="baz">baz content</div>
        </div>
    </div>
    ...
    </body>

## TabView Events

TabViews fire the following events during operation:

Event | When | Payload
--- | --- | ---
`addChild` | a Tab is added to the TabView | `child, index`
`removeChild` | a Tab is removed from the TabView | `child, index`
`selectionChange` | the selected tab changes | `prevVal, newVal`
`render` | a Tabview is rendered | Normal change event signature (`newVal`, `prevVal`, etc). When dragging, extra event property `ddEvent : (drag:drag event)` is added

This is not an exhaustive list. See the API docs for a complete listing.