9.8.4 State Management - caligrafy/caligrafy-quill GitHub Wiki

Vue provides powerful patterns that help modularize the user interface. Vue Components are key building blocks that help achieve that modularity. However, components are self-contained in a sense that each has properties and structures of its own. We saw ways to pass data and trigger events across components but what if data needs to be shared across different components and what if data can be changed by different components? How can we make sure that the data is up to date and synchronized all the time?

State Management is the technique that makes sure that the data that need to be shared by different components is the same by creating a centralized single source of truth. Caligrafy uses Vuex (a Vue add-on) to achieve state management.

Learn more about Vuex in the official Vuex Documentation

The store is at the center of every Caligrafy Vue application. It is the single source of truth where all the shared data properties and the actions that can be taken on them are defined. The store is responsible for changing and updating shared data across all the components that use it.

In Caligrafy Vue applications, the store is a global object that can be accessed from all components

this.$store

In the Caligrafy Vue App, the store comes out of the box with the distribution. The store can be found in the src/common/store.js file.

Similarly to a Vue a component, a store has its own 4 properties: state, mutations, actions, getters and has the following structure:

import { createStore } from 'vuex'

//import * as app from '@/common/app.js'
const store = createStore({
    state: {},
    mutations: {},
    actions: {},
    getters: {}
	
});

The store has 4 core properties:

The state is the latest version of the data. The state and the data defined in it can be accessed from all the components

    this.$store.state.propertyName

Read more about States

The only way to change a state is by committing a mutation. Mutations are similar to events in that they have a handler that takes the new state as an argument.

Mutations are defined like computed properties in a Vue component

import { createStore } from 'vuex'

const store = createStore({
    state: {}, 
    mutations: {

        // always takes a state as a first argument
        increment(state, incrementValue) {
            state.count += incrementValue;
        }

    },
    actions: {},
    getters: {}
    
});

Components can only modify states by mutating them. That means they need to invoke a mutation by committing the change.

this.$store.commit('increment', 1);

Read more about Mutations

The actions are methods that are used to asynchronously make changes to the data in the store. Basically, if a piece of data is constantly viewed and changed by different components and if that piece of data comes from the server through API calls then actions could handle the calls.

Unlike mutations, actions can't directly change a state, they need to commit mutations in order to effect a change.

import { createStore } from 'vuex'

const store = createStore({
    state: {},

    mutations: {

        // always takes a state as a first argument
        increment(state, incrementValue) {
            state.count += incrementValue;
        }

    },
    
    actions: {

        increment(context, incrementValue) {

            // dummy example for illustration purposes
            context.commit('increment', incrementValue);
        }

    },
    getters: {}
    
});

Components can dispatch actions to change the data in the store.

this.$store.dispatch('increment', 1);

Read more about Actions

Getters are sets of methods that retrieve the data from the store. Getters can manipulate the data but the manipulations are ephemeral unless they are committed through mutations.

Getters are implemented as callback methods and receive a state as a first argument.

import { createStore } from 'vuex'

const store = createStore({
    state: {},
    mutations: {

        // always takes a state as a first argument
        increment(state, incrementValue) {
            state.count += incrementValue;
        }

    },
    actions: {

        increment(context, incrementValue) {

            // dummy example for illustration purposes
            context.commit('increment', incrementValue);
        }

    },
    getters: {
         isEven(state) {
             return () => {
                 return state.count%2 == 0;
             }
         }

    }
    
});

Components can call the getters directly.

this.$store.getters.isEven('increment');

Read more about Getters

This the end of the Caligrafy Vue documentation and the beginning of your journey!