|
| 1 | +## vuex-router-actions |
| 2 | + |
| 3 | +The library you've been waiting for to streamline complex Vuex actions and fast and secure routing in your app. |
| 4 | + |
| 5 | +## Goals |
| 6 | + |
| 7 | +- To make it easier to use Vuex actions. |
| 8 | +- To make it easier to produce apps which can load data asynchronously before being routed to a page and also check along the way whether that user can go to that page - and also what to do when they cannot. |
| 9 | +- To cache action results so traversing through an app is as efficient as possible. |
| 10 | +- To make it easier to track asynchronous actions and keep the user notified when the app is loading. |
| 11 | + |
| 12 | +## Features |
| 13 | + |
| 14 | +- Cache the results of an action based on logic or a cache key. |
| 15 | +- Listen to when actions are started, resolved, rejected, ended, and all pending actions are done. |
| 16 | +- Call a mutation with a flag on whether a set of actions are currently running. |
| 17 | +- Check the state of the store to determine whether an action can continue (subsequently a route). |
| 18 | +- Keep a routed Vue component from loading or updating until an action is finished. |
| 19 | +- If an action has exited because a user cannot visit a route, provide a way to redirect the user somewhere else. |
| 20 | +- Communicate to the user when one or more actions are being processed (makes it easy to create loading screens). |
| 21 | + |
| 22 | +## Contents |
| 23 | + |
| 24 | +- [Goals](#goals) |
| 25 | +- [Features](#features) |
| 26 | +- [Dependencies](#dependencies) |
| 27 | +- [Installation](#installation) |
| 28 | +- [API](#api) |
| 29 | + - [actionsWatch](#actionswatch) |
| 30 | + - [actionsLoading](#actionsloading) |
| 31 | + - [actionsCached](#actionscached) |
| 32 | + - [actionsCachedConditional](#actionscachedconditional) |
| 33 | + - [actionsProtect](#actionsprotect) |
| 34 | + - [actionBeforeRoute](#actionbeforeroute) |
| 35 | + - [actionOptional](#actionoptional) |
| 36 | + |
| 37 | +### Dependencies |
| 38 | + |
| 39 | +No build time dependencies, but this library is used in conjunction with `vuex` and optionally `vue-router`. |
| 40 | + |
| 41 | +### Installation |
| 42 | + |
| 43 | +#### npm |
| 44 | + |
| 45 | +Installation via npm : `npm install --save vuex-router-actions` |
| 46 | + |
| 47 | +## API |
| 48 | + |
| 49 | +#### actionsWatch |
| 50 | + |
| 51 | +Watches the given actions and invokes the callbacks passed in the options of `VuexRouterActions`. If the result of an action is a promise - it is watched and immediately invokes `onActionStart` followed by `onActionResolve` or `onActionReject` and then `onActionEnd`. If the result of an action is not a promise then `onActionStart` and `onActionEnd` are invoked immediately. If there are no more watched actions being executed then `onActionsDone` is invoked after the last `onActionEnd`. |
| 52 | + |
| 53 | +```javascript |
| 54 | +import VuexRouterActions, { actionsWatch } from 'vuex-router-actions' |
| 55 | +const plugin = VuexRouterActions({ |
| 56 | + onActionStart (action, num) {}, |
| 57 | + onActionEnd (action, num, result, resolved) {} |
| 58 | +}) |
| 59 | +const store = new Vuex.Store({ |
| 60 | + plugins: [plugin], |
| 61 | + actions: { |
| 62 | + ...actionsWatch({ |
| 63 | + loadThis (context, payload) {}, |
| 64 | + loadThat (context, payload) {} // return a Promise |
| 65 | + }) |
| 66 | + } |
| 67 | +}) |
| 68 | +``` |
| 69 | + |
| 70 | +#### actionsLoading |
| 71 | + |
| 72 | +Calls a mutation on a store when any of the passed actions are running and when they stop. This provides an easy way to signal to the user when something is loading, even a complex set of asynchronous actions. |
| 73 | + |
| 74 | +```javascript |
| 75 | +import { actionsLoading } from 'vuex-router-actions' |
| 76 | +const store = new Vuex.Store({ |
| 77 | + state: { |
| 78 | + loading: false |
| 79 | + }, |
| 80 | + mutations: { |
| 81 | + setLoading (state, loading) { |
| 82 | + state.loading = loading |
| 83 | + } |
| 84 | + }, |
| 85 | + actions: { |
| 86 | + ...actionsLoading('setLoading', { |
| 87 | + page1 (context, payload) {}, |
| 88 | + page2 (context, payload) {} |
| 89 | + }) |
| 90 | + } |
| 91 | +}) |
| 92 | +``` |
| 93 | + |
| 94 | +#### actionsCached |
| 95 | + |
| 96 | +Produces actions with cached results based on some cache key. The action will always run the first time unless the cache key returned `undefined`. The cached results of the action are "cleared" when a different key is returned for a given action. |
| 97 | + |
| 98 | +```javascript |
| 99 | +import { actionsCached } from 'vuex-router-actions' |
| 100 | +const store = new Vuex.Store({ |
| 101 | + actions: { |
| 102 | + ...actionsCached({ |
| 103 | + loadPage: { |
| 104 | + getKey: (context, payload) => payload, // look at store, getters, payload, etc |
| 105 | + handler: (context, payload) => null // some result that can be cached |
| 106 | + } |
| 107 | + }) |
| 108 | + } |
| 109 | +}) |
| 110 | +``` |
| 111 | + |
| 112 | +#### actionsCachedConditional |
| 113 | + |
| 114 | +Produces actions with cached results based on some condition. The action will always run the first time. |
| 115 | + |
| 116 | +```javascript |
| 117 | +import { actionsCachedConditional } from 'vuex-router-actions' |
| 118 | +const store = new Vuex.Store({ |
| 119 | + actions: { |
| 120 | + ...actionsCachedConditional({ |
| 121 | + loadPage: { |
| 122 | + isInvalid: (context, payload) => true, // look at store, getters, payload, etc |
| 123 | + handler: (context, payload) => null // some result that can be cached |
| 124 | + } |
| 125 | + }) |
| 126 | + } |
| 127 | +}) |
| 128 | +``` |
| 129 | + |
| 130 | +#### actionsProtect |
| 131 | + |
| 132 | +Creates "protection" actions. These are functions which return a truthy or falsy value and the action returned produces a Promise that is resolved or rejected. This is useful when creating actions which load data for a route. You can add protection actions before and/or after the loading actions so it can validate the route path and afterwards validate whether the user should be able to see the given route. If the protect action returns another promise that promise is passed through, and whether it resolves or rejects determines if the action stops or continues. |
| 133 | + |
| 134 | +```javascript |
| 135 | +import { actionsProtect, actionBeforeRoute } from 'vuex-router-actions' |
| 136 | +const store = new Vuex.Store({ |
| 137 | + actions: { |
| 138 | + loadUser (context, user_id) {}, // returns promise which loads user data, also commits user to state |
| 139 | + loadTask (context, task_id) {}, // returns promise which loads task data |
| 140 | + |
| 141 | + // for actionBeforeRoute the to route is passed |
| 142 | + loadTaskPage ({dispatch}, to) { |
| 143 | + return dispatch('loadUser', to.params.user) |
| 144 | + .then(user => dispatch('hasUser')) |
| 145 | + .then(hasUser => dispatch('loadTask', to.params.task)) |
| 146 | + .then(task => dispatch('canEditTask', task)) |
| 147 | + }, |
| 148 | + ...actionsProtect({ |
| 149 | + hasUser ({state}) { return state.user && !state.user.disabled }, |
| 150 | + canEditTask ({state}, task) { return state.user.canEdit( task ) } |
| 151 | + }) |
| 152 | + } |
| 153 | +}) |
| 154 | +// Task page |
| 155 | +const component = { |
| 156 | + ...actionBeforeRoute('loadTaskPage') |
| 157 | +} |
| 158 | +``` |
| 159 | + |
| 160 | +#### actionBeforeRoute |
| 161 | + |
| 162 | +Dispatches an action in the store and waits for the action to finish before the routed component this is placed in is entered or updated (see `beforeRouteEnter` and `beforeRouteUpdate` in `vue-router`). If the action resolves the routed component will be entered, otherwise `getOtherwise` will be invoked to determine where the router should be redirected. `getOtherwise` by default returns false which simply stops routing. If it returned undefined it would proceed as normal. If it returned a string or a route object it would redirect to that route. |
| 163 | + |
| 164 | +```javascript |
| 165 | +// MyPage.vue |
| 166 | +import { actionBeforeRoute } from 'vuex-router-actions' |
| 167 | +export default { |
| 168 | + ...actionBeforeRoute('loadMyPage', (to, from, rejectReason) => { |
| 169 | + return '/path/i/can/goto/perhaps/previous/which/also/does/check' |
| 170 | + }) |
| 171 | +} |
| 172 | +``` |
| 173 | + |
| 174 | +#### actionOptional |
| 175 | + |
| 176 | +Allows you to pass the results of a dispatch through this function and whether or not it resolves or rejects it won't stop from proceeding. This happens by returning a promise which always resolves. If the given promise is rejected then `resolveOnReject` is passed to the resolve function of the returned Promise. |
| 177 | + |
| 178 | +## LICENSE |
| 179 | +[MIT](https://opensource.org/licenses/MIT) |
0 commit comments