Sheet Modal

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