Angular-selector-on-steroids NPM

angular-selector-on-steroids

angular-selector-on-steroids is a native AngularJS (1.6.x) directive that transforms a simple <select> html tag into a full html select with typeahead/ autocompletion. This component is a shameless upgrade to the angular-selector directive, which has been booted up with steroids to circumvent the limitations faced by with the older implementation, such as bad-performance, too many digest cycles and unnecessary watchers.

Why was there a need to upgrade?

The angular-selector although a well authored component, does not cater to large data-sets in terms of both limiting the amount of repeated processes/ iterations/ functions, and did not embrace better rendering and updating logic. Eventually it relied heavily on AngularJs two way data-binding which drove the performance to a stand-still for even a data-set with 1000 items. This created huge memory bloat and lag in the UI. It was time to upgrade the component.

What has been done as a part of upgrade?

Moved to Typescript, obvious reason being better typing and to expose interface of the component to the real consumers. (Previously just js soup).
Better abstraction and separation of concerns. (Previously non-modular code.)
Moved the build/ bundling to webpack, to allow for tree-shaking and packaged as UMD to allow imports. (Previously inline scripts).
Re-authored in es6, keeping up with better coding standards (Previously es5).
Every directive is a class, embracing OOP (Previously functional).
Data marshalling via RxJs, better pub-sub model of communication with in the modules (Previously callback pattern).
Rendering of html, moved from being dependent on angular DOM manipulation to Virtual dom's diff and patch mechanism, using virtual-dom and hyperx libraries. This provided significant performance boost in rendering. (Previously ng-x repeats and ng-x dom manipulators).

Dependencies

Just AngularJS!
Other dependencies are bundled into the UMD module.

Features

The feature set remains the same as the forked component, please refer original documentation here.
The extra added feature is called steroids. To enable better rendering and performance boost, set steroids=true in the configuration object.
100% fallback (reverse compatible) to orignial component logic, by setting a boolean values steroids=false the older way of rendering and non-performance component can be used.

Limitations

As the template generation & DOM Manipulation logic was moved virtual-dom and hyperx the current generated template abides by label & value attribute passed for binding interpolation.
For any complex dropdown or view item template a JSON structure of the object is shown. Kindly fallback to non-steroids version steroids=false if you need custom and complex template logic.

Examples

I have extended the example to a comparitive example of previous (steroids=false) vs new (steroids=true) implementation, to highlight difference in performance. // TODO: Check example link
An interactive version of all examples is accesible here https://jkodu.github.io/angular-selector-on-steroids

Installation

npm install --save angular-selector-on-steroids

Usage:

import * as sos from '../dist/angular-selector-on-steroids';
new sos.AngularSelectorOnSteroids().init();

const app = angular.module('MyApp', ['selectorOnSteroids']);

<select 
    selector-on-steroids
    steroids="true"    
    model="selectedObj" 
    options="arrayOfOptions" 
    value-attr="code" 
    >
</select>

Options/ Configuration

Parameter	Type	Default	Description
steroids	`Boolean`	`false`	Enable/disable the get performance boost in rendering and data marshalling.
remoteCancelPendingXhr	`Boolean`	`false`	Enable/disable pending request cancellation, on new XHR requests.
model	`Property`		Two-way binding property that models the `select` view.
name	`String`		Input name attribute.
disable	`Boolean`	`false`	Enable/disable the select. Note the name is `disable` not `disabled` to avoid collisions with the HTML5 disabled attribute.
disableSearch	`Boolean`	`false`	Enable/disable the search input field.
require	`Boolean`	`false`	Sets required validation. Note the name is `require` not `required` to avoid collisions with the HTML5 required attribute.
multi	`Boolean`	`false`	Allows to select more than one value. Note the name is `multi` not `multiple` to avoid collisions with the HTML5 multiple attribute.
limit	`Integer`	`Infinity`	Maximum number of selectable items when `multi` is `true`.
placeholder	`String`		Optional placeholder text to display if input is empty.
options	`Array`	`[]`	Set of options to display.Each object must contain a `label` key and a `value` key, otherwise you need to use a custom template (`viewItemTemplate` and `dropdownItemTemplate`) or change the default values of `valueAttr` and `labelAttr` properties.
valueAttr	`String`	`null`	Name of the value key in options array. This also sets the type of result for the model: if you don't set this attribute (`null` by default) the entire object option is returned, otherwise it will be returned only the selected property.
labelAttr	`String`	`"label"`	Name of the label key in options array.
groupAttr	`String`	`"group"`	Name of the `optgroup` label key in options array. It allows to group items by the selected key. Items have to be already sorted to see the groups just one time.
debounce	`Integer`	`0`	Debounce model update value in milliseconds.
rtl	`Boolean`	`false`	Two-way bindable attribute to set Right-To-Left text direction.
api	`Object`	`{}`	This object is equipped with the methods for interacting with the selector. Check out the "APIs" example.
create	`Boolean` or `Function` or `Promise`		Allows users to type the label of their own options and push them into the list. You can pass a function that returns the full format of the option, using `input` as parameter, a `Promise`, or set it to `true` to let Angular Selector create an object with the default properties given by `valueAttr` and `labelAttr`. Check out "Create custom options" and "Create custom options (using `Promise`)" examples.
change	`Function`		Callback fired every time the selected values change. It provides two parameters: `newValue` and `oldValue`.
remote	`Object` or `Promise`	{ method: 'GET', cache: true, params: {}}	You can use remote data fetching with the native `$http` service or with your own custom service. In the first case this parameter must be the configuration object to pass to the native `$http` service (docs). In the second case, `remote` is a function that returns a Promise object.
remoteParam	`String`	`"q"`	If `remote` attribute is used with the native `$http` service, this parameter is the name of the query key in the `params` object. You should use this to perform server-side filtering.
remoteValidation	`Object` or `Promise`	{ method: 'GET', cache: true, params: {}}	This should be used to perform validation after a "manual" update of the model. It has the same structure of the `remote` property, check out "Remote fetching and validation" example.
remoteValidationParam	`String`	`"value"`	If `remoteValidation` attribute is used with the native `$http` service, this parameter is the name of the query key in the `params` object.
removeButton	`Boolean`	`true`	Two-way bindable attribute to show the remove button (cross icon).
softDelete	`Boolean`	`false`	If `disableSearch` is `false`, restores the last selected input text (using `labelAttr` attribute) after pressing Backspace.
closeAfterSelection	`Boolean`	`false`	Close dropdown after selecting an item.
viewItemTemplate	`String`	`"selector/item-default.html"`	Template URL for the selected item(s).
dropdownItemTemplate	`String`	`"selector/item-default.html"`	Template URL for each item in the dropdown list.
dropdownCreateTemplate	`String`	`"selector/item-create.html"`	Template URL for the dropdown element for the new items.
dropdownGroupTemplate	`String`	`"selector/group-default.html"`	Template URL for each group (header) in the dropdown list.

Roadmap & Why there is no need to PR to original project

The code has matured to newer standards of Angular and Javascript, and hence there is no reason to update the older component.
The plan is to abstract the selector logic to pure Js and provide a bolt-on AngularJs and Angular component.

Contributions

PR's are welcome.
Please raise issues if any.

License

Licensed under the MIT license.

Local Development

npm install
npm run build-prod - generates a dist directory ready for publishing.
npm run build - generates the demo/dist directory for local development (no watch).
npm run dev - builds and watches both source and sandbox directory for local development.
npm run serve - boots up a http-server and serves the demo directory.