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.