List Index

    List Index allows to access a particular section of the list view instantly without scrolling through each section.

    List Index Layout

    Single List Index layout is pretty simple:

    <div class="page">
      <div class="navbar">...</div>
    
      <!-- List Index element, must be a direct child of page -->
      <div class="list-index"></div>
    
      <!-- Scrollable page content -->
      <div class="page-content">...</div>
    </div>
    

    List Index App Methods

    Let's look at related App methods to work with List Index:

    app.listIndex.create(parameters)- create List Index instance

    • parameters - object. Object with list index parameters

    Method returns created List Index's instance

    app.listIndex.destroy(el)- destroy List Index instance

    • el - HTMLElement or string (with CSS Selector) or object. List Index element or List Index instance to destroy.

    app.listIndex.get(el)- get List Index instance by HTML element

    • el - HTMLElement or string (with CSS Selector). List Index element.

    Method returns List Index's instance

    List Index Parameters

    Now let's look at list of available parameters we need to create List Index:

    Parameter Type Default Description
    el HTMLElement
    string
    List Index element. HTMLElement or string with CSS selector of list index element
    listEl HTMLElement
    string
    Related List View element. HTMLElement or string with CSS selector of List View element
    indexes array
    string
    auto Array with indexes. If not passed then it will automatically generate it based on item-divider and list-group-title elements inside of passed List View element in listEl parameter
    scrollList boolean true Will automatically scroll related List View to the selected index
    label boolean false Enables label bubble with selected index when you swipe over list index
    iosItemHeight number 14 Single index item height. It is required to calculate dynamic index and how many indexes fit on the screen. For iOS theme
    mdItemHeight number 14 Single index item height. It is required to calculate dynamic index and how many indexes fit on the screen. For MD theme
    on object Object with events handlers. For example:
    var listIndex = app.listIndex.create({
      el: '.list-index'
      on: {
        select: function () {
          console.log('Index selected')
        },
      },
    })
    

    List Index Methods & Properties

    So to create List Index we have to call:

    var listIndex = app.listIndex.create({ /* parameters */ })

    After that we have its initialized instance (like listIndex variable in example above) with useful methods and properties:

    Properties
    listIndex.app Link to global app instance
    listIndex.el List index HTML element
    listIndex.$el Dom7 instance with list index HTML element
    listIndex.ul Dynamically created inner <ul> HTML element
    listIndex.$ul Dom7 instance with dynamically created inner <ul> HTML element
    listIndex.listEl Related List HTML element, passed in listEl parameter
    listIndex.$listEl Dom7 instance with related List HTML element, passed in listEl parameter
    listIndex.indexes Array with calculated indexes
    listIndex.params List index parameters
    Methods
    listIndex.update() Recalculates indexes, sizes and rerenders list index
    listIndex.scrollToList(itemContent) Scrolls related list to specified index content
    listIndex.destroy() Destroys list index instance
    listIndex.on(event, handler) Add event handler
    listIndex.once(event, handler) Add event handler that will be removed after it was fired
    listIndex.off(event, handler) Remove event handler
    listIndex.off(event) Remove all handlers for specified event
    listIndex.emit(event, ...args) Fire event on instance

    List Index Events

    List Index will fire the following DOM events on list index element and events on app and list index instance:

    DOM Events

    Event Target Description
    listindex:select List Index Element<div class="list-index"> Event will be triggered on index select rather by click or swiping
    listindex:click List Index Element<div class="list-index"> Event will be triggered on index click
    listindex:beforedestroy List Index Element<div class="list-index"> Event will be triggered right before List Index instance will be destroyed

    App and List Index Instance Events

    List Index instance emits events on both self instance and app instance. App instance events has same names prefixed with listIndex.

    Event Arguments Target Description
    select (listIndex, itemContent) listIndex Event will be triggered on index select rather by click or swiping. As an argument event handler receives list index instance and selected index item content
    listIndexSelect (listIndex, itemContent) app
    click (listIndex, itemContent) listIndex Event will be triggered on index click. As an argument event handler receives list index instance and clicked index item content
    listIndexClick (listIndex, itemContent) app
    beforeDestroy (listIndex) listIndex Event will be triggered right before List Index instance will be destroyed. As an argument event handler receives list index instance
    listIndexBeforeDestroy (listIndex) app

    List Index Auto Initialization

    If you don't need to use List Index API and your List Index is inside of the page and presented in DOM on moment of page initialization then it can be auto initialized with just adding additional list-index-init class:

    <!-- Add list-index-init class -->
    <div class="list-index list-index-init"></div>
    

    In this case if you need to access created List Index instance you can use the app.listIndex.get app method:

    var listIndex = app.listIndex.get('.list-index');
    
    var indexes = listIndex.indexes;
    // do something with indexes

    When using auto init you may need to pass additional parameters. you can set all available parameters via data- attributes on list index element:

    <div class="page">
      ...
    
      <!-- parameters set via data- attributes -->
      <div class="list-index"
        data-list-el=".contacts-list"
        data-label="true"
        data-indexes="auto"
      ></div>
    
      <div class="page-content">
        <div class="list contacts-list">
          ...
        </div>
      </div>
    </div>
    

    Examples

    <div class="page">
      <div class="navbar">
        ...
      </div>
    
      <!-- List index element -->
      <div class="list-index"></div>
    
      <div class="page-content">
    
        <!-- Contacts list -->
        <div class="list simple-list contacts-list">
          <div class="list-group">
            <ul>
              <li class="list-group-title">A</li>
              <li>Aaron</li>
              <li>Adam</li>
              ...
            </ul>
          </div>
          <div class="list-group">
            <ul>
              <li class="list-group-title">B</li>
              <li>Benjamin</li>
              <li>Blake</li>
              <li>Bobby</li>
            </ul>
          </div>
          <div class="list-group">
            <ul>
              <li class="list-group-title">C</li>
              <li>Caleb</li>
              <li>Callum</li>
              ...
            </ul>
          </div>
          ...
        </div>
      </div>
    </div>
    var app = new Framework7();
    
    var listIndex = app.listIndex.create({
      // ".list-index" element
      el: '.list-index',
      // List el where to look indexes and scroll for
      listEl: '.contacts-list',
      // Generate indexes automatically based on ".list-group-title" and ".item-divider"
      indexes: 'auto',
      // Scroll list on indexes click and touchmove
      scrollList: true,
      // Enable bubble label when swiping over indexes
      label: true,
    });