## What is AngularJS Dropdown Multiselect?

This directive uses Bootstrap's Dropdown with the power of AngularJS directives and binding. Bootstrap and AngularJS are the only dependencies.
In this page you can see basic and advanced usage examples.

## Download

There are several options to do that:

1. Using bower: `bower install angularjs-dropdown-multiselect`
2. Using npm: `npm install angularjs-dropdown-multiselect`
3. Download the .zip file from here

This is documentation for the currently still in beta v2.0.0, the documentation for v1 can be found here: V1 docs
test

### Demo

### The model:

    {{testmodel|json}}

### Demo

### The model:

    {{example1model|json}}

### Code

// HTML
// JavaScript $scope.example1model = []; $scope.example1data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"} ];
This example shows the ability to select the property to display as text label.
In this case, the property the used as label is "id".

### Demo

### The model:

    {{example2model|json}}

### Code

// HTML
// JavaScript $scope.example2model = []; $scope.example2data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"}]; $scope.example2settings = {displayProp: 'id'};
You can use the feature in order to show which items are selected instead the items count.
In order to use this feature, set the "smartButtonMaxItems" settings parameter to a number bigger than 0.
You can also provide "smartButtonTextConverter" parameter in order to add smart logic and convert the text.

### Demo

### The model:

    {{example13model|json}}

### Code

//HTML
//JS $scope.example13model = []; $scope.example13data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Lisa"}, {id: 4, label: "Nicole"}, {id: 5, label: "Danny"} ]; $scope.example13settings = { smartButtonMaxItems: 3, smartButtonTextConverter: function(itemText, originalItem) { if (itemText === 'Jhon') { return 'Jhonny!'; } return itemText; } };
You can use the feature in order to make the list of items scrollable. Useful when you deal with a lot of items.

### Demo

### The model:

    {{example14model|json}}

### Code

//HTML
//JS $scope.example14model = []; $scope.example14data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Lisa"}, {id: 4, label: "Nicole"}, {id: 5, label: "Danny"}, {id: 6, label: "Dan"}, {id: 7, label: "Dean"}, {id: 8, label: "Adam"}, {id: 9, label: "Uri"}, {id: 10, label: "Phil"} ]; $scope.example14settings = { scrollableHeight: '100px', scrollable: true };

### Demo

### The model:

    {{example9model|json}}

### Code

// HTML
// JavaScript $scope.example9model = []; $scope.example9data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"}]; $scope.example9settings = {enableSearch: true};
By default, search is done on all items, by specifying the searchField in the settings object one can specify on which field of the objects the filtering should be done.

### Demo

### The model:

    {{example20model|json}}

### Code

// HTML
// JavaScript $scope.example20model = []; $scope.example20data = [ { id: 1, label: "David", age: 23 }, { id: 2, label: "Jhon", age: 24 }, { id: 3, label: "Danny", age: 26 } ]; $scope.example20settings = { searchField: 'age', enableSearch: true };
Setting showEnableSearchButton to true will add the enable/disable search button under the Select all / Deselect all buttons

### Demo

### The model:

    {{example21model|json}}

### Code

// HTML
// JavaScript $scope.example21model = []; $scope.example21data = [ { id: 1, label: "David"}, { id: 2, label: "Jhon"}, { id: 3, label: "Danny"} ]; $scope.example21settings = { showEnableSearchButton: true };

### Demo

### The model:

    {{searchSelectAllModel|json}}

### Code

// HTML
// JavaScript $scope.searchSelectAllModel = []; $scope.searchSelectAllData = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"} ]; $scope.searchSelectAllSettings = { enableSearch: true, showSelectAll: true, keyboardControls: true };
By default, there is no limit on the maximum selected items.
You can limit the selection by providing selectionLimit using the settings attribute.
Note 1: limit the selection to 0 is the default and won't limit the selection!
Note 2: When using this limit, the "Select All" button will not appear!
Note 3: When using single selection (limit to 1) the selection will change automaticlly if another item is clicked!

### Demo

### The model:

    {{example10model|json}}

### Code

// HTML
// JavaScript $scope.example10model = []; $scope.example10data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"}]; $scope.example10settings = {selectionLimit: 2};
Please read the notes in the "Selection Limit" example.
This example shows an example of using selection limit and single selection.

