List.js

Do you want a 3 KB (gzipped&minified) cross-browser native JavaScript that makes your plain HTML lists super flexible, searchable, sortable and filterable? Yeah! Do you also want the possibility to add, edit and remove items by dead simple templating? Hell yeah!

Super simple examples

More examples are found at Listjs.com and Listjs.com/examples

Index existing list

HTML

<div id="hacker-list">
    <ul class="list">
       <li>
           <h3 class="name">Jonny</h3>
           <p class="city">Stockholm</p>
       </li>
       <li>
           <h3 class="name">Jonas</h3>
           <p class="city">Berlin</p>
       </li>
    </ul>
</div>

Javascript

var options = {
    valueNames: [ 'name', 'city' ]
};

var hackerList = new List('hacker-list', options);

Create list on initialization

Version 1 (does not work with tables)

HTML

<div id="hacker-list">
    <ul class="list"></ul>
</div>

JavaScript

var options = {
    item: '<li><h3 class="name"></h3><p class="city"></p></li>'
};

var values = [
    { name: 'Jonny', city:'Stockholm' }
    , { name: 'Jonas', city:'Berlin' }
];

var hackerList = new List('hacker-list', options, values);

Version 2

HTML

<div id="hacker-list">
    <ul class="list"></ul>
</div>

<div style="display:none;">
    <!-- A template element is needed when list is empty, TODO: needs a better solution -->
    <li id="hacker-item">
       <h3 class="name"></h3>
       <p class="city"></p>
    </li>
</div>

JavaScript

var options = {
    item: 'hacker-item'
};

var values = [
    { name: 'Jonny', city:'Stockholm' }
    , { name: 'Jonas', city:'Berlin' }
];

var hackerList = new List('hacker-list', options, values);

Index existing list and then add

HTML

<div id="hacker-list">
    <ul class="list">
       <li>
           <h3 class="name">Jonny</h3>
           <p class="city">Stockholm</p>
       </li>
    </ul>
</div>

JavaScript

var options = {
    valueNames: ['name', 'city']
};

var hackerList = new List('hacker-list', options);

hackerList.add( { name: 'Jonas', city:'Berlin' } );

Add automagic search and sort inputs and buttons

HTML

<div id="hacker-list">

    <input class="search" />
    <span class="sort" data-sort="name">Sort by name</span>
    <span class="sort" data-sort="city">Sort by city</span>

    <ul class="list">
       <li>
           <h3 class="name">Jonny</h3>
           <p class="city">Stockholm</p>
       </li>
       <li>
           <h3 class="name">Jonas</h3>
           <p class="city">Berlin</p>
       </li>
    </ul>
</div>

Javascript (nothing special)

var options = {
    valueNames: [ 'name', 'city' ]
};

var hackerList = new List('hacker-list', options);

Plugins

List.js offers the possiblity to use and add plugins that are integrated in the list objects and are initiated at the same time as the lists. Read more here »

List of plugins

• Paging plugin - A plugin for easily adding paging to List.js
• Fuzzy search plugin - A plugin for fuzzy search matching

As you can see, there are currently only two plugins. But I would very much like to add your plugin to this list if you just email me.

Documentation

Search, sort and list container element

The secret behind the search field, the sort buttons, and the list container element are the classes. By default, all inputs with class search become search fields for the list.

<input type="text" class="search" />

The sorting gets activated for all elements with class sort and then sorts the valueName corresponding to the the data-sort value of the element.

<span class="sort" data-sort="name">Sort names</span>

The element containing the list has to have the class list (or one that you define)

<ul class="list"></ul>
# Can be a div, table, dl, or whatever fits your purpose

All of these classes can be defined by yourself when creating the list by setting the options searchClass, listClass and sortClass.

Create a list

Constructor

• List(id, options, values)

Parameters

• id or element (*required) Id the element in which the list area should be initialized. OR the actual element itself.

