SemanSemantic-UItic-UI/server/documents/modules/tab.html.eco

---
layout      : 'default'
css         : ''
element     : 'tab'
elementType : 'module'

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

themes      : ['Default']
---

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

<%- @partial('header', { tabs: {  usage: 'Usage', examples: 'Examples', settings: 'Settings' } }) %>

<div class="main container">
  <!--
  <div class="ui tab" data-tab="definition">

    <div class="peek">
      <div class="ui vertical pointing secondary menu">
        <a class="active item">Types</a>
      </div>
    </div>

  </div>
  -->

  <div class="ui active tab" data-tab="usage">

    <h2 class="ui dividing header">Initializing Tabs</h2>

    <p>Tabs are usually used in concert with an element that activates the tab. Tabs are initialized on the activating item instead of the tab.</p>
    <p>If there are no menus that activate tab elements on the page, tabs can be initialized globally by using <code>$.tab()</code> and activated programmatically using <code>$.tab('change tab', path);</code></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>


    <h2 class="ui dividing header">Managing State</h2>

    <h4 class="ui header">...with Hash Tags</h4>

    <p>Hash tags use in page links and <code>onhashstatechange</code> to create history events for each tab. This is sometimes easier to use than the more advanced push state, because it does not require you to route those URLs on your server. All in page links will route to the same url.</p>

    <div class="code">
      $('.ui.menu .item')
        .tab({
          history: true,
          historyType: 'state'
        })
      ;
    </div>

    <h4 class="ui header">...with HTML5 State</h4>
    <p>Tabs can can use html5 push state to manage page state without using <code>#/foo</code> links. When a user refreshes a page using push state the server will be queried for the new url. This means you must set up appropriate routes in your backend to match each link.</p>
    <p>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="code">
    $('.ui.menu .item')
      .tab({
        history: true,
        historyType: 'state'
        path: '/modules/tab.html'
      })
    ;
    </div>

    <h4 class="ui header">Setting Paths</h4>
    <p>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 <b>base URL without any internal state</b>. This cannot be set automatically to <code>window.location</code> because refreshing the page will change  future page refreshes the URL may include an internal link. </p>

    <div class="ui warning message">Using the incorrect path will cause the module to work incorrectly, producing unexpected results.</div>

    <h2 class="ui dividing header">AJAX Content</h2>

    <h3 class="ui header">...with automatic routing</h3>

    <p>Specifying the setting <code>auto: true</code>, will automatically retrieve content at a remote url matching the url set in the browser.</p>
    <p>So for example the tab <code>inbox</code> will retrieve content from the URL <code>base-url/inbox/</code></p>
    <p>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, or a full page request.</p>
    <p>Queries with <code>'X-Remote': true</code> should refresh only the tabbed content, while queries without are normal resources and should refresh <b>the entire page contents</b></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>

    <h3 class="ui header">...with an API Behavior</h3>

    <p>Tabs provide an optional coupling with API which allow you to specify a templated API endpoint that a tab can query</p>
    <p>Tabs will automatically pass the url variable <code>{$tab}</code> which can be replaced for RESTful API links.</p>

    <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>
    </table>
  </div>

  <div class="ui tab" data-tab="examples">

    <div class="first example">

      <h4 class="ui header">Multi-level Tabs with Defaults</h4>
      <p>This example shows how default tabs are opened recursively for multiple tiers of tabs</p>
      <div class="ui info message">Each of these examples is initialized with a context to prevent contamination with other tab examples on this page. This is not necessary unless using multiple tab systems on a single page.</div>
      <div class="ignored code" data-type="javascript">
      $('.first.example .menu .item')
        .tab({
          context: '.first.example'
        })
      ;
      </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="history example">
      <h4>Example with hash page history</h4>
      <div class="code" data-type="javascript">
        $('.history.example .menu .item')
          .tab({
            context : '.history.example',
            history : true
          })
        ;
      </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>
      <div class="code">
      $('.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>


  </div>

  <div class="ui tab" data-tab="settings">

    <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>

</div>
</body>
</html>