diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-25 00:07:54 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-25 00:07:54 +0300 |
commit | c4db541c1b2c97ab1eda354ea3899489fe5c33e5 (patch) | |
tree | 45d5d381232179082ea11136e3b53211b37349d5 /doc/development/fe_guide | |
parent | 603c7d4cac5e28bc1c75e50c23ed2cbe56f1aafc (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development/fe_guide')
-rw-r--r-- | doc/development/fe_guide/vuex.md | 93 |
1 files changed, 84 insertions, 9 deletions
diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 675f30feba6..fd8ba0297c5 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -246,21 +246,96 @@ From [vuex mutations docs](https://vuex.vuejs.org/guide/mutations.html): export const ADD_USER = 'ADD_USER'; ``` -### How to include the store in your application +### Initializing a store's state -The store should be included in the main component of your application: +It's common for a Vuex store to need some initial state before its `action`s can +be used. Often this includes data like API endpoints, documentation URLs, or +IDs. + +To set this initial state, pass it as a parameter to your store's creation +function when mounting your Vue component: ```javascript - // app.vue - import store from './store'; // it will include the index.js file +// in the Vue app's initialization script (e.g. mount_show.js) - export default { - name: 'application', - store, - ... - }; +import Vue from 'vue'; +import createStore from './stores'; +import AwesomeVueApp from './components/awesome_vue_app.vue' + +export default () => { + const el = document.getElementById('js-awesome-vue-app'); + + return new Vue({ + el, + store: createStore(el.dataset), + render: h => h(AwesomeVueApp) + }); +}; ``` +The store function, in turn, can pass this data along to the state's creation +function: + +```javascript +// in store/index.js + +import * as actions from './actions'; +import mutations from './mutations'; +import createState from './state'; + +export default initialState => ({ + actions, + mutations, + state: createState(initialState), +}); +``` + +And the state function can accept this initial data as a parameter and bake it +into the `state` object it returns: + +```javascript +// in store/state.js + +export default ({ + projectId, + documentationPath, + anOptionalProperty = true +}) => ({ + projectId, + documentationPath, + anOptionalProperty, + + // other state properties here +}); +``` + +#### Why not just ...spread the initial state? + +The astute reader will see an opportunity to cut out a few lines of code from +the example above: + +```javascript +// Don't do this! + +export default initialState => ({ + ...initialState, + + // other state properties here +}); +``` + +We've made the conscious decision to avoid this pattern to aid in the +discoverability and searchability of our frontend codebase. The reasoning for +this is described in [this +discussion](https://gitlab.com/gitlab-org/frontend/rfcs/-/issues/56#note_302514865): + +> Consider a `someStateKey` is being used in the store state. You _may_ not be +> able to grep for it directly if it was provided only by `el.dataset`. Instead, +> you'd have to grep for `some_state_key`, since it could have come from a rails +> template. The reverse is also true: if you're looking at a rails template, you +> might wonder what uses `some_state_key`, but you'd _have_ to grep for +> `someStateKey` + ### Communicating with the Store ```javascript |