fuelux/_includes/js/spinbox.html

<!-- spinbox
================================================== -->
<div class="fu-docs-section">
  <h1 id="spinbox" class="page-header">Spinbox <a href="{{ site.repo }}/blob/{{ site.current_version }}/js/spinbox.js"><small>spinbox.js</small></a></h1>

  <p>Spinbox includes an enhanced numeric input based upon the native <code>&lt;input type=&quot;number&quot;&gt;</code>.</p>

  <div class="form-group">
    <label class="control-label" for="spinboxIllustration">spinbox</label>
    <div class="form-group">

      <div id="spinboxIllustration" class="spinbox digits-3" data-initialize="spinbox">
        <input id="overviewSpinboxInput" type="text" value="3" class="form-control input-mini spinbox-input">

        <div class="spinbox-buttons btn-group btn-group-vertical">
          <button type="button" class="btn btn-default spinbox-up btn-xs">
            <span class="glyphicon glyphicon-chevron-up"></span><span class="sr-only">Increase</span>
          </button>
          <button type="button" class="btn btn-default spinbox-down btn-xs">
            <span class="glyphicon glyphicon-chevron-down"></span><span class="sr-only">Decrease</span>
          </button>
        </div>
      </div>

    </div>
  </div>

  <h2 id="spinbox-usage">Usage</h2>
  <p>A spinbox allows for click interaction with a numeric input.</p>

  <p class="bg-danger">Currently there is a bug causing <code>changed</code> events to fire twice for some elements. The workaround is to disable this data-api, using <code>$.off('fu.data-api')</code></p>

  <h3 id="spinbox-usage-javascript">Via JavaScript</h3>
  <p>Call the selectlist control via JavaScript:</p>
  {% highlight js %}$('#mySpinbox').spinbox();{% endhighlight %}

  <h3 id="spinbox-usage-data-attributes">Via data-attributes</h3>
  <p>To enable the spinbox control without writing JavaScript, add <code>data-initialize="spinbox"</code> to the <code>.spinbox</code> element that you wish to initialize. Such elements that exist when <code>$.ready()</code> executes will be initialized. Any spinbox markup that is programmatically created with <code>data-initialize="spinbox"</code> sometime after the initial page load will not immediately initialize. Rather, it will initialize when the <code>mousedown</code> event is fired on it.</p>

  <h3 id="spinbox-usage-markup">Markup</h3>

  <p>Add <code>class="spinbox"</code> to a div within a <code>class="fuelux"</code> container.</p>

{% highlight html %}
<div class="spinbox" data-initialize="spinbox" id="mySpinbox">
  <input type="text" class="form-control input-mini spinbox-input">
  <div class="spinbox-buttons btn-group btn-group-vertical">
    <button type="button" class="btn btn-default spinbox-up btn-xs">
      <span class="glyphicon glyphicon-chevron-up"></span><span class="sr-only">Increase</span>
    </button>
    <button type="button" class="btn btn-default spinbox-down btn-xs">
      <span class="glyphicon glyphicon-chevron-down"></span><span class="sr-only">Decrease</span>
    </button>
  </div>