### Demo

### The model:

    {{example12model|json}}

### Code

// HTML
// JavaScript $scope.example12model = {}; // ! IMPORTANT ! $scope.example12data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"} ]; $scope.example12settings = { selectionLimit: 1, };
You can also group the items by propery that you want, in order to to that, provide the groupBy setting.
Also, you need to provide "groupByTextProvider" callback in the extra-settings attribute, in order to provide the header text for each group.
Note: If you won't specify the "groupByTextProvider" callback in order to get the header for each group, the value of the group will be displayed!

### Demo

### The model:

    {{example11model|json}}

### Code

// HTML
// JavaScript $scope.example11model = []; $scope.example11data = [ {id: 1, label: "David", gender: 'M'}, {id: 2, label: "Jhon", gender: 'M'}, {id: 3, label: "Lisa", gender: 'F'}, {id: 4, label: "Nicole", gender: 'F'}, {id: 5, label: "Danny", gender: 'M'} ]; $scope.example11settings = { groupByTextProvider: function(groupValue) { if (groupValue === 'M') { return 'Male'; } else { return 'Female'; } }, groupBy: 'gender', };
When items are grouped by property you can also specify an array of groups that you can use to select the items by. The extra-settings property selectByGroups accepts an array of the values of the groups that you want to be selectable. The naming will use the groupByTextProvider function to give them an actual label.

### Demo

### The model:

    {{selectByGroupModel|json}}

### Code

// HTML
// JavaScript $scope.selectByGroupModel = []; $scope.selectByGroupData = [ { id: 1, label: "David", gender: 'M' }, { id: 2, label: "Jhon", gender: 'M' }, { id: 3, label: "Lisa", gender: 'F' }, { id: 4, label: "Nicole", gender: 'F' }, { id: 5, label: "Danny", gender: 'M' }, { id: 6, label: "Unknown", gender: 'O' } ]; $scope.selectByGroupSettings = { selectByGroups: ['F', 'M'], groupByTextProvider: function(groupValue) { switch (groupValue) { case 'M': return 'Male'; case 'F': return 'Female'; case 'O': return 'Other'; } }, groupBy: 'gender', };
You can select your own text of the button using the "defaultText" in settings.

### Demo

### The model:

    {{example5model|json}}

### Code

// HTML
// JavaScript $scope.example5model = []; $scope.example5data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"}]; $scope.example5settings = {}; $scope.example5customTexts = {buttonDefaultText: 'Select Users'};
This example shows a demostration of using a pre-setted model.
Note:The model should have the same objects as in the options array.

### Demo

### The model:

    {{example6model|json}}

### Code

// HTML
// JavaScript $scope.example6data = [ { id: 1, label: 'David' }, { id: 2, label: 'Jhon' }, { id: 3, label: 'Danny' } ]; $scope.example6model = [$scope.example6data[0], $scope.example6data[2]]; $scope.example6settings = {};
This example shows a demostration of access and set the search filter from outside the directive.
This can be done by settings the "search-filter" attribute.

### Demo

### The model:

    {{example7model|json}}

### Search Filter:

    {{customFilter|json}}

### Code

// HTML
// JavaScript $scope.example15model = []; $scope.example15data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Lisa"}, {id: 4, label: "Nicole"}, {id: 5, label: "Danny"} ]; $scope.example15settings = { enableSearch: true }; $scope.customFilter = 'a';
You can also use a checkboxes list by setting checkBoxes setting to true!

### Demo

### The model:

    {{example8model|json}}

### Code

// HTML
// JavaScript $scope.example8model = []; $scope.example8data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"} ]; $scope.example8settings = { checkBoxes: true, };

### Demo

You can also aplly the active class to the selected list items. This can be done by setting the styleActive setting to true

### The model:

    {{example16model|json}}

### Code

// HTML
// JavaScript $scope.example16model = []; $scope.example16data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"}]; $scope.example16settings = {styleActive: true};

### Demo

When activated the dropdown can be used with the keyboard instead of with the mouse. Up, down arrow change focused element, escape closes the dropdown, enter and space activate focused element.

### The model:

    {{example17model|json}}

### Code

// HTML
// JavaScript $scope.example17model = []; $scope.example17data = [ {id: 1, label: "David"}, {id: 2, label: "Jhon"}, {id: 3, label: "Danny"}]; $scope.example17settings = {keyboardControls: true};

