vuetify-dialog-promise

A Vue plugin with a Promise API for Vuetify dialogs and snackbar notifications.

Major and minor version history

* Version ^3.0.0: Vue 3 compatibility
* Version ^2.6.0: allows you to specify message.href in snackbars, linking to it when clicking on the text
* Version ^2.5.0: allows you to specify message.defaultValue in prompts, switches to v-card for snackbars, and updates
dependencies
* Version ^2.4.0: switches to v-chip for snackbars because they're more suitable, and makes it possible to display
multiple snackbars simultaneously.
* Version ^2.3.0: switches to v-btn for snackbars because a Vuetify update broke programmatic creation of non-absolute
snackbars. Also removes the close button; now snackbars can be closed by clicking on them.
* Version ^2.2.0: no longer uses snackbarParent property (snackbars mounted in calling component instance)
* Version ^2.1.0: accepts theme property / config param (see
Vuetify theme)
* Version ^2.0.0: requires Vuetify ^2.0.0
* Version ^1.0.0: requires Vuetify ^1.5.0

Description

Intended to be as straightforward to use as native browser dialogues, with the look and feel of Vuetify widgets and
sufficient flexibility to cover most use cases involving straightforward alerts, notifications, confirmations, and
prompts.

Adds the following methods to the Vue instance:

* $alert( message )
- An alert dialog. Returns Promise, resolved when the user accepts it.
- message can be a string, in which case it is displayed in a plain dialog with an "Accept" button, or an object
with any properties including { text, title?, dialogMaxWidth?, acceptText?, cancelText? } where title becomes
the dialog title, text becomes the message to display, and the other properties control the appearance and
behaviour of the dialog (see "Configurable properties" below). Also applies to $confirm and $prompt (see below).
* $confirm( message )
- A confirmation dialog. Returns Promise, resolved if the user accepts it, rejected if the user cancels it.
* $prompt( message )
- A prompt dialog. Returns Promise, resolved with user input if user accepts it, rejected if the user cancels it.
- An additional property message.defaultValue may be passed to the prompt
* $inform( message )
- Raises a snackbar notification in the default colour.
- message can be a string or an object with properties { text, color?, closeText?, snackbarX?, snackbarY?,
snackbarTimeout? } where text becomes the message to display, and the other properties control the appearance
and behaviour of the snackbar (see "Initialisation properties" below). Applies to $warn and $error also (see
below).
* $warn( message )
- Raises a snackbar notification in the warning colour.
* $error( message )
- Raises a snackbar notification in the error colour.

Features

* Button labels localised to a large variety of languages (pull requests welcome)
* Allows you to inject your own button labels, overriding the defaults
* Dialogue and snackbar messages are plain text only: markup is escaped to keep it XSS-safe. However, paragraph breaks
can be added with newline '\\n' characters in the message.
* Various features of the dialogues and snackbars are configurable with initialisation properties (e.g. dialog max
width, snackbar location, colour, duration)

Initialisation properties

Various properties can be configured by handing them to Vue.use in the options argument when installing the plugin.
(see Usage examples below).

All of these are optional and have reasonable defaults:

* locale {string}
- ISO locale identifier for the button labels. Over 30 locales are supported. To override, see the properties below.
* acceptText {string}
- Label for accept button in dialog
* cancelText {string}
- Label for cancel button in dialog
* closeText {string}
- Label for close button in snackbar message
* snackbarX {"left"|"center"|"right"}
- Position of snackbar message
* snackbarY {"top"|"bottom"}
- Position of snackbar message
* snackbarTimeout {integer}
- Snackbar duration in milliseconds
* dialogMaxWidth {integer}
- Max width of dialog in pixels
* theme {Object}
- Vuetify theme applied to dialogs

Usage examples

$3

To experiment with the plugin directly in the browser, refer to this online example.

$3

To install and configure (all init properties are optional, see "Initialisation properties" above for complete list):

``
import Vue from "vue";
import VuetifyDialogPromise from "vuetify-dialog-promise";

Vue.use( VuetifyDialogPromise, {
locale : "fi",
snackbarX : "left",
snackbarY : "bottom"
} );
`

$3

To use the plugin from inside your own component:

`
// Message with defaults
this.$alert( "Your mother is a hamster and your father smells of elderberries." );

// Confirmation with property overrides
this.$confirm( {
title : "Are you a witch?",
text : "Do you weigh less than a duck?",
acceptText : "I float",
cancelText : "I sink"
} ).then( y => this.burnTheWitch() ).catch( n => this.notAWitch() );

// Prompt for value
this.$prompt( "What is your quest?" ).then( quest =>
this.beginQuest( quest ).catch( n => {} );

// Snackbar notification with defaults
this.$inform( "We are the knights that say Ni." );

// Snackbar notification with overrides
this.$inform( { text : "My favourite colour is blue.", color : "blue" } );
`

Developer notes

A full demo is provided with the project. To use it, fork and clone the repository and use the following utilities:

$3

`
npm install
`

$3


`
npm run serve
`

$3

`
npm run build-bundle
`

$3

`
npm run build
`

$3

`
npm run test
`

$3

`
npm run test:unit
``

$3

See Configuration Reference.

Credits

* Localisations for the standard button labels are originally extracted from the
Dojo toolkit i18n.