diff --git a/README.md b/README.md index d598e89b3..a7aba04b4 100644 --- a/README.md +++ b/README.md @@ -7,47 +7,49 @@ [![Scrutinizer](https://img.shields.io/scrutinizer/g/Godofbrowser/vuejs-dialog.svg?branch=master)](https://scrutinizer-ci.com/g/Godofbrowser/vuejs-dialog/?branch=master) [![npm](https://img.shields.io/npm/dt/vuejs-dialog.svg)]() -![Vuejs Dialog Plugin](./src/docs/img/html-enabled.png?raw=true "Vuejs Dialog Plugin example") -![Vuejs Dialog Plugin](./src/docs/img/demo.gif?raw=true "Vuejs Dialog Plugin usage demo") - +![Vuejs Dialog Plugin](./src/docs/img/html-enabled.png?raw=true 'Vuejs Dialog Plugin example') +![Vuejs Dialog Plugin](./src/docs/img/demo.gif?raw=true 'Vuejs Dialog Plugin usage demo') ## Demo [https://godofbrowser.github.io/vuejs-dialog/](https://godofbrowser.github.io/vuejs-dialog/) ## Important updates in version v1.x.x -1. Dialog will always resolve with an object. (i.e callback for proceed always will receive an object) -2. For directives usage, the object returned in (1) above will include a node. The node is the element the directive was bound to (see issue [#5](https://github.com/Godofbrowser/vuejs-dialog/issues/5) -3. Styles will have to be included explicitly as they have been extracted into a separate file (see issue [#28](https://github.com/Godofbrowser/vuejs-dialog/issues/28)) -4. If loader is enabled globally, and a dialog is triggered via a directive without a callback, the loader is ignored for clicks on proceed -5. Custom class injection on parent node (see issue [#25](https://github.com/Godofbrowser/vuejs-dialog/issues/25)) -6. Ability to register custom views. This allows for custom logic, custom buttons, etc (see issue [#13](https://github.com/Godofbrowser/vuejs-dialog/issues/13), [#14](https://github.com/Godofbrowser/vuejs-dialog/issues/14), [#33](https://github.com/Godofbrowser/vuejs-dialog/issues/33)) -7. For installation via __HTML script tag__ - * The library has been namespaced as it has been split into two. The main library which is the plugin and the mixin which is useful in custom components - * To this effect, the new way to install the plugin is slightly dufferent: `window.Vue.use(VuejsDialog.main.default)` - * And the mixin can be added to components like so: `mixins: [VuejsDialog.mixin.default, ...otherMixins]` + +1. Dialog will always resolve with an object. (i.e callback for proceed always will receive an object) +2. For directives usage, the object returned in (1) above will include a node. The node is the element the directive was bound to (see issue [#5](https://github.com/Godofbrowser/vuejs-dialog/issues/5) +3. Styles will have to be included explicitly as they have been extracted into a separate file (see issue [#28](https://github.com/Godofbrowser/vuejs-dialog/issues/28)) +4. If loader is enabled globally, and a dialog is triggered via a directive without a callback, the loader is ignored for clicks on proceed +5. Custom class injection on parent node (see issue [#25](https://github.com/Godofbrowser/vuejs-dialog/issues/25)) +6. Ability to register custom views. This allows for custom logic, custom buttons, etc (see issue [#13](https://github.com/Godofbrowser/vuejs-dialog/issues/13), [#14](https://github.com/Godofbrowser/vuejs-dialog/issues/14), [#33](https://github.com/Godofbrowser/vuejs-dialog/issues/33)) +7. For installation via **HTML script tag** + - The library has been namespaced as it has been split into two. The main library which is the plugin and the mixin which is useful in custom components + - To this effect, the new way to install the plugin is slightly dufferent: `window.Vue.use(VuejsDialog.main.default)` + - And the mixin can be added to components like so: `mixins: [VuejsDialog.mixin.default, ...otherMixins]` ## Installation #### HTML - ```html - // Include vuejs - - - // Include vuejs-dialog plugin - - - // only needed in custom components - - + +// Include vuejs-dialog plugin + + + // only needed in custom components + + - ``` +``` + #### Package Manager + ```javascript -// installation via npm +// installation via npm npm i -S vuejs-dialog // or @@ -60,18 +62,19 @@ yarn add vuejs-dialog // then // import into project -import Vue from "vue" -import VuejsDialog from "vuejs-dialog" -import VuejsDialogMixin from "vuejs-dialog/vuejs-dialog-mixin.min.js" // only needed in custom components +import Vue from 'vue'; +import VuejsDialog from 'vuejs-dialog'; +import VuejsDialogMixin from 'vuejs-dialog/vuejs-dialog-mixin.min.js'; // only needed in custom components // include the default style -import 'vuejs-dialog/vuejs-dialog.min.css' +import 'vuejs-dialog/dist/vuejs-dialog.min.css'; // Tell Vue to install the plugin. -Vue.use(VuejsDialog) +Vue.use(VuejsDialog); ``` #### Webpack External + ```javascript // If you're including via script tag and importing as Webpack external // Webpack config @@ -83,15 +86,16 @@ Vue.use(VuejsDialog) } } ``` + ```javascript // then // import into project -import Vue from "vue" -import VuejsDialog from "vuejs-dialog" +import Vue from 'vue'; +import VuejsDialog from 'vuejs-dialog'; // Tell Vue to install the plugin. -Vue.use(VuejsDialog.main.default) +Vue.use(VuejsDialog.main.default); // mixin available at: VuejsDialog.mixin.default ``` @@ -102,47 +106,48 @@ Vue.use(VuejsDialog.main.default) // Anywhere in your Vuejs App. // Trigger an Alert dialog -this.$dialog.alert('Request completed!') - .then(function (dialog) { - console.log('Closed') - }) - +this.$dialog.alert('Request completed!').then(function(dialog) { + console.log('Closed'); +}); + // Trigger a confirmation dialog -this.$dialog.confirm('Please confirm to continue') - .then(function (dialog) { - console.log('Clicked on proceed') - }) - .catch(function () { - console.log('Clicked on cancel') - }); +this.$dialog + .confirm('Please confirm to continue') + .then(function(dialog) { + console.log('Clicked on proceed'); + }) + .catch(function() { + console.log('Clicked on cancel'); + }); ``` ## Basic Usage outside a vuejs application + ```javascript // VuejsDialog Methods are also available on the global vue // This makes it possible to use the plugin inside a ReactJs application // or just any javascript application // Simply include vue, vuejs-dialog, ask vue to use the plugin and that's all: -Vue.dialog.alert('Request completed!') - .then(function (dialog) { - console.log('Closed') - }) - -Vue.dialog.confirm('Please confirm to continue') - .then(function (dialog) { - console.log('Clicked on proceed') - }) - .catch(function () { - console.log('Clicked on cancel') - }); +Vue.dialog.alert('Request completed!').then(function(dialog) { + console.log('Closed'); +}); + +Vue.dialog + .confirm('Please confirm to continue') + .then(function(dialog) { + console.log('Clicked on proceed'); + }) + .catch(function() { + console.log('Clicked on cancel'); + }); ``` ## Return value on success ```javascript // Whenever a user clicks on proceed, -// the promise returned by the dialog call will be +// the promise returned by the dialog call will be // resolved with a dialog object with the following shape: @@ -158,8 +163,8 @@ Vue.dialog.confirm('Please confirm to continue') ``` @@ -213,11 +218,12 @@ __If you don't pass a message, the global/default message would be used.__ // Which is useful for closing the dialog when transaction is complete. ``` + ```javascript methods: { makeAdmin: function() { // Do stuffs - + }, doNothing: function() { // Do nothing or some other stuffs @@ -225,29 +231,30 @@ methods: { } ``` -__A more practical use of ths `v-confirm` directive with multiple triggers - Solution 1__ +**A more practical use of ths `v-confirm` directive with multiple triggers - Solution 1** ```html // While looping through users ``` + ```javascript methods: { makeAdmin: function(dialog, user) { // Make user admin from the backend /* tellServerToMakeAdmin(user) */ - + // When completed, close the dialog /* dialog.close() */ - + }, doNothing: function() { // Do nothing or some other stuffs @@ -255,8 +262,7 @@ methods: { } ``` - -__( new ) A more practical use of ths `v-confirm` directive with multiple triggers - Solution 2__ +**( new ) A more practical use of ths `v-confirm` directive with multiple triggers - Solution 2** ```html // While looping through users @@ -264,25 +270,26 @@ __( new ) A more practical use of ths `v-confirm` directive with multiple trigge :data-user="user" v-confirm="{ loader: true, - ok: makeAdmin, - cancel: doNothing, + ok: makeAdmin, + cancel: doNothing, message: 'User will be given admin privileges. Make user an Admin?'}" > Make Admin ``` + ```javascript methods: { makeAdmin: function(dialog) { let button = dialog.node // node is only available if triggered via a directive let user = button.dataset.user - + // Make user admin from the backend /* tellServerToMakeAdmin(user) */ - + // When completed, close the dialog /* dialog.close() */ - + }, doNothing: function() { // Do nothing or some other stuffs @@ -290,12 +297,11 @@ methods: { } ``` -__For v-confirm directive, if an "OK" callback is not provided, the default event would be triggered.__ +**For v-confirm directive, if an "OK" callback is not provided, the default event would be triggered.** ```html // Default Behaviour when used on links Go to example.com - ``` ## Setting a dialog title (new) @@ -305,15 +311,15 @@ The message object should contain a `title` and `body` ```javascript let message = { - title: 'Vuejs Dialog Plugin', - body: 'A lightweight, promise based alert, prompt and confirm dialog' -} + title: 'Vuejs Dialog Plugin', + body: 'A lightweight, promise based alert, prompt and confirm dialog' +}; -this.$dialog.confirm(message) +this.$dialog.confirm(message); ``` - ## Options + ```javascript // Parameters and options @@ -330,7 +336,7 @@ let options = { verification: 'continue', // for hard confirm, user will be prompted to type this to enable the proceed button verificationHelp: 'Type "[+:verification]" below to confirm', // Verification help text. [+:verification] will be matched with 'options.verification' (i.e 'Type "continue" below to confirm') clicksCount: 3, // for soft confirm, user will be asked to click on "proceed" btn 3 times before actually proceeding - backdropClose: false // set to true to close the dialog when clicking outside of the dialog window, i.e. click landing on the mask + backdropClose: false // set to true to close the dialog when clicking outside of the dialog window, i.e. click landing on the mask customClass: '' // Custom class to be injected into the parent node for the current dialog instance }; @@ -342,19 +348,21 @@ this.$dialog.confirm(message, options) // This will be triggered when user clicks on cancel }); ``` + ## Global Configuration + ```javascript // You can also set all your defaults at the point of installation. // This will be your global configuration // use VuejsDialog.main.default if including via script tag -Vue.use(VuejsDialog, { - html: true, - loader: true, - okText: 'Proceed', - cancelText: 'Cancel', - animation: 'bounce', -}) +Vue.use(VuejsDialog, { + html: true, + loader: true, + okText: 'Proceed', + cancelText: 'Cancel', + animation: 'bounce' +}); // Please note that local configurations will be considered before global configurations. // This gives you the flexibility of overriding the global config on individual call. @@ -363,25 +371,28 @@ Vue.use(VuejsDialog, { ## CSS Override If you have included the plugin's style and wish to make a few overides, you can do so with basic css, ex: + ```css .dg-btn--ok { - border-color: green; - } - + border-color: green; +} + .dg-btn-loader .dg-circle { - background-color: green; + background-color: green; } ``` ## Useful tip for customization + You can use any of the options in your verification help text. Example: ```javascript this.$dialog.confirm($message, { - verificationHelp: 'Enter "[+:verification]" below and click on "[+:okText]"', - type: 'hard' -}) + verificationHelp: 'Enter "[+:verification]" below and click on "[+:okText]"', + type: 'hard' +}); ``` + ## More flexibility with Custom components ```vue @@ -409,60 +420,58 @@ this.$dialog.confirm($message, { - ``` ```javascript -import Vue from 'vue' -import CustomView from './path/to/file/custom-component.vue' +import Vue from 'vue'; +import CustomView from './path/to/file/custom-component.vue'; -const VIEW_NAME = 'my-unique-view-name' -Vue.dialog.registerComponent(VIEW_NAME, CustomView) +const VIEW_NAME = 'my-unique-view-name'; +Vue.dialog.registerComponent(VIEW_NAME, CustomView); let vm = new Vue({ - methods: { - showCustomView(){ - // Note: Use confirm instead of alert if you need to handle rejection - this.$dialog.alert(trans('messages.html'), { - view: VIEW_NAME, // can be set globally too - html: true, - animation: 'fade', - backdropClose: true - }) - } + methods: { + showCustomView() { + // Note: Use confirm instead of alert if you need to handle rejection + this.$dialog.alert(trans('messages.html'), { + view: VIEW_NAME, // can be set globally too + html: true, + animation: 'fade', + backdropClose: true + }); } -}) + } +}); ``` - ... and you get your custom view - +... and you get your custom view -![Vuejs Dialog Plugin](./src/docs/img/custom-view.png?raw=true "Vuejs Dialog Plugin custom view demo") +![Vuejs Dialog Plugin](./src/docs/img/custom-view.png?raw=true 'Vuejs Dialog Plugin custom view demo') [Here's a working fiddle for custom component/view](http://jsfiddle.net/godofbrowser/pktL3mjb/) @@ -472,8 +481,8 @@ let vm = new Vue({ ## Contributing -* Fork it! -* Create your feature branch: git checkout -b my-new-feature -* Commit your changes: git commit -am 'Add some feature' -* Push to the branch: git push origin my-new-feature -* Submit a pull request :) +- Fork it! +- Create your feature branch: git checkout -b my-new-feature +- Commit your changes: git commit -am 'Add some feature' +- Push to the branch: git push origin my-new-feature +- Submit a pull request :)