fuelux/javascript.html

---
layout: default
title: Javascript
slug: javascript
lead: "Over a dozen reusable controls built to provide datepickers, pillboxes, trees, wizards, and much more."
---

<!-- Overview
================================================== -->
<div class="bs-docs-section">
  <h1 id="js-overview" class="page-header">Overview</h1>

  <h3 id="js-individual-compiled">Individual or compiled</h3>
  <p>Components can be included individually (using FuelUX's individual <code>*.js</code> files), or all at once (using <code>fuelux.js</code> or the minified <code>fuelux.min.js</code>).</p>

  <div class="bs-callout bs-callout-danger">
    <h4>Using the compiled JavaScript</h4>
    <p>Both <code>fuelux.js</code> and <code>fuelux.min.js</code> contain all plugins in a single file. Include only one.</p>
  </div>

  <div class="bs-callout bs-callout-danger">
    <h4>Plugin dependencies</h4>
    <p>Some components depend on other components. If you include components individually, make sure to check for these dependencies in the docs below. An error should be thrown if dependencies are not met. Also note that all plugins depend on jQuery and Bootstrap (this means jQuery and Boostrap must be included <strong>before</strong> the components files). <a href="{{ site.repo }}/blob/v{{ site.current_version }}/bower.json">Consult our <code>bower.json</code></a> to see which versions of jQuery and Bootstrap are supported.</p>
  </div>

  <h3 id="js-class-triggers">Selector-based initialization</h3>
  <p>You can initialize all FuelUX components on page load purely through markup without writing a single line of JavaScript by adding its respective class as a descendant of <code>.fuelux</code>.</p>

  <p>Alternatively, you can initialize a specific component like this at any time:</p>
{% highlight js %}
$('#myElement').selectlist();
{% endhighlight %}

  <p>All methods should accept an optional options object, a string which targets a particular method, or nothing (which initiates a plugin with default behavior):</p>
{% highlight js %}
$('#myElement').wizard()                      // initialized with defaults
$('#myElement').wizard('selectedItem', { step: 3 });)   // initialized with selectedItem
$('#myElement').wizard('show')                // initializes and invokes show immediately
{% endhighlight %}

  <p>Each plugin also exposes its raw constructor on a <code>Constructor</code> property: <code>$.fn.popover.Constructor</code>.</p>

  <h3 id="js-events">Events</h3>
  <p>FuelUX provides custom events for most components unique actions. Generally, these come in an infinitive and past form - where the infinitive (ex. <code>show</code>) is triggered at the start of an event, and its past form (ex. <code>changed</code>) is trigger on the completion of an action.</p>
  <p>As of 3.0.0, all FuelUX events are namespaced.</p>

  <div class="bs-callout bs-callout-warning" id="callout-third-party-libs">
    <h4>Third-party libraries</h4>
    <p><strong>Bootstrap does not officially support third-party JavaScript libraries</strong> like Prototype or jQuery UI. Despite <code>.noConflict</code> and namespaced events, there may be compatibility problems that you need to fix on your own.</p>
  </div>
</div>


<!-- checkbox
================================================== -->
<div class="bs-docs-section">
    <h1 id="checkboxes" class="page-header">Checkboxes <small>checkboxes.js</small></h1>

    <h2 id="checkboxes-examples">Examples</h2>
    <p>Browser-independent look and feel for checkbox element.</p>

    <h4>Default (stacked)</h4>
    <div class="bs-example">
        <div class="checkbox">
            <label class="checkbox-custom">
                <input type="checkbox" value="option1">
                Browser-independent checkbox unchecked on page load
            </label>
        </div>
        <div class="checkbox">
            <label class="checkbox-custom">
                <input checked="checked" type="checkbox" value="option2">
                Browser-independent checkbox checked on page load
            </label>
        </div>
        <div class="checkbox">
            <label class="checkbox-custom">
                <input disabled="disabled" type="checkbox" value="option3">
                Disabled browser-independent checkbox unchecked on page load
            </label>
        </div>
        <div class="checkbox">
            <label class="checkbox-custom">
                <input checked="checked" disabled="disabled" type="checkbox" value="option4">
                Disabled browser-independent checkbox checked on page load
            </label>
        </div>
    </div>

{% highlight html %}
<div class="checkbox">
  <label class="checkbox-custom">
    <input type="checkbox" value="">
    Browser-independent checkbox unchecked on page load
  </label>
</div>
<div class="checkbox">
  <label class="checkbox-custom">
    <input checked="checked" type="checkbox" value="">
    Browser-independent checkbox checked on page load
  </label>
