diff --git a/README.md b/README.md index 9fb0257f..fbb3f078 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,11 @@ # Vue.js modal -Simple to use, highly customizable, mobile-friendly Vue.js modal with SSR support. +Easy to use, highly customizable Vue.js modal library. + +### 😎 [Examples](http://vue-js-modal.yev.io/) + +### 🤓 [Documentation](https://euvl.github.io/vue-js-modal/) [![npm version](https://badge.fury.io/js/vue-js-modal.svg)](https://badge.fury.io/js/vue-js-modal) [![npm](https://img.shields.io/npm/dm/vue-js-modal.svg)](https://www.npmjs.com/package/vue-js-modal) @@ -14,14 +18,6 @@ Version 2.0.0 release candidates will have breaking changes until it is 2.0.1. I If you notice any bugs or regressings please do not hesitate to report any issues. -# Sponsorship & support - -**If you are using this project please consider sponsorting it's further development & bug fixes** - -Links: https://github.com/sponsors/euvl, https://www.buymeacoffee.com/yev - - -

screen shot 2018-03-01 at 10 33 39 @@ -32,426 +28,15 @@ Links: https://github.com/sponsors/euvl, https://www.buymeacoffee.com/yev

-Demo: http://vue-js-modal.yev.io/ - -### Install - -```bash -npm install vue-js-modal --save -``` - -### How to use - -Include plugin in your `main.js` file. - -```javascript -import VModal from 'vue-js-modal' - -Vue.use(VModal) - -/* -By default, the plugin will use "modal" name for the component. -If you need to change it, you can do so by providing "componentName" param. - -Example: - -Vue.use(VModal, { componentName: "foo-modal" }) -... - -*/ -``` - -Or as a Nuxt.js plugin: - -##### plugins/vue-js-modal.js - -```javascript -import Vue from 'vue' -import VModal from 'vue-js-modal' - -Vue.use(VModal) -``` - -##### nuxt.config.js - -```javascript -export default { - plugins: [ - {src: '~/plugins/vue-js-modal', mode: 'client'}, - ] -``` - -Create modal: - -```vue - - hello, world! - -``` -Call it from anywhere in the app: - -```javascript -methods: { - show () { - this.$modal.show('hello-world'); - }, - hide () { - this.$modal.hide('hello-world'); - } -} -``` --- -You can easily send data into the modal: - -```javascript -this.$modal.show('hello-world', { foo: 'bar' }) -``` - -And receive it in `beforeOpen` event handler: - -```vue - -``` -```javascript -methods: { - beforeOpen (event) { - console.log(event.params.foo); - } -} -``` - -If you use **Bower** package manager - you will have to initialize library differently: - -```js -Vue.use(window["vue-js-modal"].default); -``` - -### Dialog - -It is a simplified version of the modal, which has most parameters set by default and is pretty useful for quick prototyping, showing alerts or creating mobile-like modals. - -To start using `` you must set `dialog: true` in plugin configuration: - -```js -Vue.use(VModal, { dialog: true }) -``` - -And include it in your project: - -```vue - -``` - -Call it (all params except of “text” are optional): - -```javascript -this.$modal.show('dialog', { - title: 'Alert!', - text: 'You are too awesome', - buttons: [ - { - title: 'Deal with it', - handler: () => { alert('Woot!') } - }, - { - title: '', // Button title - default: true, // Will be triggered by default if 'Enter' pressed. - handler: () => {} // Button click handler - }, - { - title: 'Close' - } - ] -}) -``` - -

- -

- -### Dynamic Modals - -In order to instantiate modals at runtime (for lazy-loading or decluttering templates), it is possible to create modals dynamically. - -To start using this feature you must set `dynamic: true` in plugin configuration: - -```js -Vue.use(VModal, { dynamic: true, dynamicDefaults: { clickToClose: false } }) -``` - -Call it (the first argument is the component definition, the second are component properties, the third modal parameters, and the fourth the modal event listeners): - -```javascript -this.$modal.show({ - template: ` -
-

This is created inline

-

{{ text }}

-
- `, - props: ['text'] -}, { - text: 'This text is passed as a property' -}, { - height: 'auto' -}, { - 'before-close': (event) => { console.log('this will be called before the modal closes'); } -}) -``` - -It can also be used with `.vue` files: - -```javascript -import MyComponent from './MyComponent.vue' - -this.$modal.show(MyComponent, { - text: 'This text is passed as a property' -}, { - draggable: true -}) -``` - -Other than defining the `name` modal parameter, it's also possible to close dynamic modals emitting a `'close'` event: - -```javascript -this.$modal.show({ - template: ` -
-

Close using this button:

- -
- ` -}) -``` - -It is possible to set default property values for dynamic modals. - -Example: - -```javascript - -import VueJsModal from 'plugin' - -Vue.use(VueJsModal, { - dynamic: true, - dynamicDefaults: { - foo: 'foo' - } -}) -``` - -```javascript -{ - showDynamicRuntimeModal () { - this.$modal.show({ - template: ` -
-

{{ text }}

-

Default Property: {{ foo }} - value is "foo"

