Framework7 v2
Support Framework7
stars forks
iOSAndroid
Improve this Doc

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
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();
});