</div>
<div class="checkbox">
  <label class="checkbox-custom">
    <input disabled="disabled" type="checkbox" value="">
    Disabled browser-independent checkbox unchecked on page load
  </label>
</div>
<div class="checkbox">
  <label class="checkbox-custom">
    <input checked="checked" disabled="disabled" type="checkbox" value="">
    Disabled browser-independent checkbox checked on page load
  </label>
</div>
{% endhighlight %}

    <h4>Inline checkboxes</h4>
    <p>Use the <code>.checkbox-inline</code> or <code>.radio-inline</code> classes on a series of checkboxes or radios for controls that appear on the same line.</p>
    <div class="bs-example">
        <label class="checkbox-custom checkbox-inline">
            <input type="checkbox" value="option1"> 1
        </label>
        <label class="checkbox-custom checkbox-inline">
            <input checked="checked" type="checkbox" value="option2"> 2
        </label>
        <label class="checkbox-custom checkbox-inline">
            <input disabled="disabled" type="checkbox" value="option3"> 3
        </label>
    </div>

{% highlight html %}
<label class="checkbox-custom checkbox-inline">
  <input type="checkbox" value="option1"> 1
</label>
<label class="checkbox-custom checkbox-inline">
  <input checked="checked" type="checkbox" value="option2"> 2
</label>
<label class="checkbox-custom checkbox-inline">
  <input disabled="disabled" type="checkbox" value="option3"> 3
</label>
{% endhighlight %}

    <h4>Element toggling checkboxes</h4>
    <p>Use the <code>data-toggle="{{selector}}"</code> to automatically show/hide elements matching the selector within the body upon check/uncheck. <strong>(works with any <a href="http://api.jquery.com/category/selectors/">jQuery selector</a>)</strong></p>
    <div class="bs-example">
        <div class="form-group">
            <div class="checkbox">
                <label class="checkbox-custom">
                    <input data-toggle="#checkboxToggleID" type="checkbox" value="option1">
                    Toggles element with matching id.
                </label>
            </div>
            <label class="checkbox-custom checkbox-inline">
                <input data-toggle=".checkboxToggleCLASS" type="checkbox" value="option1">
                Toggles elements with matching class.
            </label>
        </div>
        <div class="alert bg-info" id="checkboxToggleID" style="display: none;">Id toggling container.</div>
        <div class="alert bg-success checkboxToggleCLASS" style="display: none;">Class toggling container.</div>
        <div class="alert bg-success checkboxToggleCLASS" style="display: none;">Class toggling container.</div>
    </div>
{% highlight html %}
<div class="checkbox">
  <label class="checkbox-custom">
    <input data-toggle="#checkboxToggleID" type="checkbox" value="option1">
    Toggles element with matching id.
  </label>
</div>
<label class="checkbox-custom checkbox-inline">
  <input data-toggle=".checkboxToggleCLASS" type="checkbox" value="option1">
  Toggles elements with matching class.
</label>

<div class="alert bg-info" id="checkboxToggleID" style="display: none;">Id toggling container.</div>
<div class="alert bg-success checkboxToggleCLASS" style="display: none;">Class toggling container.</div>
<div class="alert bg-success checkboxToggleCLASS" style="display: none;">Class toggling container.</div>
{% endhighlight %}

    <h4>Highlighting checkboxes</h4>
    <p>Use the <code>.highlight</code> class to add a background highlight upon check.
    </p>
    <div class="bs-example">
        <div class="checkbox highlight">
            <label class="checkbox-custom">
                <input type="checkbox" value="option1">
                This block-level checkbox will be highlighted on check.
            </label>
        </div>
        <label class="checkbox-custom checkbox-inline highlight">
            <input type="checkbox" value="option2">
            This inline checkbox will be highlighted on check.
        </label>
    </div>
{% highlight html %}
<div class="checkbox highlight">
  <label class="checkbox-custom">
    <input type="checkbox" value="option1">
    This block-level checkbox will be highlighted on check.
  </label>
</div>
<label class="checkbox-custom checkbox-inline highlight">
  <input type="checkbox" value="option2">
  This inline checkbox will be highlighted on check.
