---
layout      : 'default'
css         : 'rating'

element     : 'rating'
elementType : 'module'

title       : 'Rating'
description : 'A rating allows a user to indicate interest in content'
type        : 'UI Module'

themes      : ['Default']
---

<%- @partial('header', { tabs: 'module' }) %>

<link rel="stylesheet/less" type="text/css" href="/build/less/definitions/modules/rating.less" />
<script src="/javascript/rating.js"></script>

<div class="main container">

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

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

    <div class="example">
      <h4 class="ui header">Rating</h4>
      <p>A basic rating </p>
      <div class="ui rating" data-max-rating="1"></div>
    </div>

    <div class="example">
      <h4 class="ui header">Star</h4>
      <p>A rating can use a set of star icons</p>

      Rating
      <div class="ui star rating" data-rating="3"></div>
    </div>

    <div class="example">
      <h4 class="ui header">Heart</h4>
      <p>A rating can use a set of heart icons</p>
      <div class="ui heart rating" data-rating="7" data-max-rating="10"></div>
    </div>

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

    <div class="example">
      <h4 class="ui header">Size</h4>
      <p>A rating can vary in size</p>
      <div class="ui mini star rating"></div>
      <div class="ignored hidden ui divider"></div>
      <div class="ui tiny star rating"></div>
      <div class="ignored hidden ui divider"></div>
      <div class="ui small star rating"></div>
      <div class="ignored hidden ui divider"></div>
      <div class="ui star rating"></div>
      <div class="ignored hidden ui divider"></div>
      <div class="ui large star rating"></div>
      <div class="ignored hidden ui divider"></div>
      <div class="ui huge star rating"></div>
      <div class="ignored hidden ui divider"></div>
      <div class="ui massive star rating"></div>
    </div>
  </div>

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

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

    <div class="example">
      <h4 class="ui header">Setting existing values</h4>
      <p>The starting rating can be set either using metadata value <code>data-rating</code> or the setting <code>initialRating</code>.
      <p>The maximum rating can be be set using the metadata value <code>data-max-rating</code> or the settings <code>maxRating</code>, or you can just include the icon html yourself on initialization to avoid the overhead of the <code>DOM template insertions</code>. </p>
      <div class="ui ignored info message">If a metadata rating is specified it will automatically override the default value specified in javascript.</div>
      <div class="code" data-type="javascript">
      $('.toggle.example .rating')
        .rating({
          initialRating: 2,
          maxRating: 4
        })
      ;
      </div>
      <div class="ui very relaxed celled list">
        <div class="item">
          <img class="ui avatar image" src="/images/demo/avatar2.jpg">
          <div class="content">
            <div class="header">
              New York Dog Fair
              <div class="ui heart rating" data-rating="2"></div>
            </div>
            A fun day at the fair
          </div>
        </div>
        <div class="item">
          <img class="ui avatar image" src="/images/demo/avatar3.jpg">
          <div class="content">
            <div class="header">
              Dog Appreciation Day
              <div class="ui heart rating" data-rating="2"></div>
            </div>
            I'd like to tell your dog he's great
          </div>
        </div>
      </div>
    </div>

    <div class="toggle no example">
      <h4 class="ui header">Read-Only Ratings</h4>
      <p>You can disable or enable interactive rating</p>
      <div class="code" data-type="javascript" data-demo="true">
      $('.toggle.example .rating')
        .rating('disable')
      ;
      </div>
      <div class="code" data-type="javascript" data-demo="true">
      $('.toggle.example .rating')
        .rating('enable')
      ;
      </div>
      <div class="ui heart demo rating" data-rating="3">
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
      </div>
    </div>

    <div class="clearing no example">
      <h4 class="ui header">Clearing Ratings</h4>
      <p>When clearable is set to <code>true</code> you can clear the rating by clicking on the current start rating.</p>
      <div class="evaluated code" data-type="javascript">
      $('.clearing.example .rating')
        .rating('setting', 'clearable', true)
      ;
      </div>
      <div class="ui heart demo rating" data-rating="3">
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
      </div>
    </div>
  </div>

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

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

    <div class="ui example">
      <h4 class="ui header">Metadata</h4>
      <p>You can specify the starting rating, and max rating in metadata.
      <div class="code" data-type="javascript">
        $('.ui.rating')
          .rating()
        ;
      </div>
      <div class="code" data-type="html">
        <div class="ui rating" data-rating="3" data-max-rating="5"></div>
      </div>
    </div>

    <div class="example">
      <h4 class="ui header">Javascript</h4>
      <p>You can specify the rating values in javascript</p>
      <div class="code" data-type="javascript">
        $('.ui.rating')
          .rating({
            rating: 3,
            maxRating: 5
          })
        ;
      </div>
      <div class="code" data-type="html">
        <div class="ui rating"></div>
      </div>
    </div>

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

    <p>All the following <a href="/module.html#/behavior">behaviors</a> can be called using the syntax:</p>
    <div class="code">
    $('.ui.rating')
      .modal('behavior name', argumentOne, argumentTwo)
    ;
    </div>

    <table class="ui definition celled sortable table segment">
      <thead>
        <th>Behavior</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>set rating(rating)</td>
          <td>Sets rating programmatically</td>
        </tr>
        <tr>
          <td>get rating</td>
          <td>Gets current rating</td>
        </tr>
        <tr>
          <td>disable</td>
          <td>Disables interactive rating mode</td>
        </tr>
        <tr>
          <td>enable</td>
          <td>Enables interactive rating mode</td>
        </tr>
        <tr>
          <td>clear rating</td>
          <td>Clears current rating</td>
        </tr>
      </tbody>
    </table>
  </div>

  <div class="ui tab" data-tab="settings">
    <h3 class="ui header">
      Rating Settings
      <div class="sub header">Rating settings modify the rating's behavior</div>
    </h3>
    <table class="ui celled sortable definition table segment">
      <thead>
        <th>Setting</th>
        <th class="four wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>initialRating</td>
          <td>0</td>
          <td>A number representing the default rating to apply</td>
        </tr>
        <tr>
          <td>clearable</td>
          <td>auto</td>
          <td>By default a rating will be only clearable if there is 1 icon. Setting to true/false will allow or disallow a user to clear their rating</td>
        </tr>
        <tr>
          <td>interactive</td>
          <td>true</td>
          <td>Whether to enable user's ability to rate</td>
        </tr>
      </tbody>
    </table>

    <h3 class="ui header">
      Callbacks
      <div class="sub header">Callbacks specify a function to occur after a specific behavior.</div>
    </h3>
    <table class="ui celled sortable definition table segment">
      <thead>
        <th class="four wide">Setting</th>
        <th>Context</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>onRate(value)</td>
          <td>Rating</td>
          <td>Is called after user selects a new rating</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 sortable definition table segment">
      <thead>
        <th>Setting</th>
        <th class="four wide">Default</th>
        <th>Description</th>
      </thead>
      <tbody>
        <tr>
          <td>namespace</td>
          <td>rating</td>
          <td>Event namespace. Makes sure module teardown does not effect other events attached to an element.</td>
        </tr>
        <tr>
          <td>selector</td>
          <td colspan="2">
            <div class="code">
      selector  : {
        icon : '.icon'
      }
            </div>
          </td>
        </tr>
        <tr>
          <td>className</td>
          <td colspan="2">
            <div class="code">
      className : {
        active     : 'active',
        hover      : 'hover',
        loading    : 'loading'
      },
            </div>
          </td>
        </tr>
      </tbody>
    </table>


    <h3 class="ui header">
      Debug Settings
      <div class="sub header">Debug settings controls debug output to the console</div>
    </h3>
    <table class="ui 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>Rating</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>error</td>
          <td colspan="2">
            <div class="code">
      error   : {
        action    : 'You called a rating action that was not defined'
      }
            </div>
          </td>
        </tr>
      </tbody>
    </table>
  </div>

</div>