Pull To Refresh

    Pull to refresh is a special component that can be used to initiate the refreshing of a page’s contents.

    Pull To Refresh Layout

    Let's look on how to integrate pull to refresh to page:

    <div class="page">
      <!-- Page content must have additional "ptr-content" class -->
      <div class="page-content ptr-content" data-ptr-distance="55">
        <!-- Default pull to refresh preloader-->
        <div class="ptr-preloader">
          <div class="preloader"></div>
          <div class="ptr-arrow"></div>
        </div>
    
        <!-- usual content below -->
        <div class="list">
          ...
        </div>
    
        <!-- nested scrollable element -->
        <div class="my-scolling-content ptr-watch-scrollable">
          ...
        </div>
      </div>
    </div>

    Where:

    • ptr-content class. This is required to enable pull to refresh
    • div class="ptr-preloader" hidden layer with pull to refresh visual elements: preloader and arrow
    • data-ptr-distance="55" additional attribute that allows to set custom pull to refresh trigger distance. By default (if not specified) it is 44px
    • ptr-watch-scrollable - additional class that must be added on nested scrollable elements to prevent pull to refresh on such elements scrolling

    Pull To Refresh Sequence

    When user starts to pull ptr-content down, then ptr-preloader will receive additional ptr-pull-down class.

    When user pulls down ptr-content on a distance more than 44px (when ptr-preloader will be fully visible), then ptr-preloader will receive additional ptr-pull-up class which changes arrow rotation to notify user about refresh action on release.

    When user release pull to refresh content when it is in "ptr-pull-up" state, then ptr-preloader will receive additional ptr-refreshing class. In "refreshing" state arrow will be hidden and user will see preloader indicator. On this stage you probably need to do Ajax request and refresh page content.

    Pull To Refresh App Methods

    There are few App's methods that can be used with pull to refresh container:

    app.ptr.create(el)- initialise PTR on specified HTML element container.

    • el - HTMLElement or string (with CSS selector) - PTR element (ptr-content). Required.

    Method returns created PTR instance

    Use this method only in case you have added ptr content after page init or if you want to enable it later. Otherwise if there is "ptr-content" element on page init it will be created automatically

    app.ptr.destroy(el)- remove PTR event listeners from the specified HTML element

    • el - HTMLElement or string (with CSS selector) - PTR element (ptr-content). Required.

    app.ptr.get(el)- get PTR instance by HTML element

    • el - HTMLElement or string (with CSS Selector). PTR element (ptr-content).

    Method returns PTR instance

    app.ptr.done(el)- reset PTR state on specified PTR content element

    • el - HTMLElement or string (with CSS Selector). PTR element (ptr-content). Required.

    app.ptr.refresh(el)- trigger PTR on specified PTR content element

    • el - HTMLElement or string (with CSS Selector). PTR element (ptr-content). Required.

    Pull To Refresh Methods & Properties

    If we created PTR manually or used app.ptr.get method we will PTR initialized instance with useful methods and properties:

    // init ptr manually
    var ptr = app.ptr.create('.ptr-content');
    
    // or using get to retreive already created instance
    var ptr = app.ptr.get('.ptr-content');
    Properties
    ptr.app Link to global app instance
    ptr.el PTR HTML element (ptr-content)
    ptr.$el Dom7 instance with PTR HTML element (ptr-content)
    Methods
    ptr.done() Reset PTR state
    ptr.refresh() Trigger PTR
    ptr.destroy() Destroy PTR instance and remove PTR event listeners from the specified HTML element

    Pull To Refresh Events

    PTR will fire the following DOM events on popup element and events on app and popup instance:

    DOM Events

    Event Target Description
    ptr:pullstart Pull To Refresh content<div class="ptr-content"> Event will be triggered when you start to move pull to refresh content
    ptr:pullmove Pull To Refresh content<div class="ptr-content"> Event will be triggered during you move pull to refresh content
    ptr:pullend Pull To Refresh content<div class="ptr-content"> Event will be triggered when you release pull to refresh content
    ptr:refresh Pull To Refresh content<div class="ptr-content"> Event will be triggered when pull to refresh enters in "refreshing" state. event.detail contain ptr.done method to reset its state after loading completed
    ptr:done Pull To Refresh content<div class="ptr-content"> Event will be triggered after pull to refresh is done and it is back to initial state (after calling ptr.done method)
    ptr:beforedestroy Pull To Refresh content<div class="ptr-content"> Event will be triggered right before PTR instance will be destroyed

    App and Pull To Refresh Instance Events

    PTR instance emits events on both self instance and app instance. App instance events has same names prefixed with ptr.

    Event Target Arguments Description
    pullStart ptr (el) Event will be triggered when you start to move pull to refresh content. As an argument event handler receives ptr element
    ptrPullStart app (el)
    pullMove ptr (el, data) Event will be triggered when you start to move pull to refresh content. As an argument event handler receives ptr element and ptr data containing the following properties:
    • event - touchmove event
    • scrollTop - current scroll top position
    • translate - current translateY offset
    • touchesDiff - touches difference (in px)
    ptrPullMove app (el, data)
    pullEnd ptr (el, data) Event will be triggered when you release pull to refresh content. As an argument event handler receives ptr element
    ptrPullEnd app (el, data)
    refresh ptr (el, done) Event will be triggered when pull to refresh enters. As an argument event handler receives ptr element and done function to reset PTR state
    ptrRefresh app (el, done)
    done ptr (el) Event will be triggered right before PTR instance will be destroyed. As an argument event handler receives ptr element
    ptrDone app (el)
    beforeDestroy ptr (ptr) Event will be triggered right before PTR instance will be destroyed. As an argument event handler receives PTR instance
    ptrBeforeDestroy app (ptr)

    Example

    <div class="page-content ptr-content">
      <div class="ptr-preloader">
        <div class="preloader"></div>
        <div class="ptr-arrow"></div>
      </div>
      <div class="list media-list">
        <ul>
          <li class="item-content">
            <div class="item-media"><img src="http://lorempixel.com/88/88/abstract/1" width="44"/></div>
            <div class="item-inner">
              <div class="item-title-row">
                <div class="item-title">Yellow Submarine</div>
              </div>
              <div class="item-subtitle">Beatles</div>
            </div>
          </li>
          <li class="item-content">
            <div class="item-media"><img src="http://lorempixel.com/88/88/abstract/2" width="44"/></div>
            <div class="item-inner">
              <div class="item-title-row">
                <div class="item-title">Don't Stop Me Now</div>
              </div>
              <div class="item-subtitle">Queen</div>
            </div>
          </li>
          <li class="item-content">
            <div class="item-media"><img src="http://lorempixel.com/88/88/abstract/3" width="44"/></div>
            <div class="item-inner">
              <div class="item-title-row">
                <div class="item-title">Billie Jean</div>
              </div>
              <div class="item-subtitle">Michael Jackson</div>
            </div>
          </li>
        </ul>
      </div>
    </div>
    var app = new Framework7();
    
    var $$ = Dom7;
    
    // Dummy Content
    var songs = ['Yellow Submarine', 'Don\'t Stop Me Now', 'Billie Jean', 'Californication'];
    var authors = ['Beatles', 'Queen', 'Michael Jackson', 'Red Hot Chili Peppers'];
    // Pull to refresh content
    var $ptrContent = $$('.ptr-content');
    // Add 'refresh' listener on it
    $ptrContent.on('ptr:refresh', function (e) {
      // Emulate 2s loading
      setTimeout(function () {
        var picURL = 'http://lorempixel.com/88/88/abstract/' + Math.round(Math.random() * 10);
        var song = songs[Math.floor(Math.random() * songs.length)];
        var author = authors[Math.floor(Math.random() * authors.length)];
        var itemHTML =
          '<li class="item-content">' +
            '<div class="item-media"><img src="' + picURL + '" width="44"/></div>' +
            '<div class="item-inner">' +
              '<div class="item-title-row">' +
                '<div class="item-title">' + song + '</div>' +
              '</div>' +
              '<div class="item-subtitle">' + author + '</div>' +
            '</div>' +
          '</li>';
        // Prepend new list element
        $ptrContent.find('ul').prepend(itemHTML);
        // When loading done, we need to reset it
        app.ptr.done(); // or e.detail();
      }, 2000);
    });