Pull To Refresh

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

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

    Where:

    • 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
    • data-ptr-mousewheel="true" additional attribute that enables pull to refresh with mousewheel (for desktop apps). Works only for PTR top.
    • ptr-watch-scrollable - additional class that must be added on nested scrollable elements to prevent pull to refresh on such elements scrolling
    • ptr-ignore - additional class that must be added on nested scrollable elements or other elements that will to prevent pull to refresh on such elements scrolling or touchmove

    Pull To Refresh From Bottom

    It is also possible to make it work like pull from bottom. In this case we need to move ptr-preloader element to the bottom of page content and add additional ptr-bottom class to pull to refresh content:

    1. <div class="page">
    2.   <!-- ptr-content must have additional "ptr-bottom" class -->
    3.   <div class="page-content ptr-content ptr-bottom">
    4.     <div class="list">
    5.       ...
    6.     </div>
    8.     <!-- Pull to refresh preloader moves to bottom -->
    9.     <div class="ptr-preloader">
    10.       <div class="ptr-arrow"></div>
    11.     </div>
    12.   </div>
    13. </div>

    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.

    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).

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

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

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

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

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

    Pull To Refresh Events

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

    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.

    Below is the list of related CSS variables (CSS custom properties).

    1. .ios {
    2.   --f7-ptr-preloader-size: 20px;
    3.   --f7-ptr-size: 44px;
    4. }
    5. .md {
    6.   --f7-ptr-preloader-size: 22px;
    7.   --f7-ptr-size: 40px;
    8. }
    9. .aurora {
    10.   --f7-ptr-preloader-size: 20px;
    11.   --f7-ptr-size: 38px;
    12. }

    Examples

    Pull From Top

    1. var app = new Framework7();
    4. // Dummy Content
    5. var songs = ['Yellow Submarine', 'Don\'t Stop Me Now', 'Billie Jean', 'Californication'];
    6. var authors = ['Beatles', 'Queen', 'Michael Jackson', 'Red Hot Chili Peppers'];
    7. // Pull to refresh content
    8. var $ptrContent = $$('.ptr-content');
    9. // Add 'refresh' listener on it
    10. $ptrContent.on('ptr:refresh', function (e) {
    11.   // Emulate 2s loading
    12.   setTimeout(function () {
    13.     var picURL = 'https://cdn.framework7.io/placeholder/abstract-88x88-' + (Math.floor(Math.random() * 10) + 1) + '.jpg';
    14.     var song = songs[Math.floor(Math.random() * songs.length)];
    15.     var author = authors[Math.floor(Math.random() * authors.length)];
    16.     var itemHTML =
    17.       '<li class="item-content">' +
    18.         '<div class="item-media"><img src="' + picURL + '" width="44"/></div>' +
    19.         '<div class="item-inner">' +
    20.           '<div class="item-title-row">' +
    21.             '<div class="item-title">' + song + '</div>' +
    22.           '</div>' +
    23.           '<div class="item-subtitle">' + author + '</div>' +
    24.         '</div>' +
    25.       '</li>';
    26.     // Prepend new list element
    27.     $ptrContent.find('ul').prepend(itemHTML);
    28.     // When loading done, we need to reset it
    29.     app.ptr.done(); // or e.detail();
    30. });

    Pull From Bottom