### Demo

When search is enabled and a single selection is active, wehn search returns a single match pressing enter in the search box will activate the matched option.

### The model:

    {{example18model|json}}

### Code

// HTML
// JavaScript $scope.example18model = {}; $scope.example18data = [ { id: 1, label: "David" }, { id: 2, label: "Jhon" }, { id: 3, label: "Lisa" }, { id: 4, label: "Nicole" }, { id: 5, label: "Danny" } ]; $scope.example18settings = { keyboardControls: true, enableSearch: true, selectionLimit: 1 };

### Demo

Instead of using the default template you can use an own custom temlpate.

### The model:

    {{example19model|json}}

### Code

// HTML
// JavaScript $scope.example19model = {}; $scope.example19data = [ { id: 1, name: "David" }, { id: 2, name: "Jhon" }, { id: 3, name: "Lisa" }, { id: 4, name: "Nicole" }, { id: 5, name: "Danny" } ]; $scope.example19settings = { template: '{{option.name}}' };
Setting the field disabled of an option to true will disable that option, if the option was previously checked it will still stay checked and will not be able to be unchecked.

### Demo

### The model:

    {{disabledModel|json}}

### Code

// HTML
// JavaScript $scope.disabledModel = []; $scope.disabledData = [ { id: 1, label: "David", disabled: true}, { id: 2, label: "Jhon"}, { id: 3, label: "Danny"} ];
When setting "selectedToTop" to true, selected items will be ordered to the top. When group by is active, the selected items will be at the top of their group.

### Demo

### The model:

    {{selectedToTopModel|json}}

### Code

// HTML
// JavaScript $scope.selectedToTopModel = []; $scope.selectedToTopData = [ { id: 1, label: 'David' }, { id: 2, label: 'Jhon' }, { id: 3, label: 'Danny' }, ]; $scope.selectedToTopSettings = { selectedToTop: true, };
Example to show that options no longer need to be an object with an id property

### Demo

### The model:

    {{stringModel|json}}

### Code

// HTML
$scope.stringModel = []; $scope.stringData = [ 'David', 'Jhon', 'Danny', ]; $scope.stringSettings = { template: '{{option}}', smartButtonTextConverter(skip, option) { return option; }, };
Example to show that you can replace the button with a custom element.

### Demo

My Custom trigger

### The model:

    {{transclusionModel|json}}

### Code

// HTML
My Custom trigger
$scope.transclusionModel = []; $scope.transclusionData = [ { id: 1, label: 'David' }, { id: 2, label: 'Jhon' }, { id: 3, label: 'Danny' }, ]; $scope.transclusionSettings = { };
When idProperty is set the objects will be compared by that property (that should be unique) instead of by reference.

### Demo

### The model:

    {{idPropertyModel|json}}

### Code

// HTML
$scope.idPropertyModel = [{ id: 1 }]; $scope.idPropertyData = [ { id: 1, label: 'David' }, { id: 2, label: 'Jhon' }, { id: 3, label: 'Danny' }, ]; $scope.idPropertySettings = { idProperty: 'id', };
When there is a selection this method will be called with the selection as a parameter. The function is supposed to return the text that you want to display on the button.

### Demo

### The model:

    {{smartButtonTextProviderModel|json}}

### Code

// HTML
$scope.smartButtonTextProviderModel = []; $scope.smartButtonTextProviderData = [ { id: 1, label: 'David' }, { id: 2, label: 'Jhon' }, { id: 3, label: 'Danny' }, ]; $scope.idPropertySettings = { smartButtonTextProvider(selectionArray) { return selectionArray.length + 2; }, };

# Full API Documentation

## Attributes

List of allowed attributes, you can find more information about them in the usage examples above.

Attribute Name | Type | Description
--- | --- | ---
selected-model | Object / Array | The object the will contain the model for the selected items in the dropdown.
options | Object / Array | The options for the dropdown.
extra-settings | Object | The settings for the directive, more information about these settings are available below.
events | Object | Events callbacks, more information below.
translation-texts | Object | Gives the ability to modify the default texts in the directive. More information below.
search-filter | String | Uses for settings the search filter from outside the direcrtive.
disabled | Boolean | Used for disabling the dropdown.