-
- `, - props: ['text', 'foo'] - }, { - text: 'This text is passed as a property' - }) - }, -} -``` - - -For more examples please take a look at [vue-js-modal.yev.io](http://vue-js-modal.yev.io). - -**Note:** keep in mind that there are some limitations in using dynamic modals. If you need full functionality then use ordinary modal instead. - -### Properties - -| Name | Required | Type | Default | Description | -| --- | --- | --- | --- | --- | -| name | true | [String, Number] | | Name of the modal | -| delay | false | Number | 0 | Delay between showing overlay and actual modal box | -| resizable | false | Boolean | false | If true allows resizing the modal window, keeping it in the center of the screen. | -| adaptive | false | Boolean | false | If true, modal box will try to adapt to the window size | -| draggable | false | [Boolean, String]| false | If true, modal box will be draggable. If string, a selector to use as a handle for dragging | -| scrollable | false | Boolean | false | If `height` property is `auto` and the modal height exceeds window height - you will be able to scroll modal | -| reset | false | Boolean | false | Resets position and size before showing modal | -| focus-trap | false | Boolean | false | Enable focus trap (plugin uses naive implementation of the focus trap) | -| clickToClose | false | Boolean | true | If set to `false`, it will not be possible to close modal by clicking on the background | -| transition | false | String | | Transition name | -| overlayTransition | false | String | 'overlay-fade'| Transition name for the background overlay | -| classes | false | [String, Array] | '' | Classes that will be applied to the modal box | -| styles | false | [String, Array, Object] | | Style that will be applied to the modal box (currently only supports strings)| -| width | false | [String, Number] | 600 | Width in pixels or percents (e.g. 50 or "50px", "50%") | -| height | false | [String, Number] | 300 | Height in pixels or percents (e.g. 50 or "50px", "50%") or `"auto"` | -| minWidth | false | Number (px) | 0 | The minimum width to which modal can be resized | -| minHeight | false | Number (px) | 0 | The minimum height to which modal can be resized | -| maxWidth | false | Number (px) | Infinity | The maximum width of the modal (if the value is greater than window width, window width will be used instead | -| maxHeight | false | Number (px) | Infinity | The maximum height of the modal (if the value is greater than window height, window height will be used instead | -| pivotX | false | Number (0 - 1.0) | 0.5 | Horizontal position in %, default is 0.5 (meaning that modal box will be in the middle (50% from left) of the window | -| pivotY | false | Number (0 - 1.0) | 0.5 | Vertical position in %, default is 0.5 (meaning that modal box will be in the middle (50% from top) of the window | - -### Events - -| Name | Description | -| --- | --- | -| before-open | Emits while modal is still invisible, but was added to the DOM | -| opened | Emits after modal became visible or started transition | -| before-close | Emits before modal is going to be closed. Can be stopped from the event listener calling `event.cancel()` (example: you are creating a text editor, and want to stop closing and ask the user to correct mistakes if the text is not valid) -| closed | Emits right before modal is destroyed | - -Example: -```vue - - -``` - -Example with a dynamic modal: -```vue - -``` - -This example initializes `time` variable every time the modal is being opened. -And then forbids closing it for the next 5000 ms - -### Other - -#### Height: "auto" - -From `v1.2.6` height can be set to "auto". If you want to be able to scroll modal in case it's height exceeds window height - you can set flag `scrollable="true"`. - -p.s. `scrollable` will only work with `height="auto"`. - -Example: - -```vue -... -``` - -Auto height: - -

- -

- -Scrollable content & auto height: - -

- -

- - -#### Close button - -If you want to have a Close (x) button in the top-right corner, you can use "top-right" slot for it. There is deliberately no predefined Close button style - you will have to implement/use your own button. - -Example: -```vue - -``` - - -#### Draggable handler - -Draggable property can accept not only `Boolean` but also `String` parameters. With `String` value, you can specify a CSS selector to the element which will be a "handler" for dragging. - -Example: - -```vue - -
DRAG ME HERE
-
-     Hello, 🌎! -
- -``` +# Sponsorship & support -#### IE support +**If you are using this project please consider sponsorting it's further development & bug fixes** -To be able to use this plugin in IE you need to make sure that you transpile the code preoperty. Please read this stackoverflow: https://stackoverflow.com/questions/56446904/transpiling-es6-for-ie11-with-babel +Links: https://github.com/sponsors/euvl, https://www.buymeacoffee.com/yev -### Check out +### Other projects Check out my other projects: @@ -460,41 +45,5 @@ Check out my other projects: * https://github.com/euvl/vue-js-popover * https://github.com/euvl/v-clipboard -### Developers - -To run an example: -```sh -# Clone repo -git clone https://github.com/euvl/vue-js-modal.git - -# Run unit tests -npm run unit - -# Run linter -npm run lint - -# Build main library for client & SSR -cd vue-js-modal -npm install -npm run build - -# Build and run demo -cd demo -npm install -npm run dev -``` - -### Unit Testing in Vue 2.0 using Jest - -Include the plugin to your `.spec.js`. - -For example: If you're using the plugin in your `Main` component, then you should include the plugin to your `Main.spec.js` file. - -``` -import VModal from 'vue-js-modal' - -Vue.use(VModal) -``` - > **This library is contributor-driven**. It is not backed by any company, which means that all contributions are voluntary and done by the people who need them. If you need something improved, added, or fixed, please contribute it yourself. Please keep in mind that maintainers volunteer their free time to work on this project and have no obligation to reply on the issues, tailor library for specific use-cases or perform customer support.