</label>{% endhighlight %}

    <h2 id="checkboxes-usage">Usage</h2>
  <p>The checkbox code will automatically instantiate any checkboxes with the class <code>.scheduler</code> on page load, allowing them to function without any additional code. However, if the markup is added after page load they will need to be manually instantiated via Javascript.</p>

    <p>Initialize the checkbox manually via JavaScript:</p>
{% highlight js %}$('#MyCheckbox').checkbox();{% endhighlight %}

    <h3>Methods</h3>
    <h4>$().checkbox()</h4>
    Activates your content as a custom checkbox.

    <h4>.check()</h4>
    <p>Checks the checkbox.</p>
{% highlight js %}$('#element').checkbox('check'){% endhighlight %}

    <h4>.disable()</h4>
    <p>Disables the checkbox.</p>
{% highlight js %}$('#element').checkbox('disable'){% endhighlight %}

    <h4>.enable()</h4>
    <p>Enables the checkbox.</p>
{% highlight js %}$('#element').checkbox('enable'){% endhighlight %}

    <h4>.isChecked()</h4>
    <p>Returns <code>true</code> or <code>false</code> depending on whether the checkbox is checked.</p>
{% highlight js %}$('#element').checkbox('isChecked'){% endhighlight %}

    <h4>.toggle()</h4>
    <p>Toggles the checkbox between checked/unchecked states.</p>
{% highlight js %}$('#element').checkbox('toggle'){% endhighlight %}

    <h4>.uncheck()</h4>
    <p>Unchecks the checkbox.</p>
{% highlight js %}$('#element').checkbox('uncheck'){% endhighlight %}

</div>

{% include js-combobox.html %}

<!-- dropdown-autoflip
================================================== -->
<div class="bs-docs-section">
  <h1 id="dropdown-autoflips" class="page-header">Auto-Flip Dropdowns <small>dropdown-autoflip.js</small></h1>

  <p class="lead">Additional functionality added to dropdown menus that enables dropup menus instead of dropdown menu based on screen position.</p>

  <h2 id="dropdown-autoflips-example">Example</h2>
  <p>Add <code>data-flip="auto"</code> to a dropdown trigger <code>data-toggle="dropdown"</code>. (You may need to scroll up to trigget this functionality.) The menu will need be "below the fold" at the bottom of the screen in order to become a dropup menu. </p>
  <div class="bs-example">

    <div class="btn-group">
      <button type="button" class="btn btn-danger">Auto Flip Dropdown</button>
      <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" data-flip="auto">
        <span class="caret"></span>
        <span class="sr-only">Toggle Dropdown</span>
      </button>
      <ul class="dropdown-menu" role="menu" >
        <li><a href="#">Action</a></li>
        <li><a href="#">Another action</a></li>
        <li><a href="#">Something else here</a></li>
        <li class="divider"></li>
        <li><a href="#">Separated link</a></li>
      </ul>
    </div>

  </div><!-- /example -->

{% highlight html %}
<div class="btn-group">
  <button type="button" class="btn btn-danger">Auto Flip Dropdown</button>
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" data-flip="auto">
    <span class="caret"></span>
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <ul class="dropdown-menu" role="menu" >
    <li><a href="#">Action</a></li>
    <li><a href="#">Another action</a></li>
    <li><a href="#">Something else here</a></li>
    <li class="divider"></li>
    <li><a href="#">Separated link</a></li>
  </ul>
</div>
{% endhighlight %}

  <h3 id="dropdown-autoflips-alignment">Alignment</h3>
  <p>By default, a dropdown menu is automatically positioned 100% from the top and along the right side of its parent. Remove <code>.dropdown-menu-right</code> to a <code>.dropdown-menu</code> to left align the dropdown menu.</p>

  <h2 id="dropdown-autoflips-usage">Usage</h2>
  <p>The dropdown-autoflip add-on determines whether to show a dropdown menu or a dropup menu by calculating the position on the screen and the edge of the viewport. If a dropup menu is needed, <code>.dropup</code> is added to the <code>.dropdown-menu</code> element.</p>

  <h3>Markup</h3>
  <p>Add <code>data-flip="auto"</code> to a dropdown menu within a <code>class="fuelux"</code> container.</p>
  {% highlight html %}
  <div class="btn-group">
    <button type="button" class="btn btn-danger">Auto Flip Dropdown</button>
    <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" data-flip="auto">
      <span class="caret"></span>
      <span class="sr-only">Toggle Dropdown</span>
    </button>
    <ul class="dropdown-menu" role="menu" >
      ...
    </ul>
  </div>
  {% endhighlight %}

  <h3>Event Listeners</h3>
  <p>The auto-flip dropdown only recieves events.</p>
  <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>click</td>
          <td>Receives clicks from <code>[data-toggle=dropdown][data-flip]</code></td>
        </tr>
        <tr>
          <td>suggest</td>
          <td>Fire the <code>suggget</code> event and pass in a dropdown menu <code>$('#dropdownMenu').</code></td>
        </tr>
      </tbody>
    </table>
  </div><!-- ./bs-table-responsive -->
</div>

{% include js-pillbox.html %}

{% include js-scheduler.html %}

{% include js-selectlist.html %}

{% include js-spinbox.html %}

{% include js-tree.html %}

{% include js-wizard.html %}