• options Some of the option parameters are required at some times

  • valueNames (Array, default: null) (*only required if the list already contains items before initialization)
    If the list contains items on initialization, then this array has to contain the value names (class names) for the different values of each list item.

     <ul class="list">
         <li>
             <span class="name">Jonny</span>
             <span class="city">Sundsvall</span>
         </li>
     </ul>

    var valueNames = ['name', 'city'];

  • item (String, default: undefined)
    ID to item template element or a string of HTML (notice: does not work with <tr>)

    var options = {
        item: "<li><span class='name'></span><span class='city'></span></li>"
    }

  • listClass (String, default: "list")
    What is the class of the list-container?

  • searchClass (String, default: "search")
    What is the class of the search field?

  • sortClass (String, default: "sort")
    What is the class of the sort buttons?

  • indexAsync (Boolean, default: false)
    If there are already items in the list to which the List.js-script is added, then should the indexing be done in a asynchronous way? Good for large lists (> 500 items).

  • page (Int, default: 200) (maxVisibleItemsCount previously)
    Defines how many items that should be visible at the same time. This affects performance.

  • i (Int, default: 1)
    Which item should be shown as the first one.

  • plugins (Array, default: undefined)
    Read more about plugins here

• values (Array of objects) (*optional) Values to add to the list on initialization.

List API

These methods are available for the List-object.

Properties

• listContainer (Element)
  The element node that contains the entire list area.

• list (Element)
  The element containing all items.

• items (Array)
  An Array of all Item-objects in the list.

• visibleItems (Array)
  The currently visible items in the list

• matchingItems (Array)
  The items matching the currently active filter and search.

• searched (Boolean)
  Returns true if the list is searched.

• filtered (Boolean)
  Returns true if there is an active filter.

• list (Element)
  The element containing all items.

• templateEngines (Object)
  Contains all template engines available.

• plugins (Object)
  The currently avaliable plugins.

Methods

• add(values, callback)
  Adds one or more items to the list.

  listObj.add({ name: "Jonny", city: "Stockholm" });
  
  listObj.add([
      { name: "Gustaf", city: "Sundsvall" }
      , { name: "Jonas", city: "Berlin" }
  ]);

  If callback is set then items are added to the list in a asynchronous way, and the callback is called when all items are added. This is especially useful when adding very many items (200+ or something), or if you just like the asynchronous coding style.

  listObj.add(arrayWithManyManyItems, function(items) {
      console.log('All ' + items.length + ' were added!');
  });

• remove(valueName, value)
  Removes items from the list where the value named valueName has value value. Returns the number of items that where removed.

  itemsInList = [
  	{ id: 1, name: "Jonny" }
  	, { id: 2, name "Gustaf" }
  ];
  listObj.remove("id", 1); -> return 1

• get(valueName, value)
  Returns values from the list where the value named valueName has value value.

  itemsInList = [
  	{ id: 1, name: "Jonny" }
  	, { id: 2, name "Gustaf" }
  ];
  listObj.get("id", 2); -> return { id: 2, name "Gustaf" }

• sort(valueName, options)
  Sorts the list based on values the in the column named valueName. The options parameter can contain two properties options.sortFunction and options.asc. options.sortFunction is used if you want to make your own sort function. The default sort function is found here http://my.opera.com/GreyWyvern/blog/show.dml/1671288 options.asc = true means that you want to sort the list in ascending order. Set false for descending.

  listObj.sort('name', { asc: true }); -> Sorts the list in abc-order based on names
  listObj.sort('name', { asc: false }); -> Sorts the list in zxy-order based on names

• search(searchString, columns)
  Searches the list

  itemsInList = [
      { id: 1, name: "Jonny" }
      , { id: 2, name "Gustaf" }
      , { id: 3, name "Jonas" }
  ];
  
  listObj.search('Jonny'); -> Only item with name Jonny is shown (also returns this item)
  
  listObj.search(); -> Show all items in list

• clear()
  Removes all items from the list

• filter(filterFunction)

  itemsInList = [
      { id: 1, name: "Jonny" }
      , { id: 2, name "Gustaf" }
      , { id: 3, name "Jonas" }
  ];
  
  listObj.filter(function(item) {
     if (item.values().id > 1) {
         return true;
     } else {
         return false;
     }
  }); -> Only items with id > 1 are shown in list
  
  listObj.filter(); -> Remove all filters

• size()
  Returns the size of the list.

