--- layout: default title: List API redirect_from: - /docs/list-api - /docs/options ---
Using List.js is pretty much plug and play, but you can change some options if you feel like it.
new List(id/element, options, values);
options Some of the option parameters are required at some times
valueNames Array, default: null. *required
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'];
<ul class="list">
<li data-id="1">
<a href="http://javve.com" class="link name">Jonny</a>
<p class="born timestamp" data-timestamp="1234">1986</p>
<img class="image" src="javve.jpg" />
</li>
</ul>
var valueNames = [
'name',
'born',
{ data: ['id'] },
{ name: 'timestamp', attr: 'data-timestamp' },
{ name: 'link', attr: 'href' },
{ name: 'image', attr: 'src' }
];
item String, default: undefined
ID to item template element or a string of HTML.
var options = {
item: "<li><span class='name'></span><span class='city'></span></li>"
}
// or
var options = {
item: 'cool-item-id'
};
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
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.
pagination Boolean, default: false
Read more here.
values Array of objects) (*optional Values to add to the list on initialization.
listContainer
Element
The element node that contains the entire list area.
matchingItems
Array
The items matching the currently active filter and search.
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, {
order: 'desc',
alphabet: undefined,
insensitive: true,
sortFunction: undefined
})
Sorts the list based on values the in the column named valueName
.
The alphabet
option is used when you have non-english alphabet
where which JavaScript don't know how to sort some characters by default.
The default sort function is found here https://github.com/nwoltman/string-natural-compare, if you want to use your own, read the code and check out the tests.
listObj.sort('name', { order: "asc" }); // Sorts the list in abc-order based on names
listObj.sort('name', { order: "desc" }); // Sorts the list in zxy-order based on names
// Sort swedish characters correcly, case-insensitive.
listObj.sort('name', { alphabet: "ABCDEFGHIJKLMNOPQRSTUVXYZÅÄÖabcdefghijklmnopqrstuvxyzåäö" });
// Sort swedish characters correcly, case-sensitive.
listObj.sort('name', { alphabet: "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvXxYyZzÅåÄäÖö" });
// Alphabet could also be on the actual listObj via
listObj.alphabet = "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvXxYyZzÅåÄäÖö";
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
listObj.search('Jonny', ['name']); // Only search in the 'name' column
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
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.
reIndex()
Re-index list from HTML. Good to use if the HTML has been changed by something
else than List.js.
fuzzySearch()
Read more here
Execute callback
when list have been updated (triggered by update()
, which is used by a lot of methods). Use updated
as the event.