list-api.ejs

<%- include top.ejs %>
<div class="row">
  <div class="col-sm-3">
    <%- include ../sub-menu.ejs %>
  </div>
  <div class="col-sm-9 docs">

    <h2><a name="list-api" class="anchor" href="#list-api"></a>List API</h2>
    <p>These properties and methods are available for the List-object.</p>

    <h3><a name="properties" class="anchor" href="#properties"></a>Properties</h3>

    <ul>
      <li>
        <p>
          <strong>listContainer <a name="listContainer" class="anchor" href="#listContainer"></a></strong>
          <em class="docs-parameter-description">Element</em><br>
          The element node that contains the entire list area.
        </p>
      </li>
      <li>
        <p>
          <strong>list <a name="list" class="anchor" href="#list"></a></strong>
          <em class="docs-parameter-description">Element</em><br>
          The element containing all items.
        </p>
      </li>
      <li>
        <p>
          <strong>items <a name="items" class="anchor" href="#items"></a></strong>
          <em class="docs-parameter-description">Array</em><br>
          An Array of all Item-objects in the list.
        </p>
      </li>
      <li>
        <p>
          <strong>visibleItems <a name="visibleItems" class="anchor" href="#visibleItems"></a></strong>
          <em class="docs-parameter-description">Array</em><br>
          The currently visible items in the list
        </p>
      </li>
      <li>
        <p>
          <strong>matchingItems <a name="matchingItems" class="anchor" href="#matchingItems"></a></strong>
          <em class="docs-parameter-description">Array</em><br>
          The items matching the currently active filter and search.
        </p>
      </li>
      <li>
        <p>
          <strong>searched <a name="searched" class="anchor" href="#searched"></a></strong>
          <em class="docs-parameter-description">Boolean</em><br>
          Returns true if the list is searched.
        </p>
      </li>
      <li>
        <p>
          <strong>filtered <a name="filtered" class="anchor" href="#filtered"></a></strong>
          <em class="docs-parameter-description">Boolean</em><br>
          Returns true if there is an active filter.
        </p>
      </li>
      <li>
        <p>
          <strong>list <a name="list" class="anchor" href="#list"></a></strong>
          <em class="docs-parameter-description">Element</em><br>
          The element containing all items.
        </p>
      </li>
      <li>
        <p>
          <strong>plugins <a name="plugins" class="anchor" href="#plugins"></a></strong>
          <em class="docs-parameter-description">Object</em><br>
          The currently avaliable plugins.
        </p>
      </li>
    </ul>

    <h3><a name="methods" class="anchor" href="#methods"></a>Methods</h3>

    <ul>
      <li>
        <p><strong><a name="add" class="achor" href="#add"></a>add(values, callback)</strong><br>
        Adds one or more items to the list.</p>

<pre><code class="javascript">listObj.add({ name: "Jonny", city: "Stockholm" });

listObj.add([
    { name: "Gustaf", city: "Sundsvall" }
    , { name: "Jonas", city: "Berlin" }
]);</code></pre>

        <p>If <code>callback</code> 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.</p>

<pre><code class="javascript">listObj.add(arrayWithManyManyItems, function(items) {
    console.log('All ' + items.length + ' were added!');
});</code></pre>
      </li>
      <li>
        <p><strong><a name="remove" class="achor" href="#remove"></a>remove(valueName, value)</strong><br>
        Removes items from the list where the value named <code>valueName</code> has value <code>value</code>.
        Returns the number of items that where removed.</p>

<pre><code class="javascript">itemsInList = [
    { id: 1, name: "Jonny" }
    , { id: 2, name "Gustaf" }
];
listObj.remove("id", 1); -> return 1</code></pre>
      </li>
      <li>
        <p><strong><a name="get" class="achor" href="#get"></a>get(valueName, value)</strong><br>
        Returns values from the list where the value named <code>valueName</code> has value <code>value</code>.</p>

<pre><code class="javascript">itemsInList = [
    { id: 1, name: "Jonny" }
    , { id: 2, name "Gustaf" }
];
listObj.get("id", 2); -> return { id: 2, name "Gustaf" }</code></pre>
      </li>
      <li>
        <p><strong><a name="sort" class="achor" href="#sort"></a>sort(valueName, options)</strong><br>
        Sorts the list based on values the in the column named <code>valueName</code>. The options
        parameter can contain two properties <code>options.sortFunction</code> and <code>options.order</code>.
        <code>options.sortFunction</code> is used if you want to make your own sort function.
        The default sort function is found here <a href="http://my.opera.com/GreyWyvern/blog/show.dml/1671288">http://my.opera.com/GreyWyvern/blog/show.dml/1671288</a>
        <code>options.order = "asc"</code> means that you want to sort the list in ascending order. Set
        <code>false</code> for descending.</p>

<pre><code class="javascript">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</code></pre>

      </li>
      <li>
        <p><strong><a name="search" class="achor" href="#search"></a>search(searchString, columns)</strong><br>
          Searches the list</p>

<pre><code class="javascript">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</code></pre>

      </li>
      <li>
        <p><strong><a name="clear" class="achor" href="#clear"></a>clear()</strong><br>
        Removes all items from the list</p>
      </li>
      <li>
        <p><strong><a name="filter" class="achor" href="#filter"></a>filter(filterFunction)</strong></p>

<pre><code class="javascript">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</code></pre>

      </li>
      <li>
        <p><strong><a name="size" class="achor" href="#size"></a>size()</strong><br>
        Returns the size of the list.</p>
      </li>
      <li>
        <p><strong><a name="show" class="achor" href="#show"></a>show(i, page)</strong><br>
        Shows <code>page</code> number of items from <code>i</code>. Use for paging etc.</p>

<pre><code class="javascript">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 </code></pre>

      </li>
      <li>
        <p><strong><a name="update" class="achor" href="#update"></a>update()</strong><br>
        Updates the current state of the list. Meaning that if you for instance 
        hides some items with the <code>itemObj.hide()</code> method then you have to call <code>listObj.update()</code> 
        if you want the paging to update.</p>
      </li>
      <li>
        <p><strong><aname="on" class="achor" href="#on"></a>on(event, callback)</strong><br>
        Execute <code>callback</code> when list have been updated (triggered by <code>update()</code>, which is used by a lot of methods). Use <code>updated</code> as the event.</p>
        <h4>Avaliable events</h4>
        <ul>
          <li>updated</li>
          <li>searchStart</li>
          <li>searchComplete</li>
          <li>filterStart</li>
          <li>filterComplete</li>
          <li>sortStart</li>
          <li>sortComplete</li>
        </ul>
      </li>
</ul>

    <div class="continue">Next topic: <a href="/docs/item-api">Item API ›</a></div>
</div></div>