owl/doc/store.md

🦉 Store 🦉

Content

• Overview
• Example
• Reference
  • Public API
  • Mutations
  • Actions
  • Getters
  • Connecting a component

Overview

Managing the state in an application is not an easy task. In some cases, the state of an application can be part of the component tree, in a natural way. However, there are situations where some part of the state need to be displayed in various parts of the user interface, and then, it is not obvious which component should own which part of the state.

Owl's solution to this issue is a centralized store. It is a class that owns some state, and let the developer update it in a structured way (through mutations and actions). Owl components can then connect to the store, and will be updated if necessary.

Note: Owl's store is inspired by React Redux and VueX.

Example

Here is what a simple store looks like:

const actions = {
    addTodo({commit}, message) {
        commit('addTodo', message);
    }
};

const mutations = {
    addTodo({state}, message) {
        const todo = {
            id: state.nextId++,
            message,
            isCompleted: false,
        };
        state.todos.push(todo);
    },
};

const state = {
    todos: [],
    nextId: 1,
};

const store = new owl.Store({state, actions, mutations});
store.on('update', () => console.log(store.state));

// updating the state
store.dispatch('addTodo', 'fix all bugs');

Reference

The store is a simple owl.EventBus that triggers update events whenever its state is changed. Note that these events are triggered only after a microtask tick, so only one event will be triggered for any number of state changes in a call stack.

Also, it is important to mention that the state is observed (with an owl.Observer), which is the reason why it is able to know if it was changed. This implies that state changes need to be done carefully in some cases (adding a new key to an object, or modifying an array with the arr[i] = newValue syntax). See the Observer's documentation for more details.

Public API

1. constructor
2. commit
3. dispatch

Mutations

Mutations are the only way to modify the state. Changing the state outside a mutation is not allowed (and should throw an error). Mutations are synchronous.

Actions

Actions are used to coordinate state changes. It is also useful whenever some asynchronous logic is necessary. For example, fetching data should be done in an action.

const actions = {
    async login({commit}) {
        commit('setLoginState', 'pending');
        try {
            const loginInfo = await doSomeRPC('/login/', 'someinfo');
            commit('setLoginState', loginInfo);
        } catch {
            commit('setLoginState', 'error');
        }
    }
};

Getters

Usually, data contained in the store will be stored in a normalized way. For example,

{
    posts: [{id: 11, authorId: 4, content: 'Greetings'}],
    authors: [{id: 4, name: 'John'}]
}

However, the user interface will probably need some denormalized data like

{id: 11, author: {id: 4, name: 'John'}, content: 'Greetings'}

This is what getters are for: they give a centralized way to process and transform the data contained in the store.

const getters = {
    getPost({state}, id) {
        const post = state.posts.find(p => p.id === id);
        const author = state.authors.find(a => a.id = post.id);
        return {
            id,
            author,
            content: post.content
        };
    },
};

// somewhere else
const post = store.getters.getPost(id);

Connecting a component

By default, an Owl Component is not connected to any store. The connect function is there to create sub Components that are connected versions of Components.

const actions = {
    increment({commit}) {
        commit('increment', 1);
    }
};
const mutations = {
    increment({state}, val) {
        state.counter += val;
    }
};
const state = {
    counter: 0,
};
const store = new owl.Store({state, actions, mutations});

class Counter extends owl.Component {
    increment() {
        this.env.store.dispatch('increment');
    }
}
function mapStoreToProps(state) {
    return {
        value: state.counter
    };
}
const ConnectedCounter = owl.connect(Counter, mapStoreToProps);

const counter = new ConnectedCounter({ store, qweb });

<button t-name="Counter" t-on-click="increment">
  Click Me! [<t t-esc="props.value"/>]
</button>

The arguments of connect are:

• Counter: an owl Component to connect
• mapStoreToProps: a function that extracts the props of the Component from the state of the Store and returns them as a dict
• options: dictionary of optional parameters that may contain
  • getStore: a function that takes the env in arguments and returns an instance of Store to connect to (if not given, connects to env.store)
  • hashFunction: the function to use to detect changes in the state (if not given, generates a function that uses revision numbers, incremented at each state change)
  • deep: [only useful if no hashFunction is given] if false, only watch for top level state changes (true by default)

The connect function returns a sub class of the given Component which is connected to the store.