Multiple Process Loader Management for Vue and (optionally) Vuex.

component name, you can set `my-loader` etc. registerDirective: true, // Registers `v-waiting` directive directiveName: 'waiting', // directive name, you can set `my-loader` etc. }), }); ``` ## ♻️ Usage with Vuex Simply set `useVuex` parameter to `true` and optionally override `vuexModuleName` ```js import VueWaiting from 'vue-waiting' Vue.use(Vuex) Vue.use(VueWaiting) // add VueWaiting as Vue plugin ``` Then you should register `VueWaiting` module: ```js new Vue({ el: '#app', store, waiting: new VueWaiting({ useVuex: true, // You must pass this option `true` to use Vuex vuexModuleName: 'vuex-example-module' // It's optional, `waiting` by default. }), }); ``` Now `VueWaiting` will use `Vuex` store for data management which can be traced in `Vue DevTools > Vuex` ## ♻️ Usage with Nuxt.js Add `vue-waiting/nuxt` to modules section of `nuxt.config.js` ```js export default { modules: [ // Simple usage 'vue-waiting/nuxt', // Optionally passing options in module configuration ['vue-waiting/nuxt', { useVuex: true }] ], // Optionally passing options in module top level configuration waiting: { useVuex: true } } ``` ## 🔁 `VueWaiting` Options You can use this options for customize VueWaiting behavior. | Option Name | Type | Default | Description | | ----------- | ---- | ------- | ----------- | | `accessorName` | `String` | `"$waiting"` | You can change this value to rename the accessor. E.g. if you rename this to `$w`, your `VueWaiting` methods will be accessible by `$w.waits(..)` etc. | | `useVuex` | `Boolean` | `false` | Use this value for enabling integration with `Vuex` store. When this value is true `VueWaiting` will store data in `Vuex` store and all changes to this data will be made by dispatching actions to store | | `vuexModuleName` | `String` | `"waiting"` | Name for `Vuex` store if `useVuex` set to true, otherwise not used. | | `registerComponent` | `Boolean` | `true` | Registers `v-waiting` component. | | `componentName` | `String` | `"v-waiting"` | Changes `v-waiting` component name. | | `registerDirective` | `Boolean` | `true` | Registers `v-waiting` directive. | | `directiveName` | `String` | `"v-waiting"` | Changes `v-waiting` directive name. | > If you change the property name, typescript will not understand your custom property. so you have to manually add below to your `shims-vue.d.ts` at the root of your project. ### VueJs standalone ```typescript // shims-vue.d.ts import VueWaiting from 'vue-waiting'; declare module 'vue/types/vue' { interface Vue { $custmProperty: VueWaiting; $custmProperty: VueWaiting; } } declare module 'vue/types/options' { interface ComponentOptions { customProperty?: VueWaiting; customProperty?: VueWaiting; } } ``` ### Working with `NuxtJs` ```typescript // shims-vue.d.ts import VueWaiting from 'vue-waiting'; declare module '@nuxt/types' { interface Context { $customProperty: VueWaiting; $customProperty: VueWaiting; } interface NuxtAppOptions { $customProperty: VueWaiting; $customProperty: VueWaiting; } } ``` ## 🌈 Global Template Helpers **vue-waiting** provides some helpers to you to use in your templates. All features can be obtained from $waiting property in Vue components. #### `.any` Returns boolean value if any loader exists in page. ```vue ``` #### `.is(loader String | Matcher)` or `.waiting(loader String | Matcher)` Returns boolean value if given loader exists in page. ```vue ``` You can use **`waiting`** alias instead of **`is`**. ```vue ``` Also you can use matcher to make it more flexible: Please see [matcher](https://github.com/sindresorhus/matcher/) library to see how to use matchers. ```vue ``` #### `.is(loaders Array)` or `.waiting(loaders Array)` Returns boolean value if some of given loaders exists in page. ```vue ``` #### `.start(loader String)` Starts the given loader. ```vue ``` #### `.end(loader String)` Stops the given loader. ```vue ``` #### `.progress(loader String, current [, total = 100])` Sets the progress of the given loader. ```vue ``` ##### Completing the Progress To complete the progress, `current` value should be set bigger than `100`. If you `total` is given, `current` must be bigger than `total`. ```vue Set as downloaded (101 of 100) ``` or ```vue Set as downloaded (6 of 5) ``` #### `.percent(loader String)` Returns the percentage of the given loader. ```vue ``` ## 🏹 Directives You can use directives to make your template cleaner. #### `v-waiting:visible='"loader name"'` Shows if the given loader is loading. ```vue ``` #### `v-waiting:hidden='"loader name"'` or `v-waiting:visible.not='"loader name"'` Hides if the given loader is loading. ```vue ``` #### `v-waiting:disabled='"loader name"'` Sets `disabled="disabled"` attribute to element if the given loader is loading. ```vue ``` #### `v-waiting:enabled='"loader name"'` or `v-waiting:disabled.not='"loader name"'` Removes `disabled="disabled"` attribute to element if the given loader is loading. ```vue ``` #### `v-waiting:click.start='"loader name"'` Starts given loader on click. ```vue ``` #### `v-waiting:click.end='"loader name"'` Ends given loader on click. ```vue ``` #### `v-waiting:toggle='"loader name"'` Toggles given loader on click. ```vue ``` #### `v-waiting:click.progress='["loader name", 80]'` Sets the progress of given loader on click. ```vue ``` ## 🔌 Loading Action and Getter Mappers **vue-waiting** provides `mapWaitingActions` and `mapWaitingGetters` mapper to be used with your Vuex stores. Let's assume you have a store and async **action**s called `createUser` and `updateUser`. It will call the methods you map and will start loaders while action is resolved. ```js import {mapWaitingActions, mapWaitingGetters} from 'vue-waiting' export default { methods: { ...mapWaitingActions('users', { getUsers: 'loading users', createUser: 'creating user', updateUser: 'updating user', }), }, computed: { ...mapWaitingGetters({ somethingWithUsers: [ 'loading users', 'creating user', 'updating user', ], deletingUser: 'deleting user', }), } } // ... ``` You can also map **action** to custom method and customize loader name like in example below: ```js import {mapWaitingActions, mapWaitingGetters} from 'vue-waiting' // ... export default { methods: { ...mapWaitingActions('users', { getUsers: { action: 'getUsers', loader: 'loading users' }, createUser: { action: 'createUser', loader: 'creating user' }, createSuperUser: { action: 'createUser', loader: 'creating super user' }, }), }, } // ... ``` There is also possibility to use array as a second argument to mapWaitingActions: ```js // ... export default { methods: { ...mapWaitingActions('users', [ 'getUsers', { method: 'createUser', action: 'createUser', loader: 'creating user' }, { method: 'createSuperUser', action: 'createUser', loader: 'creating super user' }, ]), }, } // ... ``` ### ☢️Advanced Getters and Actions Usage > The Vuex module name is `waiting` by default. If you've changed on config, you should get it by `rootGetters['/is']` or `rootGetters['/any']`. You can access `vue-waiting`'s Vuex getters using `rootGetters` in Vuex. ```js export default { getters: { cartOperationInProgress(state, getters, rootState, rootGetters) { return rootGetters['waiting/is']('cart.*'); } }, } ``` And you can start and end loaders using `waiting` actions. You must pass `root: true` option to the `dispatch` method. ```js export default { actions: { async addItemToCart({ dispatch }, item) { dispatch('waiting/start', 'cart.addItem', { root: true }); await CartService.addItem(item); dispatch('waiting/end', 'cart.addItem', { root: true }); } }, } ``` #### `waitFor(loader String, func Function [,forceSync = false])` Decorator that wraps function, will trigger a loading and will end loader after the original function (`func` argument) is finished. By default `waitFor` return async function, if you want to wrap default sync function pass `true` in last argument _Example using with async function_ ```js import {waitFor} from 'vue-waiting'; // ... export default { methods: { fetchDataFromApi: waitFor('fetch data', async function () { function sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); } // do work here await sleep(3000); // simulate some api call this.fetchResponse = Math.random() }) } } // ... ``` See also `examples/wrap-example` ## 💧 Using `v-waiting` Component If you disable `registerComponent` option then import and add `v-waiting` into components ```js import vLoading from 'vue-waiting/src/components/v-waiting.vue' export default { components: { 'v-waiting': vLoading } } ``` In template, you should wrap your content with `v-waiting` component to show loading on it. ```vue ``` Better example for a `button` with loading state: ```vue ``` ## 🔁 Transitions You can use transitions with `v-waiting` component. Just pass `` props and listeners to the `v-waiting` with `transition` prop. ```vue ``` ## ⚡️ Making Reusable Loader Components With reusable loader components, you will be able to use custom loader components as example below. This will allow you to create better **user loading experience**. In this example above, the **tab gets data from back-end**, and the **table loads data from back-end at the same time**. With **vue-waiting**, you will be able to manage these two seperated loading processes easily: ```vue ``` You may want to design your own reusable loader for your project. You better create a wrapper component called `my-waiter`: ```vue kh: loading: កំពុងទាញ... en: loading: Loading... ``` Now you can use your spinner everywhere using `slot='waiting'` attribute: ```vue ``` ## 📦 Using with external spinner libraries You can use `vue-waiting` with another spinner libraries like [epic-spinners](https://github.com/epicmaxco/epic-spinners) or other libraries. You just need to add `slot="waiting"` to the component and Vue handles rest of the work. First register the component, ```js import { OrbitSpinner } from 'epic-spinners'; Vue.component('orbit-spinner', OrbitSpinner); ``` Then use it in your as a `v-waiting`'s `waiting` slot. ```vue ``` ... and done! For other libraries you can use, please see [Loaders section of ** vuejs/awesome-vue**](https://github.com/vuejs/awesome-vue#loader). ## 🚌 Run example Use `npm run vuex:dev`, `npm run vue:dev` or `npm run wrap:dev` or `npm run transition:dev` commands. for running examples locally. ## ✔ Testing components You can test components using `vue-waiting` but it requires the configuration. Let's take a basic component for instance: ```vue ``` ```js const localVue = createLocalVue(); localVue.use(Vuex); // optionally when you use Vuex integration it('uses vue-waiting component', () => { const wrapper = shallowMount(Suggestions, {localVue}); expect(wrapper.find('.suggestions').exists()).toBeTruthy(); }); ``` `vue-test-utils` will replace `v-waiting` component with an empty `div`, making it difficult to test correctly. First, make your local Vue instance use `vue-waiting`, ```js const localVue = createLocalVue(); localVue.use(Vuex); // optionally when you use Vuex integration localVue.use(VueWaiting); ``` Then inject the `waiting` property using `VueWaiting` constructor, ```js it('uses vue-waiting component', () => { const wrapper = shallowMount(SuggestedAddresses, { localVue, waiting: new VueWaiting() }); expect(wrapper.find('.suggestions').exists()).toBeTruthy(); // it works! }); ``` ## 🎯 Contributors - Chantouch Sek, (writer) ## 🔑 License MIT © [Chantouch Sek](https://github.com/Chantouch/vue-waiting/blob/main/LICENSE)