xmodal-vue14 v0.1.0

🎉 Xmodal-Vue

get rid of those ugly 💩 predefined modals

xmodal will let you define custom components and show them as modal. YOUR APP YOUR RULE!. very simple and easy

this little component comes with customization tools that will make your life a little bit easier.

📗 installation : npm i xmodal-vue or yarn add xmodal-vue

📕 How to use : as a plugin:

import Vue from "vue";
import xmodal from "xmodal-vue";

// install xmodal
Vue.use(xmodal);

for single component:

import xmodal from "xmodal-vue";

export default {
	components: {
		xmodal
	}
	------
}

create modal:

<xmodal v-model="isModal" :params="your options here" />

xmodal can have 2 props as input.

• 1- params
• 2- v-model

📝 Params

params prop is an object that will pass data to the modal. you can see available options for params in the list below.

⚠️ you need to specify a component for each modal instance. all other options are not necessary

📝 v-model

you can bind xmodal to a boolean value and control it. this boolean value can be a vuex getter, a function etc... it's an optional property.

💡 How to use this in your project : you have to use this modal in routes not inside of other components. and you only need one instance on each route. ✅ for example you can do something like this:

<template>
	<div id="#app">
		 <!-- your code here -->
		<xmodal />
	</div>
</template>

❌ and this is wrong and not supported

<template>
	<div id="#app">
		 <!-- your code here -->
		<xmodal v-model="modal1" />
		<xmodal v-model="modal2"/>
	</div>
</template>

⚠️ you can open different modals with just one instance, so you don't need to create multiple instances for multiple modals!

also, every modal that you creating, needs a default params as options. this params will act as a parent for all other modals that you going to create in that specific page

example: app.vue

<template>
    <div id="app">
		<h1>Toilet Paper</h1>
        <button @click="isModal = !isModal">Open my Modal now !</button>
        <xmodal :params="options" />
    </div>
</template>


<script>
export default {
    name: "App",
    data() {
        return {
            isModal: false,
			
			// basic modal options
            options: {
                component: require("./components/no.vue").default,
                backgroundColor: "#000000",
                opacity: "0.7",
                animation: "scaleLeft",
            }
        };
    }
};
</script>

Params prop options

• components

  you need to pass a reference of your component to modal. in that way modal can render your component on the page.

params: {
	// you have to require it like this !
	component: require("./components/no.vue").default,
}

🔴 Don't forget to add .default to end of your require function. if you don't put .default at the end of require, xmodal can't render your component and show it on the page!!

• backgroundColor and opacity

  you can control modal backdrop color and opacity like this:

params: {
	opacity: "0.5" // need to be between 0 - 1
	backgroundColor: "#00fffdf"
}

• animations

  you can set animations for modal by defining its name

• hasTimer

  it will set a timer based on seconds for your modal hasTimer comes with an indicator on top of the page default color is white. 🟢 hasTimer can be a number,string or object. if you want to change indicator color you can pass an object for hasTimer.

example:

params: {
	hasTimer: "10s"  // 10 seconds as string
	hasTimer: 10 // 10 seconds as number
	
	// customize indicator
	hasTimer: {
		duration: 10    // you can send String too !
		color: "#00ff4d" // change color of indicator
	}
}

• props

  you can send props to component that you mounted to show as modal.

params: {
	props: {
		firstName: "myName",
		lastName: "Senpai"
		....
		// more props
	} 
}

you can send props to the component, as many as you want.

• isDisable

  you can disable modal click events to preventing users to close the modal. 🟢 isDisable is useful when you want to close modal based on some condition. ( like : checking if input is correct or etc... )

example:

params: {
	isDisable: true // prevent user click
}

⚠️ hasTimer will not work with isDisable

Global Methods

you have access to 2 global methods for controlling the modal instance. you can call them by calling this.$xmodal

• this.$xmodal.open(params)

  this is where you can open multiple modals ! open function can take params as its argument.

by default, open() is inheriting from default options. you can overwrite it, by passing options that you want to change

💡 for example we want to open new modal on click with default options

<template>
    <div id="app">
        <button @click="Open">Open modal with global fnction</button>
        <xmodal :params="options" />
    </div>
</template>

		
<script>
export default {
    name: "App",
    data() {
        return {
            // default options
            options: {
                component: require("./components/no.vue").default,
                backgroundColor: "#000000",
                opacity: "0.7",
                animation: "scaleLeft",
                props: {
                    name: "Mahdi Fakhr",
                    text: "Onii-chan help me"
                },
                hasTimer: "10s"
            }
        };
    },
    methods: {
        Open() {
            this.$xmodal.open({
				// change default component and show new one
                component: require("./components/newComponent.vue").default,
            })
        }
    }
};
</script>

you literally can open new modals by this.modal.open() with brand new options, or customize it based on default options

🔴 Don't forget params in this.$xmodal.open() accept an object

• this.$xmodal.close()

  it will close all open modals in current view(route) at once

like:

<template>
    <div id="app">
        <img alt="Modal logo" src="./assets/Modal.png" />
        <button @click="Close">Open modal with global fnction</button>
		<h1>i'm about to end this man's whole career !</h1>
    </div>
</template
		
<script>
export default {
    name: "close",
    methods: {
        Close() {
            this.$xmodal.close();
        }
    }
};
</script>

Modal shortkeys

there are some shortcuts that you can use to modify xmodal

feel free to fork or edit this project