Modal
Modal is a small content pane that pops up over App's main content. Modals are usualy used to ask something from user, or to notify or warn user. Modal as all other overlays is part of so called "Temporary Views".
Modal can be opened only using JavaScript:
Predefined Modals
- Buttons text for predefined modals (like "Ok" and "Cancel") can be also changed by
$.modal.prototype.defaults
First of all, let's look on most used and already predefined modals in Framework7::
Alert
To open Alert modal we should call one of the following App methods:：$.alert(text, [title, callbackOk]) or $.alert(text, [callbackOk])
text - string. Text to alerttitle - string. Optional. Alert modal titlecallbackOk - function. Optional.Callback function that will be executed when user click "Ok" button on Alert modal
This method returns dynamically created modal's HTMLElement.
{% highlight html %}
...
...
{% endhighlight %}
{% highlight js %}
$(function(){
$(document).on('click','.alert-text',function () {
$.alert('Here goes alert text');
});
$(document).on('click','.alert-text-title', function () {
$.alert('Here goes alert text', 'Custom Title!');
});
$(document).on('click', '.alert-text-title-callback',function () {
$.alert('Here goes alert text', 'Custom Title!', function () {
$.alert('Button clicked!')
});
});
$(document).on('click', '.alert-text-callback',function () {
$.alert('Here goes alert text', function () {
$.alert('Button clicked!')
});
});
})
{% endhighlight %}
Confirm
Confirm modal usualy used when it is required to confirm some action. To open Confirm modal we should also call one of the following App methods:
$.confirm(text, [title, callbackOk, callbackCancel])
or
$.confirm(text, [callbackOk, callbackCancel])
text - string. Text to Confirmtitle - string. Optional. Confirm modal title- callbackOk - function. Optional. Callback function that will be executed when user click "Ok" button on Confirm modal (when user confirm action)
callbackCancel - function. Optional. Callback function that will be executed when user click "Cancel" button on Confirm modal (when user dismiss action)
{% highlight html %}
...
...
{% endhighlight %}
{% highlight js %}
$(document).on('click','.confirm-ok', function () {
$.confirm('Are you sure?', function () {
$.alert('You clicked Ok button');
});
});
$(document).on('click', '.confirm-ok-cancel',function () {
$.confirm('Are you sure?',
function () {
$.alert('You clicked Ok button');
},
function () {
$.alert('You clicked Cancel button');
}
);
});
$(document).on('click','.confirm-title-ok', function () {
$.confirm('Are you sure?', 'Custom Title', function () {
$.alert('You clicked Ok button');
});
});
$(document).on('click','.confirm-title-ok-cancel', function () {
$.confirm('Are you sure?', 'Custom Title',
function () {
$.alert('You clicked Ok button');
},
function () {
$.alert('You clicked Cancel button');
}
);
});
{% endhighlight %}
Prompt
Prompt modal used when it is required to get some data/answer from user. To open Prompt modal we should also call one of the following App methods:
$.prompt(text, [title, callbackOk, callbackCancel])
$.prompt(text, [callbackOk, callbackCancel])
text - string. Prompt text/questiontitle - string. Optional. Prompt modal TitlecallbackOk - function. Optional. OK button callback, As an argument function receives value of text inputcallbackCancel - function. Optional. calcel button callback
{% highlight html %}
...
...
{% endhighlight %}
{% highlight js %}
$(document).on('click','.prompt-ok', function () {
$.prompt('What is your name?', function (value) {
$.alert('Your name is "' + value + '". You clicked Ok button');
});
});
$(document).on('click','.prompt-ok-cancel', function () {
$.prompt('What is your name?',
function (value) {
$.alert('Your name is "' + value + '". You clicked Ok button');
},
function (value) {
$.alert('Your name is "' + value + '". You clicked Cancel button');
}
);
});
$(document).on('click', '.prompt-title-ok',function () {
$.prompt('What is your name?', 'Custom Title', function (value) {
$.alert('Your name is "' + value + '". You clicked Ok button');
});
});
$(document).on('click', '.prompt-title-ok-cancel',function () {
$.prompt('What is your name?', 'Custom Title',
function (value) {
$.alert('Your name is "' + value + '". You clicked Ok button');
},
function (value) {
$.alert('Your name is "' + value + '". You clicked Cancel button');
}
);
});
{% endhighlight %}
Modals
Ok, all predefined modals were just particular case (like shortcuts) of full Modal methods. Let's look how to create custom modals:
$.modal(parameters) - show custom modal
parameters - object. Parameters/options of modal
Here is the list of Modal parameters:
| Parameter |
Type |
Default |
Description |
| title |
string |
|
Optional. String with Modal title (could be HTML string) |
| text |
string |
|
Optional. String with Modal text (could be HTML string) |
| afterText |
string |
|
Optional. String with text (could be HTML string) that will be placed after "text" |
| buttons |
array |
|
Optional. Array of buttons. Each button should be presented as Object with button parameters (look below) |
| verticalButtons |
boolean |
false |
Optional. Set to true to enable vertical buttons layout |
| onClick |
function |
|
Optional. Callback function that will be executed when user clicks any of Modal's button. As arguments it receives modal (with Modal's HTMLElement) and index (with index number of clicked button) |
Let's look at Button's parameters:
| Parameter |
Type |
Default |
Description |
| text |
string |
|
String with Button's text (could be HTML string) |
| bold |
boolean |
false |
Optional. Set to true for bold button text |
| close |
boolean |
true |
Optional. If "true" then modal will be closed after click on this button |
| onClick |
function |
|
Optional. Callback function that will be executed when user click this button |
Such configuration options allows to create flexible modals. Let's look at some examples.
{% highlight html %}
...
...
{% endhighlight %}
{% highlight js %}
$(document).on('click','.open-3-modal', function () {
$.modal({
title: 'Modal with 3 buttons',
text: 'Vivamus feugiat diam velit. Maecenas aliquet egestas lacus, eget pretium massa mattis non. Donec volutpat euismod nisl in posuere. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae',
buttons: [
{
text: 'B1',
onClick: function() {
$.alert('You clicked first button!')
}
},
{
text: 'B2',
onClick: function() {
$.alert('You clicked second button!')
}
},
{
text: 'B3',
bold: true,
onClick: function() {
$.alert('You clicked third button!')
}
},
]
})
});
$(document).on('click','.open-slider-modal', function () {
var modal = $.modal({
title: 'Awesome Photos?',
text: 'What do you think about my photos?',
afterText: '',
buttons: [
{
text: 'Bad :('
},
{
text: 'Awesome!',
bold: true,
onClick: function () {
$.alert('Thanks! I know you like it!')
}
},
]
})
$.swiper($$(modal).find('.swiper-container'), {pagination: '.swiper-pagination'});
});
$(document).on('click','.open-tabs-modal', function () {
$.modal({
title: '',
text: ''+
'
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam convallis nunc non dolor euismod feugiat. Sed at sapien nisl. Ut et tincidunt metus. Suspendisse nec risus vel sapien placerat tincidunt. Nunc pulvinar urna tortor.
'+
'
Vivamus feugiat diam velit. Maecenas aliquet egestas lacus, eget pretium massa mattis non. Donec volutpat euismod nisl in posuere. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae
'+
'
Close Modals with JavaScript
Any Modal can be closed with JavaScript, not only by clicking on its buttons. For this we need to look at relate App method:
$.closeModal(modal) - close modal
modal - HTMLElement or string ( CSS Selector). Optional. If not specified, any opened modal will be closed
Modal Events
Modal events could be very useful when you need to do something in JavaScript when Modal opened/closed
| Event |
Target |
Description |
| open |
Modal Element<div class="modal"> |
Event will be triggered when Modal starts its opening animation |
| opened |
Modal Element<div class="modal"> |
Event will be triggered after Modal completes its opening animation |
| close |
Modal Element<div class="modal"> |
Event will be triggered when Modal starts its closing animation |
| closed |
Modal Element<div class="modal"> |
Event will be triggered after Modal completes its closing animation |
Preloader Modal
Preloader Modal is used to indicate some background activity (like Ajax request) and to block any user actions during this activity. To open Preloader modal we should also call appropriate App method: $.showPreloader([title]) - show modal with Preloader
title - string. Optional. Preloader modal title. By default (if not specified) it is euqal to "Loading...".
$.hidePreloader() - hide/close modal with Preloader. Because Preloader modal has not any buttons, it should be closed by JavaScript
{% highlight html %}
...
...
{% endhighlight %}
{% highlight js %}
$(document).on('click', '.open-preloader', function () {
$.showPreloader();
setTimeout(function () {
$.hidePreloader();
}, 2000);
});
$(document).on('click','.open-preloader-title', function () {
$.showPreloader('Custom Title')
setTimeout(function () {
$.hidePreloader();
}, 2000);
});
{% endhighlight %}
Indicator
If you don't need such "big" modal window like Preloader Modal to indicate activity, you can use simple and small indicator modal:
$.showIndicator() - show indicator modal
$.hideIndicator() - hide/close modal with Indicator. Because Indicator modal has not any buttons, it should be closed by JavaScript
{% highlight html %}
...
...
{% endhighlight %}
{% highlight js %}
$(document).on('click','.open-indicator', function () {
$.showIndicator();
setTimeout(function () {
$.hideIndicator();
}, 2000);
});
{% endhighlight %}
toast
Toast is a verfy light modal, It will not disturb user and will disapear after 3 seconds
{% highlight js %}
$.toast("Error!");
{% endhighlight %}
Popover
Popover compontent is used to manage the presentation of content in a popover. You use popovers to present information temporarily. The popover remains visible until the user taps outside of the popover window or you explicitly dismiss it.
Note that is not recommended to use Popover on small screens (iPhone). On small screens you should use Action Sheet.
Popover Layout
First of all let's look on Popover layout, it is pretty simple, just add somewhere in the end of the body:
{% highlight html %}
{% endhighlight %}
Open and close with HTML
It is possible to open and close required Popover using special classes and data attributes on links:
-
To open popover we need to add "open-popover" class to any HTML element (prefered to link)
-
To close popover we may add "close-popover" class to any HTML element (prefered to link)
-
If you have more than one popover in app, you need to specify appropriate popover via additional data-popover=".my-popover" attribute on this HTML element
When we open Popover with such method (from HTML), it will be automatically positioned around element that we clicked to call this Popover.
Open and close with JavaScript
We can also open and close Popover with JavaScript:
$.popover(popover, target) - open Popover around target element
popover - HTMLElement or string (with CSS Selector) of Popover to open. Requredtarget - HTMLElement or string (with CSS Selector) of target element to set popover position around this element. Requred- This method returns Popover's HTMLElement
$.closeModal(popover) - close Popover
popover - HTMLElement or string (with CSS Selector). Optional. If not specified, any opened Popover will be closed
Dynamic Popover
It allows you to create Popover dynamically by passing its HTML to related methods:
$.popover(popoverHTML, target, removeOnClose) - open Popover with popoverHTML content around target element
popoverHTML - string. HTML string of popover target - HTMLElement or string (with CSS Selector) of target element to set popover position around this element. RequredremoveOnClose - boolean. Optional, by default - true. If true then Popover will be removed from DOM when closed- This method returns dynamically created Popover's HTMLElement
Modal Defaults
The default config of modal is $.modal.prototype.defaults, you can change these config:
| Parameter |
Default |
Description |
| modalButtonOk |
"OK" |
Text of OK button |
| modalButtonCancel |
"Cancel" |
Text of cancel button |
| modalPreloaderTitle |
"Loading" |
Text of preloader |
| closePrevious |
true |
Close all previous modal when open a new modal. |
| actionsCloseByOutside |
true |
点击背景关闭 ActionSheet |
| modalCloseByOutside |
false |
点击背景关闭 Modal |
| popupCloseByOutside |
false |
点击背景关闭 Popup |