Sheet Modal

    Sheet Modal is a special overlay type which is similar to Picker/Calendar's overlay. Such modal allows to create custom overlays with custom content

    Sheet Layout

    Sheet layout is pretty simple:

    <body>
      ...
      <!-- Sheet Modal Container -->
      <div class="sheet-modal">
        <!-- Sheet Modal Toolbar, optional -->
        <div class="toolbar">
          <div class="toolbar-inner">
            <div class="left"></div>
            <div class="right">
              <a href="#" class="link sheet-close">Done</a>
            </div>
          </div>
        </div>
        <!-- Sheet Modal Inner -->
        <div class="sheet-modal-inner">
          <!-- Sheet Modal content -->
          <div class="block">
            <p>Integer mollis nulla id nibh elementum finibus...</p>
          </div>
        </div>
      </div>
    
    </body>

    Sheet App Methods

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

    app.sheet.create(parameters)- create Sheet instance

    • parameters - object. Object with sheet parameters

    Method returns created Sheet's instance

    app.sheet.destroy(el)- destroy Sheet instance

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

    app.sheet.get(el)- get Sheet instance by HTML element

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

    Method returns Sheet's instance

    app.sheet.open(el, animate)- opens Sheet

    • el - HTMLElement or string (with CSS Selector). Sheet element to open.
    • animate - boolean. Open Sheet with animation.

    Method returns Sheet's instance

    app.sheet.close(el, animate)- closes Sheet

    • el - HTMLElement or string (with CSS Selector). Sheet element to close.
    • animate - boolean. Close Sheet with animation.

    Method returns Sheet's instance

    Sheet Parameters

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

    Parameter Type Default Description
    el HTMLElement Sheet element. Can be useful if you already have Sheet element in your HTML and want to create new instance using this element
    content string Full Sheet HTML layout string. Can be useful if you want to create Sheet element dynamically
    backdrop boolean Enables Sheet backdrop (dark semi transparent layer behind). By default it is true for MD theme and false for iOS theme
    scrollToEl HTMLElement
    string
    HTML element or string (with CSS selector) of element. If specified, then sheet will try to scroll page content to this element on open
    closeByBackdropClick boolean true When enabled, sheet will be closed on backdrop click
    closeByOutsideClick boolean false When enabled, sheet will be closed on when click outside of it
    animate boolean true Whether the Sheet should be opened/closed with animation or not. Can be overwritten in .open() and .close() methods
    on object Object with events handlers. For example:
    var sheet = app.sheet.create({
      content: '<div class="sheet-modal">...</div>',
      on: {
        opened: function () {
          console.log('Sheet opened')
        }
      }
    })

    Note that all following parameters can be used in global app parameters under sheet property to set defaults for all sheets. For example:

    var app = new Framework7({
      sheet: {
        closeByBackdropClick: false,
      }
    });

    Sheet Methods & Properties

    So to create Sheet we have to call:

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

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

    Properties
    sheet.app Link to global app instance
    sheet.el Sheet HTML element
    sheet.$el Dom7 instance with sheet HTML element
    sheet.backdropEl Backdrop HTML element
    sheet.$backdropEl Dom7 instance with backdrop HTML element
    sheet.params Sheet parameters
    sheet.opened Boolean prop indicating whether sheet is opened or not
    Methods
    sheet.open(animate) Open sheet. Where
    • animate - boolean (by default true) - defines whether it should be opened with animation
    sheet.close(animate) Close sheet. Where
    • animate - boolean (by default true) - defines whether it should be closed with animation
    sheet.destroy() Destroy sheet
    sheet.on(event, handler) Add event handler
    sheet.once(event, handler) Add event handler that will be removed after it was fired
    sheet.off(event, handler) Remove event handler
    sheet.off(event) Remove all handlers for specified event
    sheet.emit(event, ...args) Fire event on instance

    Control Sheet With Links

    It is possible to open and close required sheet (if you have them in DOM) using special classes and data attributes on links:

    • To open sheet we need to add "sheet-open" class to any HTML element (prefered to link)

    • To close sheet we need to add "sheet-close" class to any HTML element (prefered to link)

    • If you have more than one sheet in DOM, you need to specify appropriate sheet via additional data-sheet=".my-sheet" attribute on this HTML element

    According to above note:

    <!-- In data-sheet attribute we specify CSS selector of sheet we need to open -->
    <p><a href="#" data-sheet=".my-sheet" class="sheet-open">Open Sheet</a></p>
    
    <!-- And somewhere in DOM -->
    <div class="sheet-modal my-sheet">
      <div class="sheet-modal-inner">
        <!-- Link to close sheet -->
        <a class="link sheet-close">Close</a>
      </div>
    </div>
    
    

    Sheet Events

    Sheet will fire the following DOM events on sheet element and events on app and sheet instance:

    DOM Events

    Event Target Description
    sheet:open Sheet Element<div class="sheet"> Event will be triggered when Sheet starts its opening animation
    sheet:opened Sheet Element<div class="sheet"> Event will be triggered after Sheet completes its opening animation
    sheet:close Sheet Element<div class="sheet"> Event will be triggered when Sheet starts its closing animation
    sheet:closed Sheet Element<div class="sheet"> Event will be triggered after Sheet completes its closing animation

    App and Sheet Instance Events

    Sheet instance emits events on both self instance and app instance. App instance events has same names prefixed with popup.

    Event Arguments Target Description
    open sheet sheet Event will be triggered when Sheet starts its opening animation. As an argument event handler receives sheet instance
    sheetOpen sheet app
    opened sheet sheet Event will be triggered after Sheet completes its opening animation. As an argument event handler receives sheet instance
    sheetOpened sheet app
    close sheet sheet Event will be triggered when Sheet starts its closing animation. As an argument event handler receives sheet instance
    sheetClose sheet app
    closed sheet sheet Event will be triggered after Sheet completes its closing animation. As an argument event handler receives sheet instance
    sheetClosed sheet app
    beforeDestroy sheet sheet Event will be triggered right before Sheet instance will be destroyed. As an argument event handler receives sheet instance
    sheetBeforeDestroy sheet app

    Examples

    <body>
      ...
        <div class="page">
          <div class="navbar">
            <div class="navbar-inner">
              <!-- In data-sheet attribute we specify CSS selector of sheet we need to open-->
              <div class="title">Sheet Modal</div>
              <div class="right"><a class="link sheet-open" href="#" data-sheet=".my-sheet">Open Sheet</a></div>
            </div>
          </div>
          <div class="page-content">
            <div class="block">
              <!-- In data-sheet attribute we specify CSS selector of sheet we need to open-->
              <p><a class="link sheet-open" href="#" data-sheet=".my-sheet">Open Sheet</a></p>
              <!-- Link to close sheet-->
              <p><a class="link sheet-close" href="#" data-sheet=".my-sheet">Close Sheet</a></p>
              <p><a class="link dynamic-sheet" href="#">Create Dynamic Sheet</a></p>
            </div>
          </div>
        </div>
      ...
    
      <div class="sheet-modal my-sheet">
        <div class="toolbar">
          <div class="toolbar-inner">
            <div class="left"></div>
            <div class="right"><a class="link sheet-close" href="#">Done</a></div>
          </div>
        </div>
        <div class="sheet-modal-inner">
          <div class="block">
            <h4>Info</h4>
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ac diam ac quam euismod porta vel a nunc. Quisque sodales scelerisque est, at porta justo cursus ac.</p>
          </div>
        </div>
      </div>
    </body>
    var app = new Framework7();
    
    var $$ = Dom7;
    
    // DOM events for my-sheet sheet
    $$('.my-sheet').on('sheet:open', function (e, sheet) {
      console.log('my-sheet open');
    });
    $$('.my-sheet').on('sheet:opened', function (e, sheet) {
      console.log('my-sheet opened');
    });
    
    // Create dynamic Sheet
    var dynamicSheet = app.sheet.create({
      content: '<div class="sheet-modal">'+
                  '<div class="toolbar">'+
                    '<div class="toolbar-inner">'+
                      '<div class="left"></div>'+
                      '<div class="right">'+
                        '<a class="link sheet-close">Done</a>'+
                      '</div>'+
                    '</div>'+
                  '</div>'+
                  '<div class="sheet-modal-inner">'+
                    '<div class="block">'+
                      '<p>Sheet created dynamically.</p>'+
                      '<p><a href="#" class="link sheet-close">Close me</a></p>'+
                    '</div>'+
                  '</div>'+
                '</div>',
      // Events
      on: {
        open: function (sheet) {
          console.log('Sheet open');
        },
        opened: function (sheet) {
          console.log('Sheet opened');
        },
      }
    });
    // Events also can be assigned on instance later
    dynamicSheet.on('close', function (sheet) {
      console.log('Sheet close');
    });
    dynamicSheet.on('closed', function (sheet) {
      console.log('Sheet closed');
    });
    
    // Open dynamic sheet
    $$('.dynamic-sheet').on('click', function () {
      // Close inline sheet before
      app.sheet.close('.my-sheet');
    
      // Open dynamic sheet
      dynamicSheet.open();
    });