</div>
{% endhighlight %}

  <h3 id="spinbox-usage-methods">Methods</h3>
  <dl>
    <dt id="spinbox-usage-methods-destroy">.spinbox('destroy')</dt>
    <dd>Removes all functionality, jQuery data, and the markup from the DOM. Returns string of control markup.
    {% highlight js %}$('#mySpinbox').spinbox('destroy');{% endhighlight %}</dd>

    <dt id="spinbox-usage-methods-getintvalue">.spinbox('getIntValue')</dt>
    <dd>
      Returns spinner value as a JS number (so, if spinner is set to <code>"12,1px"</code> it will return <code>12.1</code>)
    </dd>

    <dt id="spinbox-usage-methods-getvalue">.spinbox('getValue')</dt>
    <dd>
      Alias for <a href="#spinbox-usage-methods-value">.spinbox('value')</a>
    </dd>

    <dt id="spinbox-usage-methods-setvalue">.spinbox('setValue')</dt>
    <dd>
      Alias for <a href="#spinbox-usage-methods-value">.spinbox('value', number)</a>
    </dd>

    <dt id="spinbox-usage-methods-value">.spinbox('value')</dt>
    <dd>
      Sets or returns the spinner value
      {% highlight js %}$('#mySpinbox').spinbox('value') {% endhighlight %}
      {% highlight js %}$('#mySpinbox').spinbox('value', 11) {% endhighlight %}
      <p>If value contains non-integers, the value returns as a string. Otherwise, the value returns as a number.</p>
    </dd>
  </dl>

  <h3 id="spinbox-usage-options">Options</h3>
  <p>Options that can be passed in via JavaScript once at initialization.</p>
  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
        <tr>
          <th style="width: 100px;">Name</th>
          <th style="width: 100px;">type</th>
          <th style="width: 50px;">default</th>
          <th>description</th>
        </tr>
        </thead>
        <tbody>
        <tr>
          <td>value</td>
          <td>number</td>
          <td>1</td>
          <td>Sets the initial spinbox value</td>
        </tr>
        <tr>
          <td>min</td>
          <td>number</td>
          <td>1</td>
          <td>Sets the minimum spinbox value</td>
        </tr>
        <tr>
          <td>max</td>
          <td>number</td>
          <td>999</td>
          <td>Sets the maximum spinbox value</td>
        </tr>
        <tr>
          <td>step</td>
          <td>number</td>
          <td>1</td>
          <td>Sets the increment by which the value in the spinbox will change each time the spinbox buttons are pressed</td>
        </tr>
        <tr>
          <td>limitToStep</td>
          <td>boolean</td>
          <td>false</td>
          <td>Limits the spinner value to increments of the step value. Eg. If <code>step</code> is <code>5</code>, spinner values will be limited to increments of 5, (<code>0, 5, 10, 15...</code>)</td>
        </tr>
        <tr>
          <td>hold</td>
          <td>boolean</td>
          <td>true</td>
          <td>If <code>true</code>, the spinbox will react to its buttons being pressed and held down</td>
        </tr>
        <tr>
          <td>hold</td>
          <td>boolean</td>
          <td>true</td>
          <td>If <code>true</code>, the spinbox will react to its buttons being pressed and held down</td>
        </tr>
        <tr>
          <td>speed</td>
          <td>string</td>
          <td>"medium"</td>
          <td>Assigns spinbox speed when buttons are held down. Options include <code>"fast","medium","slow".</code></td>
        </tr>
        <tr>
          <td>disabled</td>
          <td>boolean</td>
          <td>false</td>
          <td>Creates a disables spinbox.</td>
        </tr>
        <tr>
          <td>units</td>
          <td>array</td>
          <td>[]</td>
          <td>Units that will be allowed to appear and be typed into the spinbox input along with the numeric value. For example, setting units to a value of <code>['px', 'en', 'xx']</code> would allow <code>px, en, and xx</code> units to appear within the spinbox input</td>
        </tr>
      </tbody>
    </table>
  </div><!-- ./fu-table-responsive -->

  <h3 id="spinbox-usage-events">Events</h3>
  <div class="table-responsive">
    <table class="table table-bordered table-striped">
      <thead>
      <tr>
        <th style="width: 150px;">Event Type</th>
        <th>Description</th>
      </tr>
      </thead>
      <tbody>
      <tr>
        <td>changed.fu.spinbox</td>
        <td>This event fires when the value changes (either by selecting an item from the list or updating the input value directly). Arguments include <code>event, value</code> where value is the current value of the spinner. Returns the current value of the spinner.</td>
      </tr>
      </tbody>
    </table>
  </div><!-- ./fu-table-responsive -->
  <p>All spinbox events are fired on the <code>.spinbox</code> classed element.</p>
{% highlight js %}
$('#mySpinbox').on('changed.fu.spinbox', function () {
  // do something
})
{% endhighlight %}

  <h2 id="spinbox-examples">Example</h2>
  <p>Spinbox includes an enhanced numeric input based upon the native <code>&lt;input type=&quot;number&quot;&gt;</code>. Wrap the input and the increment/decrement buttons within <code>.fuelux .spinbox</code></p>

  <div class="fu-example section">

    <div class="form-group">
      <label class="control-label" for="mySpinboxWithDefaultInput">With default value and 3-digit class</label>
      <div class="form-group">

        <div id="mySpinboxWithDefault" class="spinbox digits-3" data-initialize="spinbox">
          <input id="mySpinboxWithDefaultInput" type="text" value="3" class="form-control input-mini spinbox-input">

          <div class="spinbox-buttons btn-group btn-group-vertical">
            <button type="button" class="btn btn-default spinbox-up btn-xs">
              <span class="glyphicon glyphicon-chevron-up"></span><span class="sr-only">Increase</span>
            </button>
            <button type="button" class="btn btn-default spinbox-down btn-xs">
              <span class="glyphicon glyphicon-chevron-down"></span><span class="sr-only">Decrease</span>
            </button>
          </div>
        </div>

      </div>
    </div>

    <h5 id="spinbox-examples-sample-methods">Sample Methods</h5>
    <div class="btn-group">
      <button id="btnSpinboxSetValue" type="button" class="btn btn-default">set value (4)</button>
      <button id="btnSpinboxGetValue" type="button" class="btn btn-default">get value</button>
      <button id="btnEnableSpinbox" type="button" class="btn btn-default">enable</button>
      <button id="btnDisableSpinbox" type="button" class="btn btn-default">disable</button>
      <button id="btnSpinboxDestroy" type="button" class="btn btn-default">destroy and append</button>
    </div>

  </div><!-- /example -->
</div><!-- end docs-section -->