• show(i, page)
  Shows page number of items from i. Use for paging etc.

  itemsInList = [
      { id: 1, name: "Jonny" }
      , { id: 2, name "Gustaf" }
      , { id: 3, name "Jonas" }
      , { id: 4, name "Egon" }
      , { id: 5, name "Frank" }
      , { id: 6, name "Ester" }
  ];
  
  listObj.show(4, 3); -> Display item 4,5,6 

• update()
  Updates the current state of the list. Meaning that if you for instance hides some items with the itemObj.hide() method then you have to call listObj.update() if you want the paging to update.

• on(event, callback)
  Execute callback when list have been updated (triggered by update(), which is used by a lot of methods). Use updated as the event.

Item API

These methods are available for all Items that are returned by the list.

Properties

• elm (Element) The actual item DOM element

Methods

• values(newValues)

  • newValues optional If variable newValues are present the new values replaces the current item values and updates the list. If newValues are not present, the function returns the current values.

    item.values() -> { name: "Jonny", age: 24, city: "Umeå" }
    item.values({
        age: 25,
        city: "Stockholm"
    });
    item.values() -> { name: "Jonny", age: 25, city: "Stockholm" }

• show()
  Shows the item

• hide()
  Hides the item (removes the element from the list, and then when its shown it's appended again. The element will thereby change position in the list. A bug, but a good solution is yet to be found.)

• matching()
  Returns boolean. True if the item matches the current filter and search. Visible items always matches, but matching items are not always visible.

• visisble()
  Returns boolean. True if the item is visible. Visible items always matches, but matching items are not always visible.

Helper functions

Called by ListJsHelpers.functionName()

• getByClass(element, class, isSingle)
  http://www.dustindiaz.com/getelementsbyclass

• addEvent(element, type, callback)
  http://net.tutsplus.com/tutorials/javascript-ajax/javascript-from-null-cross-browser-event-binding/ Updated in some ways, thought.

• getAttribute(element, attribute)
  http://stackoverflow.com/questions/3755227/cross-browser-javascript-getattribute-method

• isNodeList(element)
  http://stackoverflow.com/questions/7238177/detect-htmlcollection-nodelist-in-javascript

• hasClass(element, class)
  Checks if element has class name class

• addClass(element, class)
  Adds class name class to element

• removeClass(element, class)
  Removes class name class from element

Plugins (paging)

Read more about plugins in this blog post and find out how to use the paging plugin here.

Performance and benchmarking

Read about it at The List.js Blog: Performance, wroooooom! Index, search and sort thousands of items and try it at the performance test page.

How to build the script

Type just ant in the console while in root folder.

Changelog

2012-04-24 Beta 0.2.1

• Fuzzy Search plugin, .filter() changes and bug fixes Read more »

2012-01-23 Beta 0.2.0

• Lots of updates and interesting features. Read more »

2011-12-15 Beta 0.1.4

• .filters(), .sort() and .search() now deped on each other. If the list is filtered and then there is a search, the items hidden by the filters will stay hidden etc.
• .filter() is the only way to reset filter. .filter(false) does not work anymore.

2011-11-29 Beta 0.1.3 release

• Added function .clear() that removes all items from the list
• Changed the sort function to be based on data-sort instead of rel
• When sorting one category, all sort-related classes will be removed from the other sort buttons
• Updated .sort(valueName, sortFunction) to .sort(valueName, options), se more info in the documentation

2011-11-16 Beta 0.1.2 release

• Sorting is now indicated by class asc or desc at sorting buttons
• Added three new small helper functions hasClass(element, class), addClass(element, class) and removeClass(element, class)

2011-10-20 Beta 0.1.1 release

• Added possibility to reverse sort the list

2011-10-18 Beta 0.1 release

• Examples at Listjs.com works in IE7,8,9 (IE6 is not tested, should work)
• More documentation
• Misc bug fixes

2011-10-15 Final alpha 0.3 release

• More documentation
• Only show 200 items at same time, huge speed increase
• Misc bug fixes

2011-08-08 Alpha 0.2 release

• Added asynchronous item adding
• Added asynchronous list indexing
• Improved (but incomplete) documentation
• Bugfixes and improved helper functions
• Show helper functions non-minified

2011-07-25 Alpha 0.1 release

License (MIT)

Copyright (c) 2012 Jonny Strömberg http://jonnystromberg.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.