Language: ENCN

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 should have additional "pull-to-refresh-content" class -->
  <div class="page-content pull-to-refresh-content" data-ptr-distance="55">
    <!-- Default pull to refresh layer-->
    <div class="pull-to-refresh-layer">
      <div class="preloader"></div>
      <div class="pull-to-refresh-arrow"></div>
    </div>
 
    <!-- usual content below -->
    <div class="list-block">
      ...
    </div>
  </div>
</div>   

Where

  • page-content should have additional pull-to-refresh-content class. This is required to enable pull to refresh
  • pull-to-refresh-layer 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.

Pull To Refresh Sequence

When user starts to pull pull-to-refresh-content down, then pull-to-refresh-layer will receive additional "pull-down" class.

When user pulls down pull-to-refresh-content on a distance more than 44px (when pull-to-refresh-layer will be fully visible), then pull-to-refresh-layer will receive additional "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 "pull-up" state, then pull-to-refresh-layer will receive additional "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 Events

There is a special JavaScript event that helps us to recognize when we need to refresh content:

Event Target Description
ptr:pullstart Pull To Refresh content<div class="pull-to-refresh-content"> Event will be triggered when you start to move pull to refresh content
ptr:pullmove Pull To Refresh content<div class="pull-to-refresh-content"> Event will be triggered during you move pull to refresh content
ptr:pullend Pull To Refresh content<div class="pull-to-refresh-content"> Event will be triggered when you release pull to refresh content
ptr:refresh Pull To Refresh content<div class="pull-to-refresh-content"> Event will be triggered when pull to refresh enters in "refreshing" state
ptr:done Pull To Refresh content<div class="pull-to-refresh-content"> Event will be triggered after pull to refresh is done and it is back to initial state (after calling pullToRefreshDone method)

Reset Pull To Refresh

After we refreshed page content, we need to reset pull to refresh component to let user pull it again:

myApp.pullToRefreshDone(ptrContent) - reset specified pull to refresh content

  • ptrContent - HTMLElement or string (with CSS Selector) of pull-to-refresh-content we need to reset

Trigger Pull To Refresh

We can also trigger Pull To Refresh manually by using the following method:

myApp.pullToRefreshTrigger(ptrContent) - trigger pull to refresh on specified pull to refresh content

  • ptrContent - HTMLElement or string (with CSS Selector) of pull-to-refresh-content we need to trigger

Example

<div class="page-content pull-to-refresh-content">
  <div class="pull-to-refresh-layer">
    <div class="preloader"></div>
    <div class="pull-to-refresh-arrow"></div>
  </div>
  <div class="list-block media-list">
    <ul>
      <li class="item-content">
        <div class="item-media"><img src="http://hhhhold.com/88/d/jpg?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>
      ...
    </ul>
    <div class="list-block-label">
      <p>Just pull page down to let the magic happen.</p>
    </div>
  </div>
</div>          
var myApp = 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 = $$('.pull-to-refresh-content');
 
// Add 'refresh' listener on it
ptrContent.on('ptr:refresh', function (e) {
    // Emulate 2s loading
    setTimeout(function () {
        // Random image
        var picURL = 'http://hhhhold.com/88/d/jpg?' + Math.round(Math.random() * 100);
        // Random song
        var song = songs[Math.floor(Math.random() * songs.length)];
        // Random author
        var author = authors[Math.floor(Math.random() * authors.length)];
        // List item html
        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
        myApp.pullToRefreshDone();
    }, 2000);
});

Destroy/Disable Pull To Refresh

Sometimes you may need to disable Pull To Refresh on page. We can do that using the following method:

myApp.destroyPullToRefresh(ptrContent) - destroy/disable pull to refresh on specified pull to refresh content

  • ptrContent - HTMLElement or string (with CSS Selector) of pull-to-refresh-content we need to disable

And if we need to initialize/enable it again:

myApp.initPullToRefresh(ptrContent) - initialize/enable pull to refresh

  • ptrContent - HTMLElement or string (with CSS Selector) of pull-to-refresh-content we need to enable