## Settings

Available settings that effects the display or behavior of the directive.
These setting are set with the "extra-settings" attribute.

Property Name | Type | Default Value | Description
--- | --- | --- | ---
dynamicTitle | Boolean | true | Indicates if the text of the button should change when selecting items from the list.
closeOnBlur | Boolean | true | Indicates if the dropdown should close when clicking outside of it's scope.
displayProp | String | label | The name of the property that contains the text for the item.
enableSearch | Boolean | false | Indicated if to show the search input or not.
clearSearchOnClose | Boolean | false | Indicated if to clear the search field when the dropdown has closed.
searchField | String | "$" | Indicates on which field the search should be done
selectionLimit | Number | 0 | The max allowed selected items for the list. For more information see the examples above.
showCheckAll | Boolean | true | Indicates if to show the "Check All" item.
showUncheckAll | Boolean | true | Indicates if to show the "Uncheck All" item.
showEnableSearchButton | Boolean | false | Indicates if to show the "Enable search / Disable search" item.
closeOnSelect | Boolean | false | Indicates if to close the dropdown after checking an item on the list.
closeOnDeselect | Boolean | false | Indicates if to close the dropdown after unchecking an item on the list. With selectionLimit = 1 setting this to true does the same as setting closeOnSelect to true.
buttonClasses | String | btn btn-default | The CSS classes that used for setting the style of the button.
groupBy | String | undefined | The name of the property which you like to group by your options. See grouping example.
groupByTextProvider | Function | angular.noop | A callback to a function that provide that name for each group when using groupBy setting. The parameter for the function will be the value of the groupBy property.
scrollable | Boolean | false | Indicates if the dropdown is scrollable, useful if you have a lot of items.
scrollableHeight | Number | 300px | Indicates the height of the drop down if the dropdown is scrollable.
smartButtonMaxItems | Number | 0 | Manages the "Smart Button Text" feature, defines the maximum amount of items to on the button.
smartButtonTextConverter | Function | angular.noop | Related the "Smart Button Text" feature, if a function provided - it will called with two paramters: The item's text and the original item, the return value will displayed instead of the item's display property. This feature is useful when you want to convert the displayed text into something else.
styleActive | Boolean | false | Indicates if the list items should get a class active applied when they are selected.
keyboardControls | Boolean | false | When activated the dropdown can be used with the keyboard instead of with the mouse.
template | String | { {getPropertyForObject(option, settings.displayProp)} } | Can be used to modify the appearance of an option in the list, each option is accessible as option.
selectByGroups | Array | undefined | Values of the groupby property that you want to be selectable as group
checkBoxes | Boolean | false | Indicated if to show a normal dropdown with glyphicons or HTML checkboxes.
selectedToTop | Boolean | false | When true will put the selected options at the top of the list
idProperty | string | undefined | Used to compare by property instead of by reference.

## Events

Available event callbacks what the directive fires. These callbacks are set with "events" attribute.

Event Name | Parameters | Description
--- | --- | ---
onItemSelect | item | Fired when selecting an item.
onItemDeselect | item | Fired when unselecting an item.
onSelectAll |  | Fired when clicking select all.
onDeselectAll |  | Fired when clicking unselect all.
onInitDone |  | Fired when the directive done with the "link" phase.
onMaxSelectionReached |  | Fired when the user reaches the max allowed selected items.
onSelectionChanged |  | Fired when the selection changes.

## Translation Texts

Available texts that you can override if you wan't to make a translation for your website. These are set with the "translation-texts" attribute.

Property Name | Default Value | Description
--- | --- | ---
checkAll | Check All | "Check All" item's text.
uncheckAll | Uncheck All | "Uncheck All" item's text.
enableSearch | Enable search | "enable search" item's text.
disableSearch | Disable search | "disable search" item's text.
selectionCount | checked | The suffix for "X/Y" that showed when using selection limit.
selectionOf | / | The value between the selected values and the max values when using selection limit.
searchPlaceholder | Search... | The placeholder for the search input.
buttonDefaultText | Select | The default text that used for the button when no items selected.
dynamicButtonTextSuffix | checked | The suffix for the button that used when using "dynamicText".
selectGroup | Select All: | The prefix of the group selection.