Toast
Toasts provide brief feedback about an operation through a message on the screen.
Toast App Methods
Let’s look at related App methods to work with Toast:
app.toast.create(parameters)- create Toast instance
- parameters - object. Object with toast parameters
Method returns created Toast’s instance
app.toast.destroy(el)- destroy Toast instance
- el - HTMLElement or string (with CSS Selector) or object. Toast element or Toast instance to destroy.
app.toast.get(el)- get Toast instance by HTML element
- el - HTMLElement or string (with CSS Selector). Toast element.
Method returns Toast’s instance
app.toast.open(el, animate)- opens Toast
- el - HTMLElement or string (with CSS Selector). Toast element to open.
- animate - boolean. Open Toast with animation.
Method returns Toast’s instance
app.toast.close(el, animate)- closes Toast
- el - HTMLElement or string (with CSS Selector). Toast element to close.
- animate - boolean. Close Toast with animation.
Method returns Toast’s instance
app.toast.show(parameters)- create Toast instance and show immediately
- parameters - object. Object with toast parameters
Method returns created Toast’s instance
Toast Parameters
Now let’s look at list of available parameters we need to create Toast:
Parameter | Type | Default | Description |
---|---|---|---|
el | HTMLElement | Toast element. Can be useful if you already have Toast element in your HTML and want to create new instance using this element | |
icon | string | Toast icon HTML layout, e.g. <i class=”f7-icons”>home</i> or image <img src=”path/to/icon.png”> | |
text | string | Toast inner text | |
position | string | bottom | Toast position. Can be bottom , center or top |
closeButton | boolean | false | Adds toast close button |
closeButtonColor | string | One of the default color themes | |
closeButtonText | string | Ok | Close button text |
closeTimeout | number | Timeout delay (in ms) to close toast automatically | |
cssClass | string | Additional css class to add | |
destroyOnClose | boolean | false | Destroys toast instance on close |
render | function | Custom function to render Toast. Must return toast html | |
on | object | Object with events handlers. For example:
|
Note that all following parameters can be used in global app parameters under toast
property to set defaults for all toasts. For example:
var app = new Framework7({
toast: {
closeTimeout: 3000,
closeButton: true,
}
});
Toast Methods & Properties
So to create Toast we have to call:
var toast = app.toast.create({ /* parameters */ })
After that we have its initialized instance (like toast
variable in example above) with useful methods and properties:
Properties | |
---|---|
toast.app | Link to global app instance |
toast.el | Toast HTML element |
toast.$el | Dom7 instance with toast HTML element |
toast.params | Toast parameters |
Methods | |
toast.open() | Open toast |
toast.close() | Close toast |
toast.on(event, handler) | Add event handler |
toast.once(event, handler) | Add event handler that will be removed after it was fired |
toast.off(event, handler) | Remove event handler |
toast.off(event) | Remove all handlers for specified event |
toast.emit(event, …args) | Fire event on instance |
Toast Events
Toast will fire the following DOM events on toast element and events on app and toast instance:
DOM Events
Event | Target | Description |
---|---|---|
toast:open | Toast Element<div class=”toast”> | Event will be triggered when Toast starts its opening animation |
toast:opened | Toast Element<div class=”toast”> | Event will be triggered after Toast completes its opening animation |
toast:close | Toast Element<div class=”toast”> | Event will be triggered when Toast starts its closing animation |
toast:closed | Toast Element<div class=”toast”> | Event will be triggered after Toast completes its closing animation |
App and Toast Instance Events
Toast instance emits events on both self instance and app instance. App instance events has same names prefixed with toast
.
Event | Arguments | Target | Description |
---|---|---|---|
closeButtonClick | toast | toast | Event will be triggered when user clicks on Toast close button. As an argument event handler receives toast instance |
toastCloseButtonClick | toast | app | |
open | toast | toast | Event will be triggered when Toast starts its opening animation. As an argument event handler receives toast instance |
toastOpen | toast | app | |
opened | toast | toast | Event will be triggered after Toast completes its opening animation. As an argument event handler receives toast instance |
toastOpened | toast | app | |
close | toast | toast | Event will be triggered when Toast starts its closing animation. As an argument event handler receives toast instance |
toastClose | toast | app | |
closed | toast | toast | Event will be triggered after Toast completes its closing animation. As an argument event handler receives toast instance |
toastClosed | toast | app | |
beforeDestroy | toast | toast | Event will be triggered right before Toast instance will be destroyed. As an argument event handler receives toast instance |
toastBeforeDestroy | toast | app |
Examples
<div class="block">
<p>
<a href="#" class="button button-raised open-toast-bottom">Toast on Bottom</a>
</p>
<p>
<a href="#" class="button button-raised open-toast-top">Toast on Top</a>
</p>
<p>
<a href="#" class="button button-raised open-toast-center">Toast on Center</a>
</p>
<p>
<a href="#" class="button button-raised open-toast-icon">Toast with icon</a>
</p>
<p>
<a href="#" class="button button-raised open-toast-large">Toast with large message</a>
</p>
<p>
<a href="#" class="button button-raised open-toast-button">Toast with close button</a>
</p>
<p>
<a href="#" class="button button-raised open-toast-custom-button">Toast with custom button</a>
</p>
<p>
<a href="#" class="button button-raised open-toast-callback">Toast with callback on close</a>
</p>
</div>
var app = new Framework7();
var $$ = Dom7;
// Create bottom toast
var toastBottom = app.toast.create({
text: 'This is default bottom positioned toast',
closeTimeout: 2000,
});
// Create top toast
var toastTop = app.toast.create({
text: 'Top positioned toast',
position: 'top',
closeTimeout: 2000,
});
// Create center toast
var toastCenter = app.toast.create({
text: 'I\'m on center',
position: 'center',
closeTimeout: 2000,
});
// Create toast with icon
var toastIcon = app.toast.create({
icon: app.theme === 'ios' ? '<i class="f7-icons">star</i>' : '<i class="material-icons">star</i>',
text: 'I\'m with icon',
position: 'center',
closeTimeout: 2000,
});
// Create toast with large message
var toastLargeMessage = app.toast.create({
text: 'This toast contains a lot of text. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nihil, quae, ab. Delectus amet optio facere autem sapiente quisquam beatae culpa dolore.',
closeTimeout: 2000,
});
// Create toast with button
var toastWithButton = app.toast.create({
text: 'Toast with additional close button',
closeButton: true,
});
// Create toast with custom button text
var toastWithCustomButton = app.toast.create({
text: 'Custom close button',
closeButton: true,
closeButtonText: 'Close Me',
closeButtonColor: 'red',
});
// Create toast with callback on close
var toastWithCallback = app.toast.create({
text: 'Callback on close',
closeButton: true,
on: {
close: function () {
app.dialog.alert('Toast closed');
},
}
});
// Open toasts
$$('.open-toast-bottom').on('click', function () {
toastBottom.open();
});
$$('.open-toast-top').on('click', function () {
toastTop.open();
});
$$('.open-toast-center').on('click', function () {
toastCenter.open();
});
$$('.open-toast-icon').on('click', function () {
toastIcon.open();
});
$$('.open-toast-large').on('click', function () {
toastLargeMessage.open();
});
$$('.open-toast-button').on('click', function () {
toastWithButton.open();
});
$$('.open-toast-custom-button').on('click', function () {
toastWithCustomButton.open();
});
$$('.open-toast-callback').on('click', function () {
toastWithCallback.open();
});