======TabView control======

{{page>:uwa_templates#available templates}}


=====Description=====

This control is intended for the creation of tabs, each with its distinct content.

<note tip>
Tabs should be the first piece of code implemented into your widget.

Implementing tabs into an existing widget requires a lot of effort and code rewriting, so plan tabs up-front if you don't want to feel like you are rewriting your widget from scratch.
</note>


=====Preview=====

{{uwa_templates:template-tabview.gif|}}

=====Code explanation====

The path to implementing tabs for your widget follows a few standard steps...
  - instantiate the UWA.Controls.TabView object ;
  - define each of your tab using the addTab() method ;
  - have your widget watch out for the 'activeTabChange' in order to trigger code at the right moment :

<note tip>
Tabs are merely DIV tags which are displayed or hidden depending on the user's selection. You should therefore plan ahead if your code fetches HTML elements in the DOM.
</note>

====The UWA.Controls.TabView object====

That object is essential to your tabs, and should be available in the whole scope of the code. Rather than storing it in a local variable, you should store it in the global object of the widget.

<code javascript>
var tabs = new UWA.Controls.TabView();
MyWidget.tabs = tabs;
</code>

====The addTab method====


The ''addTab'' method, defined by the TabView object, is where you define one tab. It takes two arguments: the first on is the id of the tab (or group of tabs), the second one is an object or array, used for defined or custom options.

Tabs must be added in the order you want them to appear.

<code javascript>
tabs.addTab('tabID', object);
</code>

''object'' can either be an objet defining the tab, or an array containing any number of secondary tabs, available through a built-in pull-down menu. 

<code javascript>
// one tab
tabs.addTab('firstTab', {text: 'Title for the first tab'} );

// three tabs
tabs.addTab('firstTab', {text: 'First tab'});
tabs.addTab('secondTab', {text: 'Second tab'});
tabs.addTab('thirdTab', {text: 'Third tab'});
</code>

If you need sub-tabs, note that they must be added in the order you want them to appear. The first defined tab will be the one to appear when the widget loads.

<code javascript>
// one tab with a secondary tab
tabs.addTab('tabGroup', [
  {id: 'secondTab', text: 'secondTabTitle'},
  {id: 'firstSubTab', text: 'firstSubTabTitle'}
  ]);
</code>

Each tab can use the following defined settings:

^  Info  ^  Usage  ^
|  id    |  Sets the JS id for the tab  |
|  text  |  Sets the title of the tab  |
|  icon  |  Sets an icon for the tab (12*12 PNG file)  |

You can also define any custom value, for later retrieval (see sample code). This is however seldomly implemented in normal use...

<code javascript>
tabs.addTab('firstTab', 
  {text: 'firstTabTitle', customValue: 'my custom value'} );
</code>


====The setContent method====

The ''setContent'' method, also defined by the TabView object, is used to fill-in your tab with content. It is the equivalent of el.setHTML for a normal HTML element.

It takes two arguments: the tab id, and the content (in the form of an HTML string).

<code javascript>
tabs.setContent('tabID', '<p>Hey there!</p>');

var contentForTheTab = '<p>Hey there!</p>';
tabs.setContent('tabID', contentForTheTab);
</code>

Because the content is made of HTML code, you can put just about anything in a tab: text, image, Flash, Google Map, etc...


=====Sample code=====

<code javascript>
var TabViewSample = {};

widget.onLoad = function() {
  var tabs = new UWA.Controls.TabView();
  TabViewSample.tabs = tabs;

  // Create tab items
  tabs.addTab("tab1", {text: "Tab One", customInfo: "custom"});
  tabs.addTab("tab2", {text: "Tab Two"});
  tabs.addTab("tab3", {text: "Tab Three"});

  // Put some content in tabs
  tabs.setContent("tab1", "<p>Tab one</p>");
  tabs.setContent("tab2", "<p>Tab two</p>");
  tabs.setContent("tab3", "<p>Tab three</p>");

  // Restore saved active tab
  var activeTab = widget.getValue("activeTab");
  if (activeTab) {
    tabs.selectTab(activeTab);
  }

  // Register to activeTabChange event
  tabs.observe('activeTabChange', TabViewSample.onActiveTabChanged);

  widget.setBody('');

  // Append tabview to widget body
  tabs.appendTo(widget.body);
}

TabViewSample.onActiveTabChanged = function(name, data) {
  var tabs = TabViewSample.tabs;

  var contentHtml = tabs.getTabContent(name).innerHTML;
  contentHtml += '<p>Tab name: '+name+',  event: activeTabChange</p>';
  if (data.customInfo) {
    contentHtml += '<p>customInfo has value: '+ data.customInfo+'</p>';
  }
  tabs.setContent(name, contentHtml);

  // Save active tab
  widget.setValue("activeTab", name);
}
</code>


====Sample widget====

See the [[http://eco.netvibes.com/widgets/203214|Rugby World Cup 2007]] widget.