Popup

    Popup is a popup window with any HTML content that pops up over App's main content. Popup as all other overlays is part of so called "Temporary Views".

    Popup Layout

    Popup layout is pretty simple:

    <body>
      ...
      <div class="popup">
        Any HTML content goes here
      </div>
    </body>

    Popup Size

    By default Popup has a bit different size on phones and tablets (iPad). On phones it is fullscreen while on tablets it is 630px width and height. If you want to make it fullscreen size on tablets, you should add additional "popup-tablet-fullscreen" class to the required popup:

    <body>
      ...
      <!-- This popup has fullscreen size on tablets -->
      <div class="popup popup-tablet-fullscreen">
        Any HTML content goes here
      </div>
    </body>

    Popup App Methods

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

    app.popup.create(parameters)- create Popup instance

    • parameters - object. Object with popup parameters

    Method returns created Popup's instance

    app.popup.destroy(el)- destroy Popup instance

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

    app.popup.get(el)- get Popup instance by HTML element

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

    Method returns Popup's instance

    app.popup.open(el, animate)- opens Popup

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

    Method returns Popup's instance

    app.popup.close(el, animate)- closes Popup

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

    Method returns Popup's instance

    Popup Parameters

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

    Parameter Type Default Description
    el HTMLElement Popup element. Can be useful if you already have Popup element in your HTML and want to create new instance using this element
    content string Full Popup HTML layout string. Can be useful if you want to create Popup element dynamically
    backdrop boolean true Enables Popup backdrop (dark semi transparent layer behind)
    closeByBackdropClick boolean true When enabled, popup will be closed on backdrop click
    animate boolean true Whether the Popup 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 popup = app.popup.create({
      content: '<div class="popup">...</div>',
      on: {
        opened: function () {
          console.log('Popup opened')
        }
      }
    })

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

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

    Popup Methods & Properties

    So to create Popup we have to call:

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

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

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

    Control Popup With Links

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

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

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

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

    According to above note:

    <!-- In data-popup attribute we specify CSS selector of popup we need to open -->
    <p><a href="#" data-popup=".my-popup" class="popup-open">Open Popup</a></p>
    
    <!-- And somewhere in DOM -->
    <div class="popup my-popup">
      <div class="view">
        <div class="page">
          <div class="navbar">
            <div class="navbar-inner">
              <div class="title">Popup</div>
              <div class="right">
                <!-- Link to close popup -->
                <a class="link popup-close">Close</a>
              </div>
            </div>
          </div>
          <div class="page-content">
            ...
          </div>
        </div>
      </div>
      ...
    </div>
    
    

    Popup Events

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

    DOM Events

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

    App and Popup Instance Events

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

    Event Arguments Target Description
    open popup popup Event will be triggered when Popup starts its opening animation. As an argument event handler receives popup instance
    popupOpen popup app
    opened popup popup Event will be triggered after Popup completes its opening animation. As an argument event handler receives popup instance
    popupOpened popup app
    close popup popup Event will be triggered when Popup starts its closing animation. As an argument event handler receives popup instance
    popupClose popup app
    closed popup popup Event will be triggered after Popup completes its closing animation. As an argument event handler receives popup instance
    popupClosed popup app
    beforeDestroy popup popup Event will be triggered right before Popup instance will be destroyed. As an argument event handler receives popup instance
    popupBeforeDestroy popup app

    Examples

    <body>
      ...
        <div class="page-content">
          <div class="block">
            <!-- Open About Popup -->
            <p><a class="link popup-open" href="#" data-popup=".popup-about">Open About Popup</a></p>
            <!-- Open Services Popup -->
            <p><a class="link popup-open" href="#" data-popup=".popup-services">Open Services Popup</a></p>
            <p><a class="link dynamic-popup" href="#">Create Dynamic Popup</a></p>
          </div>
        </div>
      ...
      <div class="popup popup-about">
        <div class="block">
          <p>About</p>
          <!-- Close Popup -->
          <p><a class="link popup-close" href="#">Close popup</a></p>
          <p>Lorem ipsum dolor sit amet...</p>
        </div>
      </div>
      <div class="popup popup-services">
        <div class="block">
          <p>Services</p>
          <!-- Close Popup -->
          <p><a class="link popup-close" href="#">Close popup</a></p>
          <p>Lorem ipsum dolor sit amet...</p>
        </div>
      </div>
    </body>
    var app = new Framework7();
    
    var $$ = Dom7;
    
    // DOM events for About popup
    $$('.popup-about').on('popup:open', function (e, popup) {
      console.log('About popup open');
    });
    $$('.popup-about').on('popup:opened', function (e, popup) {
      console.log('About popup opened');
    });
    
    // Create dynamic Popup
    var dynamicPopup = app.popup.create({
      content: '<div class="popup">'+
                  '<div class="block">'+
                    '<p>Popup created dynamically.</p>'+
                    '<p><a href="#" class="link popup-close">Close me</a></p>'+
                  '</div>'+
                '</div>',
      // Events
      on: {
        open: function (popup) {
          console.log('Popup open');
        },
        opened: function (popup) {
          console.log('Popup opened');
        },
      }
    });
    // Events also can be assigned on instance later
    dynamicPopup.on('close', function (popup) {
      console.log('Popup close');
    });
    dynamicPopup.on('closed', function (popup) {
      console.log('Popup closed');
    });
    
    // Open dynamic popup
    $$('.dynamic-popup').on('click', function () {
      dynamicPopup.open();
    });