Dialog

    Dialog is a small content pane that pops up over App's main content. Dialogs are usualy used to ask something from a user, or to notify or warn a user. Dialog, as all other modals, is part of so called "Temporary Views".

    Dialog can only be opened by using JavaScript. So lets look at related App methods to work with dialogs.

    Dialog App Methods

    Lets look at related App methods to work with Dialog:

    app.dialog.create(parameters)- create Dialog instance

    • parameters - object. Object with dialog parameters

    Method returns created Dialog's instance

    app.dialog.destroy(el)- destroy Dialog instance

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

    app.dialog.get(el)- get Dialog instance by HTML element

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

    Method returns Dialog's instance

    app.dialog.open(el, animate)- opens Dialog

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

    Method returns Dialog's instance

    app.dialog.close(el, animate)- closes Dialog

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

    Method returns Dialog's instance

    Dialog Parameters

    Now lets look at list of available parameters we need to create Dialog:

    Parameter Type Default Description
    el HTMLElement Dialog element. Can be useful if you already have Dialog element in your HTML and want to create new instance using this element
    backdrop boolean true Enables Dialog backdrop (dark semi transparent layer behind)
    closeByBackdropClick boolean true When enabled, dialog will be closed on backdrop click
    animate boolean true Whether the Dialog should be opened/closed with animation or not. Can be overwritten in .open() and .close() methods
    title string Dialog title
    text string Dialog inner text
    content string Custom Dialog content that follows dialog text
    buttons array [] Array with dialog buttons
    verticalButtons boolean false Enables vertical buttons layout
    destroyOnClose boolean false When enabled will automatically destroy Dialog on close
    onClick function(dialog, index) Callback function that will be executed after click on the Dialog button. As an arguments it received dialog instance and clicked button index number
    cssClass string Additional css class to add
    on object Object with events handlers. For example:
    var dialog = app.dialog.create({
      text: 'Hello World',
      on: {
        opened: function () {
          console.log('Dialog opened')
        }
      }
    })

    Button Parameters

    Each Button in buttons array must be presented as object with button parameters:

    Parameter Type Default Description
    text string String with Button's text (could be HTML string)
    bold boolean false Enables bold button text
    color string Button color, one of default colors
    close boolean true If enabled then button click will close Dialog
    cssClass string Additional button CSS class
    keyCodes array [] Array with keyboard keycodes that will be used to trigger button click. For example, key code 13 means that button click will be triggered on Enter key press
    onClick function(dialog, e) Callback function that will be executed after click on this button

    Dialog Methods & Properties

    So to create a Dialog we have to call:

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

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

    Properties
    dialog.app Link to global app instance
    dialog.el Dialog HTML element
    dialog.$el Dom7 instance with dialog HTML element
    dialog.backdropEl Backdrop HTML element
    dialog.$backdropEl Dom7 instance with backdrop HTML element
    dialog.params Dialog parameters
    dialog.opened Boolean prop indicating whether dialog is opened or not
    Methods
    dialog.open(animate) Open dialog. Where
    • animate - boolean (by default true) - defines whether it should be opened with animation
    dialog.close(animate) Close dialog. Where
    • animate - boolean (by default true) - defines whether it should be closed with animation
    dialog.setProgress(progress, duration) Sets dialog progress when Dialog Progress shortcut in use
    • progress - number - progressbar progress (from 0 to 100)
    • duration - number (in ms) - progressbar progress change duration
    dialog.setTitle(title) Sets dialog's title
    • title - string - new dialog title
    dialog.setText(text) Sets dialog's text
    • title - string - new dialog text
    dialog.destroy() Destroy dialog
    dialog.on(event, handler) Add event handler
    dialog.once(event, handler) Add event handler that will be removed after it was fired
    dialog.off(event, handler) Remove event handler
    dialog.off(event) Remove all handlers for specified event
    dialog.emit(event, ...args) Fire event on instance

    Dialog Events

    Dialog will fire the following DOM events on dialog element and events on app and dialog instance:

    DOM Events

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

    App and Dialog Instance Events

    Dialog instance emits events on both self instance and app instance. App instance events has same names prefixed with dialog.

    Event Arguments Target Description
    open dialog dialog Event will be triggered when Dialog starts its opening animation. As an argument event handler receives dialog instance
    dialogOpen dialog app
    opened dialog dialog Event will be triggered after Dialog completes its opening animation. As an argument event handler receives dialog instance
    dialogOpened dialog app
    close dialog dialog Event will be triggered when Dialog starts its closing animation. As an argument event handler receives dialog instance
    dialogClose dialog app
    closed dialog dialog Event will be triggered after Dialog completes its closing animation. As an argument event handler receives dialog instance
    dialogClosed dialog app
    beforeDestroy dialog dialog Event will be triggered right before Dialog instance will be destroyed. As an argument event handler receives dialog instance
    dialogBeforeDestroy dialog app

    Dialog Shortcuts

    There are a few shortcut methods which that make creating dialogs much easier.

    First lets check the global app parameters which help to configure such shortcuts and also used for localization purposes.

    Dialog Shortcuts Parameters

    The following global dialog shortcut parameters can be passed on app initialization under dialog property:

    var app = new Framework7({
      dialog: {
        // set default title for all dialog shortcuts
        title: 'My App',
        // change default "OK" button text
        buttonOk: 'Done',
        ...
      }
    });
    Parameter Type Default Description
    title string Default dialogs shortcuts title. If not specified, will be equal to app.name
    buttonOk string OK Default "OK" button text
    buttonCancel string Cancel Default "Cancel" button text
    usernamePlaceholder string Username Default username field placeholder in Login dialog
    passwordPlaceholder string Password Default password field placeholder in Login & Password dialogs
    preloaderTitle string Loading... Default title for Preloader dialog
    progressTitle string Loading... Default title for Progress dialog
    destroyPredefinedDialogs boolean true Will automatically destroy all predefined dialogs (Alert, Confirm, Prompt, etc.) on close
    keyboardActions boolean true Enables keyboard shortcuts (Enter and Esc) keys for predefined dialogs (Alert, Confirm, Prompt, Login, Password) "Ok" and "Cancel" buttons

    Now lets look at available dialog shortcuts

    Alert

    To create Alert dialog we need to use the following app methods:

    app.dialog.alert(text, title, callback)- create Alert Dialog and open it

    • text - string. Alert dialog text
    • title - string. Alert dialog title
    • callback - function. Optional. Callback function that will be executed after user clicks on Alert button

    Method returns created Dialog's instance

    app.dialog.alert(text, callback)- create Alert Dialog with default title and open it

    Method returns created Dialog's instance

    Confirm

    Confirm dialog is usualy used when it is required to confirm some action. To open the Confirm modal we should also call one of the following App methods:

    app.dialog.confirm(text, title, callbackOk, callbackCancel)- create Confirm Dialog and open it

    • text - string. Confirm dialog text
    • title - string. Confirm dialog title
    • callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button on Confirm dialog (when user confirms action)
    • callbackCancel - function. Optional. Callback function that will be executed when user click "Cancel" button on Confirm dialog (when user dismisses action)

    Method returns created Dialog's instance

    app.dialog.confirm(text, callbackOk, callbackCancel)- create Confirm Dialog with default title and open it

    Method returns created Dialog's instance

    Prompt

    Prompt dialog is used when it is required to get some data/answer from user. To open Prompt dialog we should also call one of the following App methods:

    app.dialog.prompt(text, title, callbackOk, callbackCancel, defaultValue)- create Prompt Dialog and open it

    • text - string. Prompt dialog text
    • title - string. Prompt dialog title
    • callbackOk - function(value). Optional. Callback function that will be executed when user click "Ok" button on Prompt dialog. As an argument function receives value of text input
    • callbackCancel - function(value). Optional. Callback function that will be executed when user click "Cancel" button on Prompt dialog. As an argument function receives value of text input
    • defaultValue - string. Optional. Prompt input default value

    app.dialog.prompt(text, callbackOk, callbackCancel, defaultValue)- create Prompt Dialog with default title and open it

    Method returns created Dialog's instance

    Login

    app.dialog.login(text, title, callbackOk, callbackCancel)- create Login Dialog and open it

    • text - string. Login dialog text
    • title - string. Login dialog title
    • callbackOk - function(username, password). Optional. Callback function that will be executed when user click "Ok" button on Login dialog. As an argument function receives username and password values
    • callbackCancel - function(username, password). Optional. Callback function that will be executed when user click "Cancel" button on Login dialog. As an argument function receives username and password values

    app.dialog.login(text, callbackOk, callbackCancel)- create Login Dialog with default title and open it

    Method returns created Dialog's instance

    Password

    Password dialog is useful in case you need to request only the password

    app.dialog.password(text, title, callbackOk, callbackCancel)- create Password Dialog and open it

    • text - string. Password dialog text
    • title - string. Password dialog title
    • callbackOk - function(password). Optional. Callback function that will be executed when user click "Ok" button on Password dialog. As an argument function receives password value
    • callbackCancel - function(password). Optional. Callback function that will be executed when user click "Cancel" button on Password dialog. As an argument function receives password value

    app.dialog.password(text, callbackOk, callbackCancel)- create Password Dialog with default title and open it

    Method returns created Dialog's instance

    Preloader

    Preloader dialog is used to indicate some background activity (like Ajax request) and to block any user actions during this activity. To open Preloader dialog we should also call appropriate App method:

    app.dialog.preloader(title, color)- create Preloader Dialog and open it

    • title - string. Optional. Preloader dialog title
    • color - string. Optional. Preloader color. One of the default colors

    Method returns created Dialog's instance

    Progress

    Same as Preloader dialog but with progressbar instead of preloader.

    app.dialog.progress(title, progress, color)- create Progress Dialog and open it

    • title - string. Optional. Progress dialog title
    • progress - number. Optional. Progressbar progress (from 0 to 100). If no number passed then it will have infinite progressbar.
    • color - string. Optional. Progressbar color. One of default colors

    Method returns created Dialog's instance

    Examples

    <body>
      ...
        <div class="page-content">
          <div class="block block-strong">
            <p class="row">
              <button class="col button open-alert">Alert</button>
              <button class="col button open-confirm">Confirm</button>
              <button class="col button open-prompt">Prompt</button>
            </p>
            <p class="row">
              <button class="col button open-login">Login</button>
              <button class="col button open-password">Password</button>
            </p>
          </div>
          <div class="block-title">Vertical Buttons</div>
          <div class="block block-strong">
            <p>
              <button class="button open-vertical">Vertical Buttons</button>
            </p>
          </div>
          <div class="block-title">Preloader Dialog</div>
          <div class="block block-strong">
            <p class="row">
              <button class="col button open-preloader">Preloader</button>
              <button class="col button open-preloader-custom">Custom Title</button>
            </p>
          </div>
          <div class="block-title">Progress Dialog</div>
          <div class="block block-strong">
            <p class="row">
              <button class="col button open-progress">Determined</button>
              <button class="col button open-progress-infinite">Infinite</button>
            </p>
          </div>
        </div>
      ...
    </body>
    var app = new Framework7();
    
    var $$ = Dom7;
    
    // Alert
    $$('.open-alert').on('click', function () {
      app.dialog.alert('Hello');
    });
    
    // Confirm
    $$('.open-confirm').on('click', function () {
      app.dialog.confirm('Are you feel good today?', function () {
        app.dialog.alert('Great!');
      });
    });
    
    // Prompt
    $$('.open-prompt').on('click', function () {
      app.dialog.prompt('What is your name?', function (name) {
        app.dialog.confirm('Are you sure that your name is ' + name + '?', function () {
          app.dialog.alert('Ok, your name is ' + name);
        });
      });
    });
    
    // Login
    $$('.open-login').on('click', function () {
      app.dialog.login('Enter your username and password', function (username, password) {
        app.dialog.alert('Thank you!<br>Username:' + username + '<br>Password:' + password);
      });
    });
    
    // Password
    $$('.open-password').on('click', function () {
      app.dialog.password('Enter your username and password', function (password) {
        app.dialog.alert('Thank you!<br>Password:' + password);
      });
    });
    
    // Vertical Buttons
    $$('.open-vertical').on('click', function () {
      app.dialog.create({
        title: 'Vertical Buttons',
        text: 'Dialog with vertical buttons',
        buttons: [
          {
            text: 'Button 1',
          },
          {
            text: 'Button 2',
          },
          {
            text: 'Button 3',
          },
        ],
        verticalButtons: true,
      }).open();
    });
    
    // Preloader
    $$('.open-preloader').on('click', function () {
      app.dialog.preloader();
      setTimeout(function () {
        app.dialog.close();
      }, 3000);
    });
    
    // Preloader with custom text
    $$('.open-preloader-custom').on('click', function () {
      app.dialog.preloader('My text...');
      setTimeout(function () {
        app.dialog.close();
      }, 3000);
    });
    
    // Progress
    $$('.open-progress').on('click', function () {
      var progress = 0;
      var dialog = app.dialog.progress('Loading assets', progress);
      dialog.setText('Image 1 of 10');
      var interval = setInterval(function () {
        progress += 10;
        dialog.setProgress(progress);
        dialog.setText('Image ' + ((progress) / 10) + ' of 10');
        if (progress === 100) {
          clearInterval(interval);
          dialog.close();
        }
      }, 300)
    });
    
    // Progress Infinite
    $$('.open-progress-infinite').on('click', function () {
      app.dialog.progress();
      setTimeout(function () {
        app.dialog.close();
      }, 3000);
    });