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

title       : 'Rating'
description : 'A rating lets a user assess and view the desirability of content'
type        : 'UI Module'
---

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

<div class="main container">

  <div class="peek">
    <div class="ui vertical pointing secondary menu">
      <a class="active item">Usage</a>
      <a class="item">Types</a>
      <a class="item">Examples</a>
      <a class="item">Variations</a>
      <a class="item">Behavior</a>
      <a class="item">Settings</a>
    </div>
  </div>

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

  <h3 class="ui header">Initializing a rating</h3>
  <p>To change the range of your rating, simply adjust the number of icons in the initialized html</p>
  <div class="ui warning message">
    To use any variations besides the basic rating <a href="/elements/icon.html">ui icons</a> must be included to provide the additional icons required.
  </div>
  <div class="evaluated code" data-type="javascript">
    $('.ui.rating')
      .rating()
    ;
  </div>
  <div class="code" data-type="html">
    <div class="ui rating">
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
    </div>
  </div>


  <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">
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
    </div>
  </div>

  <div class="example">
    <h4 class="ui header">Star</h4>
    <p>A rating can use a set of star icons</p>
    <div class="ui info message">Star and heart rating types require the inclusion of semantic <a href="/elements/icon.html">ui icons</a></div>
    <div class="ui star rating">
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
    </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">
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
      <i class="icon"></i>
    </div>
  </div>
  <h2 class="ui dividing header">Examples</h2>

  <div class="example">
    <h4 class="ui header">Setting existing values</h4>
    <p>Starting ratings can be set either using metadata values or the setting <code>initialRating</code>.</p>
    <div class="ui ignored info message">If a metadata rating is specified it will automatically override any initial rating. This way you can set a default value but also allow it to be overridden.</div>
    <div class="ui divided list">
      <div class="item">
        <img src="/images/demo/avatar2.jpg">
        <div class="ui heart rating" data-rating="5">
          <i class="icon"></i>
          <i class="icon"></i>
          <i class="icon"></i>
          <i class="icon"></i>
          <i class="icon"></i>
        </div>
        <div class="content">
          <div class="header">New York Dog Fair</div>
          A fun day at the fair
        </div>
      </div>
      <div class="item">
        <img src="/images/demo/avatar3.jpg">
        <div class="ui heart rating" data-rating="2">
          <i class="icon"></i>
          <i class="icon"></i>
          <i class="icon"></i>
          <i class="icon"></i>
          <i class="icon"></i>
        </div>
        <div class="content">
          <div class="header">Dog Appreciation Day</div>
          I night 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>

  <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="another example">
      <div class="ui small star rating">
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
      </div>
    </div>
    <div class="another example">
      <div class="ui star rating">
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
      </div>
    </div>
    <div class="another example">
      <div class="ui large star rating">
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
      </div>
    </div>
    <div class="another example">
      <div class="ui huge star rating">
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
        <i class="icon"></i>
      </div>
    </div>
  </div>

  <h2 class="ui dividing header">Behavior</h2>
  <div class="no example">
    <h4 class="ui header">Set Rating</h4>
    <p>A rating can be set programatically</p>
    <div class="ignore code">
    $('.ui.rating')
      .rating('set rating', 3)
    ;
    </div>
  </div>

  <div class="no example">
    <h4 class="ui header">Get Rating</h4>
    <p>A rating can be retrieved</p>
    <div class="ignore code">
    $('.ui.rating')
      .rating('set rating', 3)
    ;
    </div>
  </div>

  <div class="no example">
    <h4 class="ui header">Enable</h4>
    <p>Enables interactive rating</p>
    <div class="ignore code">
    $('.ui.rating')
      .rating('enable')
    ;
    </div>
  </div>

  <div class="no example">
    <h4 class="ui header">Disable</h4>
    <p>Disables interactive rating</p>
    <div class="ignore code">
    $('.ui.rating')
      .rating('disable')
    ;
    </div>
  </div>


  <div class="no example">
    <h4 class="ui header">Clear Rating</h4>
    <p>A rating can be cleared</p>
    <div class="ignore code">
    $('.ui.rating')
      .rating('clear rating')
    ;
    </div>
  </div>

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

  <div class="no example">

  <h4 class="ui header">Rating Settings</h4>
  <p>Rating settings modify the rating's behavior</p>
  <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>false</td>
        <td>If enabled clicking on the current star rating will clear the rating</td>
      </tr>
      <tr>
        <td>interactive</td>
        <td>true</td>
        <td>Whether to enable user's ability to rate</td>
      </tr>
    </tbody>
  </table>

  <div class="ui horizontal section icon divider"><i class="icon setting"></i></div>
  <h4 class="ui header">Callbacks</h4>
  <p>Callback settings specify a function to occur after a specific behavior.</p>

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

  </div>

  <div class="no example">

  <h4 class="ui header">DOM Settings</h4>
  <p>DOM settings specify how this module should interface with the DOM</p>
  <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>

  </div>

  <div class="no example">

  <h4 class="ui header">Debug Settings</h4>
  <p>Debug settings controls debug output to the console</p>
  <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>
</body>

</html>