# jQuery Bootstrap-style Dropdowns

## Backstory

One of my favorite Boostrap plugins is dropdowns, but I had a bit of difficulty getting started with them. The docs say you can apply a sa-dropdown to nearly any element, but they really seem to work best with Bootstrap’s navbar, tab, and pill components. Since I was retrofitting an app that was around long before Bootstrap, this wasn’t going to work for me. That and I was hoping to get a scrollable sa-dropdown (with tips!) and a few other features out of the deal. Thus, this plugin was born.

While the appearance is almost identical to those of Bootstrap’s, it’s important to note that JavaScript for this plugin was developed entirely from scratch. Some CSS was borrowed, however, especially for generating those gorgeous tips.

Wanna see what they look like? Try it! Wanna contribute to this project? It’s on GitHub

## Usage

1. Start by including the necessary files into your app:

    <link type="text/css" rel="stylesheet" href="jquery.dropdown.css" />
    <script type="text/javascript" src="jquery.dropdown.js"></script>

2. Create a sa-dropdown by placing a `div` with a unique `id` and the `sa-dropdown` class immediately before your closing `body` tag.

For sa-dropdown menus, the `div` should contain a `ul` with the `sa-dropdown-menu` class:

    <div id="sa-dropdown-1" class="sa-dropdown sa-dropdown-tip">
        <ul class="sa-dropdown-menu">
            <li><a href="#1">Item 1</a></li>
            <li><a href="#2">Item 2</a></li>
            <li><a href="#3">Item 3</a></li>
            <li class="sa-dropdown-divider"></li>
            <li><a href="#4">Item 4</a></li>
            <li><a href="#5">Item 5</a></li>
            <li><a href="#5">Item 6</a></li>
        </ul>
    </div>

For sa-dropdown panels, the `div` should contain a `div` with the `sa-dropdown-panel` class:

    <div id="sa-dropdown-1" class="sa-dropdown sa-dropdown-tip">
        <div class="sa-dropdown-panel">
            You can put whatever HTML you want in a panel!
        </div>
    </div>

3. Add the `data-sa-dropdown` attribute to any HTML element, using the `id` of the sa-dropdown as the value. That’s all you have to do–you don’t even have to initialize it! The plugin also works on dynamically generated triggers.

    <a href="#" data-sa-dropdown="#sa-dropdown-1">dropdown</a>

## Demos

Dropdowns can be attached to any element that you want:

Here’s a link and here’s a button and here’s a span

### Scrolling

Now let’s see a really long sa-dropdown that will scroll: Example

### Form Controls

You can add form controls to your dropdowns: Example

### Panels

Dropdowns can have regular HTML, too. Example

### Special Classes

- To disable the sa-dropdown, add the `sa-dropdown-disabled` class to the trigger element
- To offset positioning, add `data-horizontal-offset="10"` and/or `data-vertical-offset="10"` to the trigger element
- To add a tip to the sa-dropdown, add the `sa-dropdown-tip` class to the sa-dropdown element
- To make the sa-dropdown anchor to the right, add the `sa-dropdown-anchor-right` class: Example
- To position a sa-dropdown relative to its parent (as opposed to the document), add the `sa-dropdown-relative` class to the sa-dropdown container

## API

You probably won’t need these, but they’re there just in case:

- `attach` – attach a sa-dropdown to the selected trigger element(s); pass in the `#sa-dropdown-id-1` as `value`
- `detach` – detach a sa-dropdown from the selected trigger element(s)
- `enable` – enables the sa-dropdown and removes the `sa-dropdown-disabled` class from the trigger
- `disable` – disables the sa-dropdown and adds the `sa-dropdown-disabled` class to the trigger
- `hide` – hide the sa-dropdown
- `show` – show the sa-dropdown

Example usage: `$('#trigger').jqDropdown('method', [value]);`

## Events

You can attach events to each sa-dropdown:

- `show` — triggered when the sa-dropdown is shown
- `hide` — triggered when the sa-dropdown is hidden

Example usage:

    $('#sa-dropdown-id-1').on('show', function(event, dropdownData) {
        console.log(dropdownData);
    }).on('hide', function(event, dropdownData) {
        console.log(dropdownData);
    });

## Q&A

- How do I stop the sa-dropdown from going off the screen?
  This plugin was intended to be very lightweight—the initial release is less than 70 lines of code! If you have a very elegant way to keep the sa-dropdown within the viewport without using a dependency, let me know. Otherwise, position them higher or use the `sa-dropdown-anchor-right` class.
- How do I modify the sa-dropdown menu on the fly?
  Just modify it like any other element, but leave the `id` intact.
- Do they support submenus?
  No, and they aren’t intended to. That would add a significant amount of complexity to the plugin and is really outside the scope of this project.
- Can I get rid of the tips?
  Sure, just remove the `sa-dropdown-tip` class from your sa-dropdown.
- Do they work in IE?
  Yes, but you won’t see any tips in IE7 and you won’t see any box-shadows until IE9. They’re completely usable in IE 7/8, they’re just not as pretty.
- Is it free to use?
  Of course! It’s licensed under the MIT license.
- Which version of jQuery is required?
  This plugin will work with jQuery 1.8 and higher.
- Who made this?
  The same guy that runs A Beautiful Site, LLC and Surreal CMS.

Here is some `HTML` inside of a sa-dropdown. You can put pretty much anything inside of a sa-dropdown, so have fun with it!