@oarepo/vuex-preloader
A url-parameters based preloader for vuex stores
- What it does
- Installation
- Configuration
- Multiple loaders on one path
- Single store on multiple paths
- Reloading
- Store name injection
- Project setup
- Sample application
What it does
This library provides a preloader that listens on router changes (beforeEach) and calls action on a vuex store before the execution is passed to target vue component.
When the route is changed, the preloader looks for meta.preloader
section
of matched route segments (all the way up to the root). For each of the
preloader segment it calls load
method on the appropriate store. The methods
are called in the order from the root down to the end of the matched path.
Installation
yarn add @oarepo/vuex-preloader
Configuration
In main.js/quasar boot, register the preloader:
import VuexPreloader from '@oarepo/vuex-preloader'
function errorHandler({router, route, pathSegment, exception}) {
console.error('Exception detected')
return '/error/404'
}
Vue.use(
VuexPreloader,
{
router, store,
errorHandler,
debug: true
}
)
In routes, make sure that routes are named and add the meta
sections:
const routes = [
{
path: '/',
name: 'home',
component: Home,
meta: {
preloader: {
'store': 'articles',
}
}
},
{
path: '/:articleId',
name: 'article',
component: () => Article,
meta: {
preloader: {
'store': 'article',
'action': 'loadArticle',
'params': {
articleId: 'id'
}
}
},
children: [
{
path: '/comments',
name: 'comments',
component: () => Comments,
meta: {
preloader: {
'isolated': commentStoreFactory,
'action': 'loadComments',
'params': {
articleId: 'articleId'
}
}
}
}
]
}
]
With this configuration, if user navigates to /12/comments
, a loading action
is dispatched on two stores - at first on article store and then comment store -
and after the loading has finished route is changed and Comments
component
is shown.
Parameters inside meta.preloader
:
-
store
- use this store module. If not filled, use the whole store -
isolated
- the parameter is a function that returns a vuexmodule
. The module is instantiated and registered via store.registerModule with a random name (prefixed withinstantiated_module.vuex_name
) When the module is not needed (user navigates out of the path segment), it is automatically removed from the main store. -
action
- dispatch this action on the store. Default action isload
-
params
- if filled, pass only these arguments to the store. The key is the name of path parameter, the value is the name of the passed parameter to theaction
. If not filled, all path parameters are passed to the store'saction
. -
props
- extra static props that will be passed to the store -
reload
- if set totrue
, always dispatch theaction
. If set tofalse
(default), dispatch theaction
only when the parameters to theaction
call have changed. -
expiration
- if set, store will not be reloaded if expiration (in seconds) has not passed since the last load -
reloadInterval
- if set, store will be reloaded automatically each reloadInterval (if the path still matches)
The path is changed only if all actions succeed in loading. If they do not,
an error handler is called with object {router, route, pathSegment, exception}
.
The handler can return:
-
true
to continue loading -
false
to stop path change. The handler is responsible for communicating the error and/or callingrouter.navigate
-
new route
to use it as thenext
url - page will be changed to this (for example, 404 page)
Multiple loaders on one path
The library supports multiple preloaders on a single route. Just put the loaders into an array, such as in:
const routes = [
{
path: '/:articleId',
name: 'article',
component: () => Article,
meta: {
preloader: [{
'store': 'article',
'action': 'loadArticle',
'params': {
articleId: 'id'
}
},
{
'store': 'comments',
'action': 'loadArticleComments',
'params': {
articleId: 'id'
}
}]
}
}
]
Single store on multiple paths
For cases where two paths reference the same loader, the loader would not reload as the remembered previous state is recorded on each path and so the loader does not know that a store content's has changed.
To fix this issue, manually set on all preloaders the same key
property, such as:
const routes = [
{
path: '/:articleId',
name: 'article1',
component: () => Article1,
meta: {
preloader: {
'key': 'article',
// extra params here
}
}
},
{
path: '/:articleId',
name: 'article2',
component: () => Article2,
meta: {
preloader: {
'key': 'article',
// extra params here
}
}
}
]
Reloading
In the default settings, store is only reloaded if the params for the fetch method have changed (i.e. the params in the url for the given route has changed). This setting can be overridden on many levels:
reload
if this option is set to true, the store will reload anytime the url is hit
expiration
if this option is set, the reload will happen on url change whenever the current time is greater than the time of the last fetch + expiration.
reloadInterval
if the route is shown to the user, the store will reload every reloadInterval
seconds
store.reloadNeeded
additionally if there is a property on the store called reloadNeeded
and
it is set to true, the store will be reloaded when the url is hit.
Store name injection
The library can also inject actual store name and additional properties into the component responsible for the path segment. To use this functionality (for example in case of isolated stores), register:
registerPreloader(router, store, erorrHandler, {injection: true})
Implicitly storeName
is injected into the component's props. When using isolated factory,
all properties returned by the factory are injected as well.
vue-query-synchronizer
integration
It is possible to use this library together with vue-query-synchronizer
. This way
the default values (such as pageSize=10, if not found in query) are stored in one place
in query synchronizer. An example ('1' is the default value of filter
):
routePart = {
path: '/vue-query-synchronizer',
name: 'vueqs',
component: VueQS,
meta: {
preloader: {
'store': 'qs',
}
},
props: query([
'string:filter:1',
], {}, {
passParams: true,
})
}
The library can also enable you to store/retrieve the default value to localStorage/server so that when user opens the application he sees his previous preset values (such as default number of table rows):
routePart = {
path: '/vue-query-synchronizer',
name: 'vueqs',
component: VueQS,
meta: {
preloader: {
'store': 'qs',
}
},
props: query([
'number:pageSize',
], {}, {
passParams: true,
onInit (params) {
params[0].defaultValue = window.localStorage.getItem('pageSize') || '10'
return params
},
onChange (newQuery, query) {
window.localStorage.setItem('pageSize', query.pageSize || '')
}
})
}
See https://github.com/oarepo/vue-query-synchronizer for details on using this library.
Project setup
yarn install
Sample application
To see the library in action, run the sample application
yarn run serve
Compile the library
yarn run build