sc-filtered-list

• FilteredList()
• Installation
• Overview
• Instantiate
• Options
• Defaults
• Events
• Styling
• Templates
• FilteredList.data()
• Add a single object/item
• Get the value
• FilteredList.destroy()

FilteredList()

sc-filtered-list is a UI control to allow the user to quickly choose a single object from a list of many objects.

Installation

Get Node.js. And then in a console...

npm install

Overview

This control is attached to a button. When the button is clicked a list would appear inline to allow the user to either use the mouse or keyboard to choose an item. A text input is available to allow the list to be filtered.

Instantiate

The FilteredList can be instantiated using data- attributes directly in the markup or manually by code.

Instantiate using data- attributes

Add data-sc-filtered-list to a <button>. Will instantiate on domready.

<button data-sc-filtered-list>

To get a reference to the instantiated object use the jQuery data method:

$('#myButton').data('scfilteredlist');

Instantiate using code

var filter = new FilteredList(document.querySelector('#myButton'));

Options

Give options using the data- attribute.

<button data-sc-filtered-list data-sc-filtered-list-options='{"fuzzy": true}'>

The options object must be a properly formatted JSON string.

Give options using code.

var filter = new FilteredList(document.querySelector('#myButton'), {
  fuzzy: true
});

• buttonLabel The button label (default: "Choose one")
• fuzzy The search type. If true "dvd" will match "david" (default: false)
• itemLabelKey The object key to use for the items label (default: "name")
• listTitle The title above the list (default: "Select an item")
• maxNumItems The maximum number of items in the list (default: 10)
• maxNumItemsVisible The maximum number of items visible (default: 7)
• width The width of the list (default: 300)
• sort The default sort ["", "asc", "desc"] (default: "desc")
• sortControlVisible If the sort control is visible (default: true)

Defaults

To change the defaults, use the global FilteredList variable.

FilteredList.defaults.maxNumItems = 10;

Events

The FilteredList uses an event based system with methods on, off and once.

myList.on('change', function(){});

Events

• change When the user selects and item and the value has changed
• close When the list closes
• destroy When the FilteredList is destroyed
• filtered When the search value changes
• itemFocus When an item in the list gains focus
• open When the list opens
• sort When the list is sorted
• redraw When the list redraws itself
• fetch When the list tries to fetch data based on the search term

Styling

CSS is provided and is required however it is plain by design. There are 2 ways to make the list pretty.

1. Include bootstrap 3.x
2. Write your own

Templates

The markup that is generated on instantiation is template driven. These templates can be changed if necessary.

FilteredList.templates.listWrapper

<div class='{{config.className}}-container'>{{!config.templates.listInput}}{{!config.templates.listHeader}}{{!config.templates.listItemWrapper}}</div>

FilteredList.templates.listInput

<div class='{{config.className}}-input-container'><input type='text' class='{{config.className}}-input form-control'></div>

FilteredList.templates.listHeader

<header class='{{config.className}}-header panel-heading'>{{!config.defaults.listTitle}}{{!config.templates.listSortToggle}}</header>

FilteredList.templates.listItemWrapper

<div class='{{config.className}}-items list-group'></div>

FilteredList.templates.listItem

<a href class='{{config.className}}-item list-group-item' data-cid='{{cid}}'>{{!key}}</a>

FilteredList.templates.listSortToggle

<button type='button' class='{{config.className}}-sort-toggle btn btn-default btn-xs' title='sort'></button>

FilteredList.data()

Adds an array of objects/items in bulk

myList.data([{
  name: "david"
}, {
  name: "max"
}]);

Add a single object/item

myList.items.push({
  name: "david"
});

Get the value

To get the value of the selected object/item use the value property.

myList.value;

FilteredList.destroy()

Destroys the FilteredList and invalidates the object.

myList.destroy();

Any further calls to methods like destroy or data etc will return nothing.