tab.html.eco

---
layout      : 'default'
css         : 'side'

title       : 'Tab'
description : 'A tab is a section of content tied to a navigation menu'
type        : 'UI Module'
---

<script src="/javascript/tab.js"></script>

<%- @partial('header') %>

<div class="main container">

  <div class="peek">
    <div class="ui vertical pointing secondary menu">
      <a class="item">Examples</a>
      <a class="item">Coupling</a>
      <a class="item">Behavior</a>
      <a class="item">Settings</a>
    </div>
  </div>

  <h2 class="ui dividing header">Examples</h2>

  <div class="first no example">

    <h4 class="ui header">Opening tabs with menus</h4>
    <p>Tabs are usually used in concert with an element that activates the tab. When using tabs, unlike other UI components, the menu or activating element is initialized instead of the tab.</p>
    <p>Tabs are connected to their activators with a metadata attribute <code>data-tab</code>. This should be added to both the activating element and the tab itself.</p>

    <div class="ignored ui info message">
      <h4 class="ui header">Default tabs</h4>
      <p>After any tab is opened it will look for a default tab to open inside of the current tab. This is the first tab that begins with the same stem url as the parent tab. For example a tab with the path <code>data-tab="home"</code> might open a tab automatically <code>data-tab="/home/inbox"</code>.</p>
      <p>This will happen recursively for every tab open, allowing as many levels of tabs as you like</p>
    </div>

    <div class="code" data-type="javascript">
    $('.first.example .menu .item')
      .tab({
        context: '.first.example'
      })
    ;
    </div>

    <div class="code" data-type="html" data-label="true">
    <div class="ui pointing secondary menu">
      <a class="active item" data-tab="first">First</a>
      <a class="item" data-tab="second">Second</a>
      <a class="item" data-tab="third">Third</a>
    </div>
    <div class="ui active tab segment" data-tab="first">
      <div class="ui top attached tabular menu">
        <a class="active item" data-tab="first/a">1A</a>
        <a class="item" data-tab="first/b">1B</a>
        <a class="item" data-tab="first/c">1C</a>
      </div>
      <div class="ui bottom attached active tab segment" data-tab="first/a">1A</div>
      <div class="ui bottom attached tab segment" data-tab="first/b">1B</div>
      <div class="ui bottom attached tab segment" data-tab="first/c">1C</div>
    </div>
    <div class="ui tab segment" data-tab="second">...</div>
    <div class="ui tab segment" data-tab="third">...</div>
    </div>

    <div class="ui pointing secondary menu">
      <a class="active item" data-tab="first">First</a>
      <a class="item" data-tab="second">Second</a>
      <a class="item" data-tab="third">Third</a>
    </div>
    <div class="ui active tab segment" data-tab="first">
      <div class="ui top attached tabular menu">
        <a class="active item" data-tab="first/a">1A</a>
        <a class="item" data-tab="first/b">1B</a>
        <a class="item" data-tab="first/c">1C</a>
      </div>
      <div class="ui bottom attached active tab segment" data-tab="first/a">1A</div>
      <div class="ui bottom attached tab segment" data-tab="first/b">1B</div>
      <div class="ui bottom attached tab segment" data-tab="first/c">1C</div>
    </div>
    <div class="ui tab segment" data-tab="second">
      <div class="ui top attached tabular menu">
        <a class="item" data-tab="second/a">2A</a>
        <a class="item" data-tab="second/b">2B</a>
        <a class="item" data-tab="second/c">2C</a>
      </div>
      <div class="ui bottom attached tab segment" data-tab="second/a">2A</div>
      <div class="ui bottom attached tab segment" data-tab="second/b">2B</div>
      <div class="ui bottom attached tab segment" data-tab="second/c">2C</div>
    </div>
    <div class="ui tab segment" data-tab="third">
      <div class="ui top attached tabular menu">
        <a class="item" data-tab="third/a">3A</a>
        <a class="item" data-tab="third/b">3B</a>
        <a class="item" data-tab="third/c">3C</a>
      </div>
      <div class="ui bottom attached tab segment" data-tab="third/a">3A</div>
      <div class="ui bottom attached tab segment" data-tab="third/b">3B</div>
      <div class="ui bottom attached tab segment" data-tab="third/c">3C</div>
    </div>
  </div>

  <h2 class="ui dividing header">Optional Coupling</h2>

  <div class="history no example">
    <h4 class="ui header">Managing History with Tabs</h4>
    <p>Tabs can attach to a history change event to allow for tabs to maintain history events. Tabs use Asual's <a href="https://github.com/asual/jquery-address">Address library</a> to provide cross-browser push state support. This makes sure in browser that don't support push state, <code>hashchange</code> is used with in page anchors to provide history functionality.</p>
    <div class="ignored ui warning message">
      <h4 class="header">Setup Paths</h4>
      Make sure when you use history to specify the path. This is required for determining the stem url from the part of the url maintaining in page history. The path is the URL without any tabs open. This cannot usually be set automatically because on future page refreshes the URL may include an internal link. Using the incorrect path will cause the module to work incorrectly, producing unexpected results.
    </div>
    <div class="ignored ui red message">
      <h4 class="header">Route your URLs</h4>
      Be sure to set up routes on your server for any url used with history. If you use history to change the url to a location that does not exist, it will 404 on the next refresh. The docs for example, are static github hosted pages, so will 404 if the page url changes
    </div>
    <div class="code" data-type="javascript">
      $('.history.example .menu .item')
        .tab({
          context : '.history.example',
          history : true,
          path    : '/modules/tab.html'
        })
      ;
    </div>
    <div class="ui pointing secondary menu">
      <a class="active item" data-tab="first">First</a>
      <a class="item" data-tab="second">Second</a>
      <a class="item" data-tab="third">Third</a>
    </div>
    <div class="ui active tab segment" data-tab="first">
      <div class="ui top attached tabular menu">
        <a class="active item" data-tab="first/a">1A</a>
        <a class="item" data-tab="first/b">1B</a>
        <a class="item" data-tab="first/c">1C</a>
      </div>
      <div class="ui bottom attached active tab segment" data-tab="first/a">1A</div>
      <div class="ui bottom attached tab segment" data-tab="first/b">1B</div>
      <div class="ui bottom attached tab segment" data-tab="first/c">1C</div>
    </div>
    <div class="ui tab segment" data-tab="second">
      <div class="ui top attached tabular menu">
        <a class="item" data-tab="second/a">2A</a>
        <a class="item" data-tab="second/b">2B</a>
        <a class="item" data-tab="second/c">2C</a>
      </div>
      <div class="ui bottom attached tab segment" data-tab="second/a">2A</div>
      <div class="ui bottom attached tab segment" data-tab="second/b">2B</div>
      <div class="ui bottom attached tab segment" data-tab="second/c">2C</div>
    </div>
    <div class="ui tab segment" data-tab="third">
      <div class="ui top attached tabular menu">
        <a class="item" data-tab="third/a">3A</a>
        <a class="item" data-tab="third/b">3B</a>
        <a class="item" data-tab="third/c">3C</a>
      </div>
      <div class="ui bottom attached tab segment" data-tab="third/a">3A</div>
      <div class="ui bottom attached tab segment" data-tab="third/b">3B</div>
      <div class="ui bottom attached tab segment" data-tab="third/c">3C</div>
    </div>
  </div>

  <div class="dynamic no example">
    <h4 class="header">Retreiving Dynamic Tab Content</h4>
    <p>The easiest way to setup dynamic content is to use the parameter <code>auto</code>, this will automatically retrieve content at a remote url matching the url set in the browser. The URL will receive an addition HTTP Header <code>'X-Remote': true</code>. You can use this on your server's back-end to determine whether a request is an AJAX request from a tab</p>
    <p>This uses a similar technique to <a href="https://github.com/defunkt/jquery-pjax">pJax</a> or Rail's <a href="https://github.com/rails/turbolinks/">turbolinks</a>.</p>

    <div class="ignored ui info message">There are a variety of settings for configuring dynamic content behavior. Visit the tab settings section for more information</div>

    <div class="code" data-type="javascript">
    $('.dynamic.example .menu .item')
      .tab({
        context : '.dynamic.example',
        auto    : true,
        path    : '/modules/tab.html'
      })
    ;
    </div>
    <div class="ui pointing secondary menu">
      <a class="active item" data-tab="first">First</a>
      <a class="item" data-tab="second">Second</a>
      <a class="item" data-tab="third">Third</a>
    </div>
    <div class="ui active tab segment" data-tab="first">
      <div class="ui top attached tabular menu">
        <a class="active item" data-tab="first/a">1A</a>
        <a class="item" data-tab="first/b">1B</a>
        <a class="item" data-tab="first/c">1C</a>
      </div>
      <div class="ui bottom attached active tab segment" data-tab="first/a"></div>
      <div class="ui bottom attached tab segment" data-tab="first/b"></div>
      <div class="ui bottom attached tab segment" data-tab="first/c"></div>
    </div>
    <div class="ui tab segment" data-tab="second">
      <div class="ui top attached tabular menu">
        <a class="item" data-tab="second/a">2A</a>
        <a class="item" data-tab="second/b">2B</a>
        <a class="item" data-tab="second/c">2C</a>
      </div>
      <div class="ui bottom attached tab segment" data-tab="second/a"></div>
      <div class="ui bottom attached tab segment" data-tab="second/b"></div>
      <div class="ui bottom attached tab segment" data-tab="second/c"></div>
    </div>
    <div class="ui tab segment" data-tab="third">
      <div class="ui top attached tabular menu">
        <a class="item" data-tab="third/a">3A</a>
        <a class="item" data-tab="third/b">3B</a>
        <a class="item" data-tab="third/c">3C</a>
      </div>
      <div class="ui bottom attached tab segment" data-tab="third/a"></div>
      <div class="ui bottom attached tab segment" data-tab="third/b"></div>
      <div class="ui bottom attached tab segment" data-tab="third/c"></div>
    </div>
  </div>

  <h2 class="ui dividing header">Behavior</h2>

  All the following <a href="/module.html#/behavior">behaviors</a> can be called using the syntax <code>$('.foo').tab('behavior name', argumentOne, argumentTwo)</code>

  <table class="ui definition celled table segment">
    <tr>
      <td>attach events(selector, event)</td>
      <td>Attaches tab action to given selector. Default event if none specified is toggle</td>
    </tr>
    <tr>
      <td>show</td>
      <td>Shows tab</td>
    </tr>
    <tr>
      <td>hide</td>
      <td>Hides tab</td>
    </tr>
    <tr>
      <td>toggle</td>
      <td>Toggles visibility of tab</td>
    </tr>
    <tr>
      <td>is open</td>
      <td>Returns whether tab is open</td>
    </tr>
    <tr>
      <td>is closed</td>
      <td>Returns whether tab is closed</td>
    </tr>
    <tr>
      <td>push page</td>
      <td>Pushes page content to be visible alongside tab</td>
    </tr>
    <tr>
      <td>get direction</td>
      <td>Returns direction of current tab</td>
    </tr>
    <tr>
      <td>pull page</td>
      <td>Returns page content to original position</td>
    </tr>
    <tr>
      <td>add body css</td>
      <td>Adds stylesheet to page head to trigger tab animations</td>
    </tr>
    <tr>
      <td>remove body css</td>
      <td>Removes any inline stylesheets for tab animation</td>
    </tr>
    <tr>
      <td>get transition event</td>
      <td>Returns vendor prefixed transition end event</td>
    </tr>
  </table>

  <h2 class="ui dividing header">Settings</h2>

  <h3 class="ui header">
    Transition Settings
    <div class="sub header">Form settings modify the transition behavior</div>
  </h3>
  <table class="ui red celled sortable definition table segment">
    <thead>
      <th>Setting</th>
      <th class="four wide">Default</th>
      <th>Description</th>
    </thead>
    <tbody>
      <tr>
        <td>overlay</td>
        <td>false</td>
        <td>Whether tab should overlay page instead of pushing page to the side</td>
      </tr>
      <tr>
        <td>useCSS</td>
        <td>true</td>
        <td>Whether to use css animations or fallback javascript animations</td>
      </tr>
      <tr>
        <td>duration</td>
        <td>300</td>
        <td>Duration of side bar animation</td>
      </tr>
    </tbody>
  </table>

  <h3 class="ui header">
    DOM Settings
    <div class="sub header">DOM settings specify how this module should interface with the DOM</div>
  </h3>
  <table class="ui celled purple definition table segment">
    <thead>
      <th>Setting</th>
      <th class="six wide">Default</th>
      <th>Description</th>
    </thead>
    <tbody>
      <tr>
        <td>namespace</td>
        <td>tab</td>
        <td>Event namespace. Makes sure module teardown does not effect other events attached to an element.</td>
      </tr>
      <tr>
        <td>className</td>
        <td>
          <div class="code">
    className: {
      active : 'active',
      pushed : 'pushed',
      top    : 'top',
      left   : 'left',
      right  : 'right',
      bottom : 'bottom'
    }
          </div>
        </td>
        <td>Class names used to attach style to state</td>
      </tr>
    </tbody>
  </table>

  <div class="ui horizontal divider"><i class="icon setting"></i></div>

  <h3 class="ui header">
    Debug Settings
    <div class="sub header">Debug settings controls debug output to the console</div>
  </h3>

  <table class="ui blue celled sortable definition table segment">
    <thead>
      <th>Setting</th>
      <th class="four wide">Default</th>
      <th>Description</th>
    </thead>
    <tbody>
      <tr>
        <td>name</td>
        <td>Tab</td>
        <td>Name used in debug logs</td>
      </tr>
      <tr>
        <td>debug</td>
        <td>True</td>
        <td>Provides standard debug output to console</td>
      </tr>
      <tr>
        <td>performance</td>
        <td>True</td>
        <td>Provides standard debug output to console</td>
      </tr>
      <tr>
        <td>verbose</td>
        <td>True</td>
        <td>Provides ancillary debug output to console</td>
      </tr>
      <tr>
        <td>errors</td>
        <td colspan="2">
          <div class="code">
    error   : {
      method   : 'The method you called is not defined.',
      notFound : 'There were no elements that matched the specified selector'
    }
          </div>
        </td>
      </tr>
    </tbody>
  </table>

</div>