vsdropdown

vsdropdown v. 0.1.1

Virtual scroll dropdown - AngularJS reusable UI component

Description

AngularJS directive which implements the virtual scroll dropdown.

1. virtualization

• only visible items are rendered in the browser
• good performance even millions of items

2. custom scrollbar

• scrollbar can be customized by CSS
• looks similar in all browsers

3. filtering

• built in global filter
• uses AngularJS filter

4. responsive UI

• vsdropdown UI is responsive and scalable to different size of devices

5. tooltips

• tooltips are used to shown the string which are not fit to the vsdropdown

6. touch and keyboard

• works with touch devices
• works with keyboard

7. accepts objects

• input object is array of objects (items) or array of strings

8. no dependencies

• Depends only AngularJS

Usage

• include the vsdropdown-0.1.1.min.js and the vsdropdown-0.1.1.min.css files into your project. See the Build project and the Installation chapters below.

<script src="vsdropdown-0.1.1.min.js"></script>
<link href="vsdropdown-0.1.1.min.css" rel="stylesheet" type="text/css">

• inject the vsdropdown module into your application module.

angular.module('sampleapp', ['vsdropdown']);

• add vsdropdown HTML tag into your HTML file. See the HTML example chapter below.
• add needed Javascript code. See the Javascript example chapter below.

HTML example

<div ng-app="sampleapp" ng-controller="sampleappctrl">
    <vsdropdown options="opt"</vsdropdown>
</div>

Tags

Tag	Description	Mandatory
vsdropdown	vsdropdown tag	yes

Attributes

Attribute	Description	Mandatory
options	vsdropdown configuration object. See below.	yes

Options data (an options attribute in the vsdropdown directive)

Attribute	Description	Values	Mandatory
items	Array of data shown in the vsdropdown.	Array of strings or array of objects.	yes
selectedItems	Selected items. Contains all items.	Array of strings or array of objects	yes
input	Object which contain sub properties.	See below.	yes
input.isObject	Is items (see above) array of strings or array of objects.	true or false	yes
input.visiblePropName	This is visible property name. Only if isObject is true.	string	depends value of previous property
input.calculateDisplayValue	A callback function which takes the current item and returns a string representation. Only if isObject is true.	string	depends value of previous property
input.properties	Object which contain sub properties.	See below.	yes
input.properties.enabled	Is properties enabled or not.	true or false	if input.isObject is true
input.properties.props	String array of property names of the one item. These properties are visible in properties popover.	array	if input.properties.enabled is true
input.properties.propertyTitle	Property title in the popover.	string	if input.isObject is true
input.properties.valueTitle	Value title in the popover.	string	if input.isObject is true
filter	Object which contain sub properties.	See below.	yes
filter.enabled	Is filtering enabled or not. If false the filter input box is hidden.	true or false	yes
filter.filterPlaceholderTxt	Filter input box placeholder text.	string	yes
filter.noHitsTxt	Filter no hits text.	string	yes
selection	Object which contain sub properties.	See below.	yes
selection.maximum	Maximum selection count. If the dropdown is single select, put number 1 to this.	number	yes
selection.selectionsTxt	Selections text. Visible in the overlay	text	if previous value is bigger than 1
selection.showCount	Is selection count visible or not. Count is visible in the show overlay button.	true or false	if previous value is bigger than 1
visibleItemCount	Visible item count in the selector.	number	yes
showTooltip	Is tooltips shown or not.	true or false	yes
fadeInEffects	Is fade in effects used in the overlay and the tooltips.	true or false	yes
itemSelectCb	Item select callback function.	function	no. It is also possible to use AngularJS watch. See chapter Javascript example

Javascript example

var sampleapp = angular.module('sampleapp', ['vsdropdown']);
sampleapp.controller('sampleappctrl', function ($scope) {
 
    // Watch the user selections - invoked when the user select/deselect item from the vsdropdown
    $scope.$watch('opt.selectedItems', function (newVal, oldVal) {
        if (newVal !== oldVal) {
            console.log('PARENT - watch: ', newVal);
        }
    }, true);
    
    // Configuration example of the vsdropdown. 
    $scope.opt = {
        items: items,
        selectedItems: selectedItems,
        input: {
            isObject: true,
            calculateDisplayValue: function(item){
                return item.name;
            },
            visiblePropName: 'name',
            properties: {
                enabled: true,
                props: ['id', 'name', 'active'],
                propertyTitle: 'Property',
                valueTitle: 'Value'
            }
        },
        filter: {
            enabled: true,
            filterPlaceholderTxt: 'Type filter...',
            noHitsTxt: 'No hit(s)'
        },
        selection: {
            maximum: 20,
            selectionsTxt: 'selections',
            showCount: true
        },
        visibleItemCount: 4,
        showTooltip: true,
        fadeInEffects: true,
        itemSelectCb: onSelectItem
    };
};

itemSelectCb

Example of the function. See description of the parameters below the example.

function onSelectItem(items, selection, operation) {
    if (selection !== undefined) {
        console.log('PARENT - onSelectItem(): Selected item(s): ', items, ' - Selection: ', selection, ' - Operation: ', operation);
    }
}

Function	Parameters	Description
onSelectItem	items, selection and operation	Called when the user selects/deselects item from the UI.

Parameters

• items - all selected items
• selection - item which selection/deselection caused this event
• operation - select or deselect. select is + and deselect is -

Demo

In the examples folder of this project has the sample application and the online demo is here

Dependencies

Depends on AngularJS. Implemented using the AngularJS version 1.4.3.

Build project

• Build can be done by executing the grunt command. It creates the dist/debug and the dist/min folders and put files to these folders.

grunt

Installation

• Installation can be done using the bower. It installs files from the dist/debug and the dist/min folders. Needed CSS and javascript files are located in these folders.

bower install vsdropdown

Compatibility (tested with)

• IE 9+
• Firefox 36
• Google Chrome 41
• Opera 28.0
• Mobile Safari 8

License

• License: MIT

Author

• Author: kekeh