Forem: Coding Dodo

OWL in Odoo 14 - How to extend and patch existing OWL Components.

Coding Dodo — Sun, 08 Aug 2021 10:42:17 +0000

In this article, we will see how to extend, monkey-patch and, modify existing OWL Components in Odoo 14. There is a lot of confusion about that, and the existing way of overriding Odoo Widget doesn't work in that case.

We will focus on OWL Components inside Odoo 14, the process will probably be different in Odoo 15 since the WebClient has been entirely rewritten in OWL.

Coding Dodo

@codingdodo_

#Odoo WebClient rewrite in OWL has been merged for future v15 ! 🤩

I wrote a big tutorial on OWL, creating an app from scratch with it and now is the best time to learn: codingdodo.com/realworld-app-…

github.com/odoo/odoo/pull…

07:46 AM - 19 Jun 2021

Finally, this article assumes you have a good understanding of OWL already, if this is not the case check out this article series where we create the Realworld App with OWL and go other most of the functionalities of the Framework.

All OWL-related content is available here.

Introduction

First and foremost OWL Components are ES6 Classes , if you are not familiar with ES6 classes, you can visit this Google presentation article. I would also refer you to the amazing book You Don't Know JS: ES6 and Beyond.

ES6 Classes are basically syntactical sugar over the existing prototype-based inheritance in JavaScript. At the most basic level, an ES6 Class is a constructor that conforms to prototype-based inheritance. ES6 classes still have Object.prototype!

To go deeper on this subject I would recommend this article about the difference between these ES6 classes and prototypes. This is a very confusing subject, but this quote from the article is very relevant

The most important difference between class- and prototype-based inheritance is that a class defines a type which can be instantiated at runtime, whereas a prototype is itself an object instance.

Anyway, to work with Odoo 14 existing OWL Components, you still have to know some general concepts. We will keep it to a bare minimum, so let's begin with what an ES6 Class look like!

class Component {
  constructor(name) {
    this.name = name;
  }

  render() {
    console.log(`${this.name} renders itself.`);
  }

  // Getter/setter methods are supported in classes,
  // similar to their ES5 equivalents
  get uniqueId() {
    return `${this.name}-test`;
  }
}

You can inherit classes with the keyword extends and super to call parent function.

class MyBetterComponent extends Component {
  constructor(name) {
    super(name); // call the super class constructor and pass in the name parameter
  }

  render() {
    console.log(`${this.name} with id ${this.uniqueId} render itslef better.`);
  }
}

let comp = new MyBetterComponent('MyBetterComponent');
comp.render(); // MyBetterComponent with id MyBetterComponent-test renders itself better.

This is the standard ES6 super keyword, don't confuse it with the Odoo _super function built inside the Framework.

Most of the patching, extending, overriding of OWL Components in Odoo will make use of this basic knowledge, so let's dive in. Everything will become clearer with examples.

Odoo OWL utils patch, and patchMixin functions.

Extending Odoo OWL components is done via a patch function that comes in 2 flavors. Either the Component itself exposes a patch function because it is wrapped around the patchMixin. Or you have to use the patch function directly (in the web.utils package) to apply a patch to an OWL Component.

With the patchMixin, the Component exposes a "patch" function.

Inside odoo/addons/web/static/src/js/core/patch_mixin.js we have this patchMixinfunction:

function patchMixin(OriginalClass) {
    let unpatchList = [];
    class PatchableClass extends OriginalClass {}

    PatchableClass.patch = function (name, patch) {
        if (unpatchList.find(x => x.name === name)) {
            throw new Error(`Class ${OriginalClass.name} already has a patch ${name}`);
        }
        if (!Object.prototype.hasOwnProperty.call(this, 'patch')) {
            throw new Error(`Class ${this.name} is not patchable`);
        }
        const SubClass = patch(Object.getPrototypeOf(this));
        unpatchList.push({
            name: name,
            elem: this,
            prototype: this.prototype,
            origProto: Object.getPrototypeOf(this),
            origPrototype: Object.getPrototypeOf(this.prototype),
            patch: patch,
        });
        Object.setPrototypeOf(this, SubClass);
        Object.setPrototypeOf(this.prototype, SubClass.prototype);
    };

    PatchableClass.unpatch = function (name) {
        if (!unpatchList.find(x => x.name === name)) {
            throw new Error(`Class ${OriginalClass.name} does not have any patch ${name}`);
        }
        const toUnpatch = unpatchList.reverse();
        unpatchList = [];
        for (let unpatch of toUnpatch) {
            Object.setPrototypeOf(unpatch.elem, unpatch.origProto);
            Object.setPrototypeOf(unpatch.prototype, unpatch.origPrototype);
        }
        for (let u of toUnpatch.reverse()) {
            if (u.name !== name) {
                PatchableClass.patch(u.name, u.patch);
            }
        }
    };
    return PatchableClass;
}

A Component using this patchMixin is returned wrapped around the function, for example inside odoo/addons/mail/static/src/components/messaging_menu/messaging_menu.js the MessagingMenu is returned like that:

// ...
const patchMixin = require('web.patchMixin');

const { Component } = owl;

class MessagingMenu extends Component {
// ...
// content of the file
// ...
}
return patchMixin(MessagingMenu);

Be careful, there are actually not that many Components that are returned with the patchMixin , you should always check first if that is the case. We will call these kinds of components "Patchable Components".

Import "web.utils", patch function for a "non-patchable" Component as a last resort.

When the Component doesn't use the patchMixin you will not be able to extend the ES6 class properly but with the patch function you will be able to override the regular functions of the Component.

The web.utils patchfunction is kind of limited, and will work on the " regular functions " of the component. Constructor, getters, setters won't be inherited with technique as we will see in examples later.

This is the patch function content:

/**
 * Patch a class and return a function that remove the patch
 * when called.
 *
 * This function is the last resort solution for monkey-patching an
 * ES6 Class, for people that do not control the code defining the Class
 * to patch (e.g. partners), and when that Class isn't patchable already
 * (i.e. when it doesn't have a 'patch' function, defined by the 'web.patchMixin').
 *
 * @param {Class} C Class to patch
 * @param {string} patchName
 * @param {Object} patch
 * @returns {Function}
 */
patch: function (C, patchName, patch) {
    let metadata = patchMap.get(C.prototype);
    if (!metadata) {
        metadata = {
            origMethods: {},
            patches: {},
            current: []
        };
        patchMap.set(C.prototype, metadata);
    }
    const proto = C.prototype;
    if (metadata.patches[patchName]) {
        throw new Error(`Patch [${patchName}] already exists`);
    }
    metadata.patches[patchName] = patch;
    applyPatch(proto, patch);
    metadata.current.push(patchName);

    function applyPatch(proto, patch) {
        Object.keys(patch).forEach(function (methodName) {
            const method = patch[methodName];
            if (typeof method === "function") {
                const original = proto[methodName];
                if (!(methodName in metadata.origMethods)) {
                    metadata.origMethods[methodName] = original;
                }
                proto[methodName] = function (...args) {
                    const previousSuper = this._super;
                    this._super = original;
                    const res = method.call(this, ...args);
                    this._super = previousSuper;
                    return res;
                };
            }
        });
    }

    return utils.unpatch.bind(null, C, patchName);
},

As you may already see, the content of this function is problematic, it directly touches the prototype of the Object and do some checks on the typeof == "function" that can be misleading...

A Component returned from its module wrapped around the patchMixin has a patch function that you can use, if not your last resort is the web.utils general patch function.

In conclusion, this is what we have to work with. Now we will go through real world examples on how to apply this knowledge and see some specific cases.

Patchable Component (returned with "patchMixin"): Extend, monkey-patch, override.

Basic syntax

The basic syntax of extending a patchable component is:

PatchableComponent.patch("name_of_the_patch", (T) => {
    class NewlyPatchedComponent extends T {
        //... go wild 
    }
    return NewlyPatchedComponent
})

With this patch, you really play with ES6 classes syntax. Your extended Component is also an ES6 class so you can touch the constructor, getters, setters, properties, and other functions.

Example: the ControlPanel Component.

In this example, we will extend the ControlPanel Component. This component is returned with the patchMixin function, original file:

// at the end of file...
ControlPanel.template = 'web.ControlPanel';

return patchMixin(ControlPanel);

Describing the functionality.

The goal of our module is to be very obnoxious, we will be to display a message, under the ControlPanel (everywhere) that will call an API and show a random inspiring quote from some famous people.

Please don't use this code in a real project, everybody will hate you secretly.

To make our fetch request to our quotes API we will use the willUpdateProps hook so every time the user navigates on his WebClient it will fetch a new quote!

If you are not familiar with OWL hooks and particularly willUpdateProps, there is series about OWL from scratch here.

And the part talking about willUpdateProps is available here.

Implementing the code

First, let's extend the OWL XML template to add our div that will contain the quote.

<?xml version="1.0" encoding="UTF-8" ?>
<templates>
    <t t-inherit="web.ControlPanel" t-inherit-mode="extension" owl="1">
        <xpath expr="//div[hasclass('o_control_panel')]" position="inside">
            <div t-esc="state.customText" class="o_control_panel_random_quote"></div>
        </xpath>
    </t>
</templates>

/static/src/xml/control_panel.xml

Inheriting an OWL XML Template is very similar to extending standard QWeb templates except that you should not forget to add owl="1". We will put our div inside the control panel and show the customText inside the state of our Component.

We will make it prettier by adding some custom SCSS for it, inside /src/scss/control_panel.scss.

.o_control_panel {
  .o_control_panel_random_quote {
    color: $text-muted;
    font-style: italic;
    align-items: center;
    justify-content: center;
    font-weight: bolder;
  }
}

Now for the JavaScript module itself /src/js/control_panel.js

odoo.define("owl_tutorial.ControlPanel", function (require) {
  "use strict";
  const ControlPanel = require("web.ControlPanel");
  const { useState } = owl.hooks;

  // ConstrolPanel has a patch function thanks to the patchMixin 
  // This is the usual syntax, first argument is the name of our patch.
  ControlPanel.patch("owl_tutorial.ControlPanelCodingDodo", (T) => {
    class ControlPanelPatched extends T {
      constructor() {
        super(...arguments);
        this.state = useState({
          customText: "",
        });
        console.log(this.state);
      }

      async willUpdateProps(nextProps) {
        // Don't forget to call the super
        await super.willUpdateProps(nextProps);

        let self = this;
        fetch("https://type.fit/api/quotes")
          .then(function (response) {
            return response.json();
          })
          .then(function (data) {
            let quote = data[Math.floor(Math.random() * data.length)];
            // Update the state of the Component
            Object.assign(self.state, {
              customText: `${quote.text} - ${quote.author}`,
            });
          });
      }
    }
    return ControlPanelPatched;
  });
});

As you can see, having the Component returned with patchMixin makes it very easy to extend it directly, patch its function and add features!

Now let's take a loot at non-patchable Components.

Non-Patchable Component: Override a regular function with "web.utils" patch.

As of Odoo 14, most of the Components aren't returned with patchMixin and if we want to override the content of some Component functions we will use the web.utils patch function.

Example: the FileUpload Component.

Inside the mail addon the component FileUpload is responsible of handling the input files and the function that interests us is this one:

/**
 * @param {FileList|Array} files
 * @returns {Promise}
 */
async uploadFiles(files) {
    await this._unlinkExistingAttachments(files);
    this._createTemporaryAttachments(files);
    await this._performUpload(files);
    this._fileInputRef.el.value = '';
}

This Component isn't return wrapped with the patchMixin so we will have to use the "web.utils" function patch.

Describing the functionality

In this example we will change the behavior of the file upload inside the chatter send message box:

We will try to extend the behavior of the FileUpload so it doesn't even try to compute any file with a size over 10MB.

Implementing the code.

This is the content of our JavaScript module file.

odoo.define(
  "owl_tutorial/static/src/components/file_uploader/file_uploader.js",
  function (require) {
    "use strict";

    const components = {
      FileUploader: require("mail/static/src/components/file_uploader/file_uploader.js"),
    };

    const { patch } = require("web.utils");

    patch(
      components.FileUploader,
      "owl_tutorial/static/src/components/file_uploader/file_uploader.js",
      {
        // You can add your own functions to the Component.
        getMaxSize() {
          return 10000000;
        },

        /**
         * @override
         */
        async uploadFiles(files) {
          for (const file of files) {
            if (file.size > this.getMaxSize()) {
              // Files over 10MB are now rejected
              this.env.services["notification"].notify({
                type: "danger",
                message: owl.utils.escape(
                  `Max file size allowed is 10 MB, This file ${file.name} is too big!`
                ),
              });
              return false;
            }
          }
          return this._super(files);
        },
      }
    );
    console.log(components.FileUploader.prototype);
  }
);

With that done we now have a limit of 10MB on the size of the file uploaded, and a little notification warning us. We return _super if no file reached the limit.

Non-patchable Component: Override the "getter" of an OWL Component.

Some time ago I saw a question on the Odoo forums asking to override the get avatar getter of the Message component.

I noticed a lot of confusion around that and unfortunately, as we saw in the introduction, there is also an architectural problem with the way the patch function is coded in Odoo core.

Describing the problem

This is the original get avatar getter function:

/**
 * @returns {string}
 */
get avatar() {
    if (
        this.message.author &&
        this.message.author === this.env.messaging.partnerRoot
    ) {
        return '/mail/static/src/img/odoobot.png';
    } else if (this.message.author) {
        // TODO FIXME for public user this might not be accessible. task-2223236
        // we should probably use the correspondig attachment id + access token
        // or create a dedicated route to get message image, checking the access right of the message
        return this.message.author.avatarUrl;
    } else if (this.message.message_type === 'email') {
        return '/mail/static/src/img/email_icon.png';
    }
    return '/mail/static/src/img/smiley/avatar.jpg';
}

This syntax with a space between get and avatar is what we call a getter function.

To see the problem we have to look inside the content of the web.utils patch function and especially the applyPatch function. We can see this condition

if (typeof method === "function") {
    //...
}

But doing typeof on avatar will give us string in that case and not function type! So the patch will never get applied, we will have to find another way to hard override this getter function.

We could try to patch the components.Message.prototype instead of the Message class itself but that would also throw an error because the patch function stores a WeakMap on top of the file:

  const patchMap = new WeakMap();

To search and add patched prototype, the lookup is done via a WeakMap this way:

patch: function (C, patchName, patch) {
    let metadata = patchMap.get(C.prototype);
    if (!metadata) {
        metadata = {
            origMethods: {},
            patches: {},
            current: [],
        };
        patchMap.set(C.prototype, metadata);
    }

So the C.prototype will throw an error if the C given is already SomeClass.prototype.

Solution 1 - Redefining prototype property.

To quickly solve this problem we will apply standard JavaScript knowledge with Object. defineProperty on the prototype and change the "avatar" property.

odoo.define(
  "owl_tutorial/static/src/components/message/message.js",
  function (require) {
    "use strict";

    const components = {
      Message: require("mail/static/src/components/message/message.js"),
    };

    Object.defineProperty(components.Message.prototype, "avatar", {
      get: function () {
        if (
          this.message.author &&
          this.message.author === this.env.messaging.partnerRoot
        ) {
          // Here we replace the Robot with the better CodingDodo Avatar
          return "https://avatars.githubusercontent.com/u/81346769?s=400&u=614004f5f4dace9b3cf743ee6aa3069bff6659a2&v=4";
        } else if (this.message.author) {
          return this.message.author.avatarUrl;
        } else if (this.message.message_type === "email") {
          return "/mail/static/src/img/email_icon.png";
        }
        return "/mail/static/src/img/smiley/avatar.jpg";
      },
    });
  }
);

Note that this is pure JavaScript override and no "Odoo magic" will save you here, the super is not called for you and you have to be really careful when doing that. Any other override after yours on the same getter will override yours!

Using directly Object.defineProperty works but you are closing the door to future easy extensions from other modules. It is important to keep that in mind as Odoo is a module-driven Framework.

Solution 2 - Putting the `defineProperty` inside the Component `setup` function (overridable).

It would be better if the standard getter would call a regular function called _get_avatar that could be overrideable by other modules.

With the patch we also cannot override the constructor so we will use a function available on each OWL Component called setup.

setup is called at the end of the constructor of an OWL Component and can be overridden, patched, etc

const { patch } = require("web.utils");

patch(
  components.Message,
  "owl_tutorial/static/src/components/message/message.js",
  {
    /**
     * setup is run just after the component is constructed. This is the standard
     * location where the component can setup its hooks.
     */
    setup() {
      Object.defineProperty(this, "avatar", {
        get: function () {
          return this._get_avatar();
        },
      });
    },
    /**
     * Get the avatar of the user. This function can be overriden
     *
     * @returns {string}
     */
    _get_avatar() {
      if (
        this.message.author &&
        this.message.author === this.env.messaging.partnerRoot
      ) {
        // Here we replace the Robot with the better CodingDodo Avatar
        return "https://avatars.githubusercontent.com/u/81346769?s=400&u=614004f5f4dace9b3cf743ee6aa3069bff6659a2&v=4";
      } else if (this.message.author) {
        return this.message.author.avatarUrl;
      } else if (this.message.message_type === "email") {
        return "/mail/static/src/img/email_icon.png";
      }
      return "/mail/static/src/img/smiley/avatar.jpg";
    },
  }
);

In that way, the function can now be overridden again by another patch in the future.

// Can be overriden again now
patch(
  components.Message,
  "another_module/static/src/components/message/message_another_patch.js",
  {
    _get_avatar() {
      let originAvatar = this._super(...arguments);
      console.log("originAvatar", originAvatar);
      if (originAvatar === "/mail/static/src/img/odoobot.png") {
        return "https://avatars.githubusercontent.com/u/81346769?s=400&u=614004f5f4dace9b3cf743ee6aa3069bff6659a2&v=4";
      }
      return originAvatar;
    },
  }
);

Getter and setters are a cool feature of Classes but leave little space for extendability, it is sometimes better to make a getter as a shortcut to an actual classic function that can be extended later.

Solution 3 - Force apply the "patchMixin" on the Component and replace it in the Components tree.

The last solution is to create another Component equal to the old Component returned with patchMixin, then replace them where they are used in parent Components.

const { QWeb } = owl;
const patchMixin = require("web.patchMixin");

// Create patchable component from original Message
const PatchableMessage = patchMixin(components.Message);
// Get parent Component 
const MessageList = require("mail/static/src/components/message_list/message_list.js");

PatchableMessage.patch(
  "owl_tutorial/static/src/components/message/message.js",
  (T) => {
    class MessagePatched extends T {
      /**
       * @override property
       */
      get avatar() {
        if (
          this.message.author &&
          this.message.author === this.env.messaging.partnerRoot
        ) {
          // Here we replace the Robot with the better CodingDodo Avatar
          return "https://avatars.githubusercontent.com/u/81346769?s=400&u=614004f5f4dace9b3cf743ee6aa3069bff6659a2&v=4";
        } else if (this.message.author) {
          return this.message.author.avatarUrl;
        } else if (this.message.message_type === "email") {
          return "/mail/static/src/img/email_icon.png";
        }
        return "/mail/static/src/img/smiley/avatar.jpg";
      }
    }
    return MessagePatched;
  }
);
MessageList.components.Message = PatchableMessage;

We had to import the parent MessageList component to redefine its own components and put our own PatchableMessage.

The good thing is that now, every other module can extend our PatchableMessage and override easily our function! 🥳

Conclusion

In this article, we reviewed the two main available methods of patching, overriding, and extending Odoo 14 OWL Components. The patchfunction available when the Component is returned with the patchMixin and the global patch function from "web.utils" when we want to override basic functions of a Component.

I hope this guide was helpful to you on your journey customizing OWL Components in Odoo 14. In another article, we will so how to create Odoo 14 OWL Components from scratch and take a look at all the adapters available to us to mix OWL Components with good old Odoo Widgets.

The repository for this tutorial is available here:

Coding-Dodo / owl_tutorial_extend_override_components

This is repository with examples on how to extend, override and monkey patch OWL Components in Odoo v14

Coding Dodo - OWL Tutorial Extend/Override Components

This addon is a companion piece to the article about Extending, Overriding, Monkey-Patching Odoo 14 OWL Components.

Author

View on GitHub

Please consider subscribing to be alerted when new content is released here on Coding Dodo.

You can also follow me on Twitter and interact with me for requests about the content you would like to see here!

☕️ Buying me a Coffee

RealWorld App with OWL (Odoo Web Library) - Part 1

Coding Dodo — Mon, 31 May 2021 00:54:00 +0000

In this series, we will create the famous "RealWorld App" from scratch. With OWL (Odoo Web Library) 🦉 as the FrontEnd of choice.

What is the RealWorld App?

The RealWorld App is a Medium.com clone called Conduit built with several technologies on the FrontEnd and BackEnd.

The final result of this 4 parts tutorial series can be seen here it is hosted on Netlify.

The RealWorld App repository is a set of specs describing this "Conduit" app, how to create it on the front-end, and on the back-end:

gothinkster / realworld

"The mother of all demo apps" — Exemplary fullstack Medium.com clone powered by React, Angular, Node, Django, and many more 🏅

Stay on the bleeding edge — join our GitHub Discussions! 🎉

See how the exact same Medium.com clone (called Conduit) is built using different frontends and backends. Yes, you can mix and match them, because they all adhere to the same API spec 😮😎

While most "todo" demos provide an excellent cursory glance at a framework's capabilities, they typically don't convey the knowledge & perspective required to actually build real applications with it.

RealWorld solves this by allowing you to choose any frontend (React, Angular 2, & more) and any backend (Node, Django, & more) and see how they power a real world, beautifully designed fullstack app called "Conduit".

Read the full blog post announcing RealWorld on Medium.

Implementations

Over 100 implementations have been created using various languages, libraries, and frameworks.

See the list of implementations on the CodebaseShow website >>>

Create a new implementation

…

View on GitHub

In our Tutorial, we will implement the front-end part. Following the FRONTEND Instructions specs defined here, we will use the brand new OWL (Odoo Web Library) as the technology choice. This is a SPA with calls to an external API, so it will be a good starting point to see a lot of what the Framework has to offer in terms of state management, routing, and reactivity.

Styles and HTML templates are available in the repository and the routing structure of the client-side is described like that:

Home page (URL: /#/ )
- List of tags
- List of articles pulled from either Feed, Global, or by Tag
- Pagination for list of articles
Sign in/Sign up pages (URL: /#/login, /#/register )
- Uses JWT (store the token in localStorage)
- Authentication can be easily switched to session/cookie-based
Settings page (URL: /#/settings )
Editor page to create/edit articles (URL: /#/editor, /#/editor/article-slug-here )
Article page (URL: /#/article/article-slug-here )
- Delete article button (only shown to article's author)
- Render markdown from server client-side
- The comments section at bottom of the page
- Delete comment button (only shown to comment's author)
Profile page (URL: /#/profile/:username, /#/profile/:username/favorites )
- Show basic user info
- List of articles populated from author's created articles or author's favorited articles

Introducing OWL Framework(Odoo Web Library)

OWL is a new open-source Framework created internally at Odoo with the goal to be used as a replacement to the current old client-side technology used by Odoo. According to the repository description:

The Odoo Web Library (OWL) is a relatively small UI framework intended to be the basis for the Odoo Web Client in future versions (>15). Owl is a modern framework, written in Typescript, taking the best ideas from React and Vue in a simple and consistent way.

The Framework offers a declarative component system, reactivity with hooks (See React inspiration), a Store (mix between Vue and React implementation), and a front-end router.

The documentation is not exhaustive for now, but we will try to make sense of everything via use-cases.

Components

Components are JavaScript classes with properties, functions and the ability to render themselves (Insert or Update themselves into the HTML Dom). Each Component has a template that represents its final HTML structure, with composition, we can call other components with their tag name inside our Component.

class MagicButton extends Component {
  static template = xml`
    <button t-on-click="changeText">
      Click Me! [<t t-esc="state.value"/>]
    </button>`;

  state = { value: 0 };

  changeText() {
    this.state.value = "This is Magic";
    this.render();
  }
}

The templating system is in XML QWeb, which should be familiar if you are an Odoo Developer. t-on-click allow us to listen to the click event on the button and trigger a function defined inside the Component called changeText.

Properties of the Component live inside the state property, it is an object that has all the keys/value we need. This state is isolated and only lives inside that Component, it is not shared with other Components (even if they are copies of that one).

Inside that changeText function we change the state.value to update the text, then we call render to force the update of the Component display: the Button shown in the Browser now has the text "Click Me! This is Magic".

Hooks and reactivity

It is not very convenient to use render function all the time and to handle reactivity better, OWL uses a system its system of hooks, specifically the useState hook.

const { useState } = owl.hooks;

class MagicButton extends Component {
  static template = xml`
    <button t-on-click="changeText">
      Click Me! [<t t-esc="state.value"/>]
    </button>`;

  state = useState({ value: 0 });

  changeText() {
    this.state.value = "This is Magic";
  }
}

As we can see, we don't have to call the render function anymore. Using the useState hook actually tells the OWL Observer to watch for change inside the state via the native Proxy Object.

Passing data from Parent to Child via props

We saw that a Component can have multiple Components inside itself. With this Parent/Child hierarchy, data can be passed via props. For example, if we wanted the initial text "Click me" of our MagicButton to be dynamic and chosen from the Parent we can modify it like that

const { useState } = owl.hooks;

class MagicButton extends Component {
  static template = xml`
    <button t-on-click="changeText">
      <t t-esc="props.initialText"/> [<t t-esc="state.value"/>]
    </button>`;

  state = useState({ value: 0 });

  changeText() {
    this.state.value = "This is Magic";
  }
}

// And then inside a parent Component
class Parent extends Component {
  static template = xml`
<div>
    <MagicButton initialText="Dont click me!"/>
</div>`;
  static components = { MagicButton };

And that's it for a quick overview of the Framework, we will dive into other features via examples. From now on it's better if you follow along with your own repository so we create the RealWorld App together!

Starting our project

Prerequisites

Make sure that you have NodeJS installed. I use NVM (Node Version Manager) to handle different NodeJS versions on my system.

Follow the NVM install instructions here or install directly the following NodeJS version on your system.

For this tutorial, I'm using NodeJS v14.15.1

▶ nvm list
       v10.22.0
       v10.24.0
        v14.7.0
-> v14.15.1
default -> 10 (-> v10.24.0)
node -> stable (-> v14.15.1) (default)
stable -> 14.15 (-> v14.15.1) (default)

Using the OWL starter template

To make things a little easier, I've created a template project with Rollup as the bundling system to help us begin with modern JavaScript convention and bundling systems.

Coding-Dodo / OWL-JavaScript-Project-Starter

OWL JavaScript Project Starter with Rollup

OWL Javascript Project Starter

This repo is an example on how to start a real project with the Odoo OWL framework.

Thanks to @SimonGenin for it's original Starter Project for OWL

Features

OWL
Javascript
Livereload
Rollup.js
Tests with Jest

Installation

This repo is a "template repository". It means you can quickly create repositories based on this one, without it being a fork.

Otherwise, you may clone it:

git clone https://github.com/Coding-Dodo/OWL-JavaScript-Project-Starter.git

Install dependencies:

npm install

Dev with livereload:

npm run dev

Production build

npm run build

Run tests

npm run test

Components

It is expected to create components in one file, following this convention:

import { Component, useState, tags } from "@odoo/owl";
const APP_TEMPLATE = tags.xml/*xml*/ `
<div t-name="App" class="" t-on-click="update">
  Hello <t t-esc="state.text"/>
</div>
`;

export class App extends Component {
  static template = APP_TEMPLATE;
  state = useState({ text:

…

View on GitHub

This is a template repo, so click on " Use this template" to create your own repo based on this one (You can also clone it like other repositories).

After pulling the repository we have this file structure:

├── README.md
├── package-lock.json
├── package.json
├── public
│   └── index.html
├── rollup.config.js
├── src
│   ├── App.js
│   ├── components
│   │   └── MyComponent.js
│   └── main.js
└── tests
    ├── components
    │   └── App.test.js
    └── helpers.js

Index.html is a basic HTML file containing minimum info, we will use the <head> tag to insert the Stylesheet given by the RealWorld app later.

The core of our app lives in the src folder, for now, it only contains 2 files. main.js is the entry point :

import { App } from "./app";
import { utils } from "@odoo/owl";

(async () => {
  const app = new App();
  await utils.whenReady();
  await app.mount(document.body);
})();

In this file, we import our main App Component , that we mount on the <body>tag of our index.html file.

Owl components are defined with ES6 (JavaScript - EcmaScript 20015) classes, they use QWeb templates, a virtual DOM to handle reactivity, and asynchronous rendering. Knowing that we simply instantiate our App object.

As its name may suggest utils package contains various utilities, here we use whenReady that tells us when the DOM is totally loaded so we can attach our component to the body.

App Component

The App Class Component represents our application, it will inject all other Components.

import { Component, tags } from "@odoo/owl";
import { MyComponent } from "./components/MyComponent";

const APP_TEMPLATE = tags.xml/*xml*/ `
<main t-name="App" class="" t-on-click="update">
  <MyComponent/>
</main>
`;

export class App extends Component {
  static template = APP_TEMPLATE;
  static components = { MyComponent };
}

MyComponent is a basic Component representing a span, when you click on it the text change. It's only here as an example and we will delete it later.

Installing dependencies and running the dev server.

First, we need to install the dependencies

cd OWL-JavaScript-Project-Starter
npm install

Then, to run the tests

npm run test

And finally, to run the development server

npm run dev

The output should be:

rollup v2.48.0
bundles src/main.js → dist/bundle.js...
http://localhost:8080 -> /Users/codingdodo/Code/owl-realworld-app/dist
http://localhost:8080 -> /Users/codingdodo/Code/owl-realworld-app/public
LiveReload enabled
created dist/bundle.js in 608ms

[2021-05-20 14:33:10] waiting for changes...

OWL Hello World App is running on localhost:8080

If you would prefer to run the server on a different port you have to edit rollup.config.js and search for the serve section

serve({
    open: false,
    verbose: true,
    contentBase: ["dist", "public"],
    host: "localhost",
    port: 8080, // Change Port here
}),

Importing styles from RealWorld App resources kit.

We will update public/index.html to include <link> to assets given by RealWorld App repository instructions. These assets include the font, the icons, and the CSS:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>RealWorld App in OWL</title>
    <!-- Import Ionicon icons & Google Fonts our Bootstrap theme relies on -->
    <link
      href="https://code.ionicframework.com/ionicons/2.0.1/css/ionicons.min.css"
      rel="stylesheet"
      type="text/css"
    />
    <link
      href="https://fonts.googleapis.com/css?family=Titillium+Web:700|Source+Serif+Pro:400,700|Merriweather+Sans:400,700|Source+Sans+Pro:400,300,600,700,300italic,400italic,600italic,700italic"
      rel="stylesheet"
      type="text/css"
    />
    <!-- Import the custom Bootstrap 4 theme from our hosted CDN -->
    <link rel="stylesheet" href="https://demo.productionready.io/main.css" />
    <script type="module" src="bundle.js"></script>
  </head>
  <body></body>
</html>

Navigating to http://localhost:8080/ should already show you the change of fonts.

Implementing the elements of the layout as Components.

The Conduit App has a classic design layout, composed of a Navbar Header, Content, and Footer.

For now, we will implement the Homepage and the different elements of the Layout as simple HTML content ("dumb" Components, with no logic).

Creating the Navbar Component

Inside src/components/ we will create a new file named Navbar.js

import { Component, tags } from "@odoo/owl";

const NAVBAR_TEMPLATE = tags.xml/*xml*/ `
<nav class="navbar navbar-light">
    <div class="container">
        <a class="navbar-brand" href="index.html">conduit</a>
        <ul class="nav navbar-nav pull-xs-right">
            <li class="nav-item">
                <!-- Add "active" class when you're on that page" -->
                <a class="nav-link active" href="">Home</a>
            </li>
            <li class="nav-item">
                <a class="nav-link" href="">
                    <i class="ion-compose"></i> New Post
                </a>
            </li>
            <li class="nav-item">
                <a class="nav-link" href="">
                    <i class="ion-gear-a"></i> Settings
                </a>
            </li>
            <li class="nav-item">
                <a class="nav-link" href="">Sign in</a>
            </li>
            <li class="nav-item">
                <a class="nav-link" href="">Sign up</a>
            </li>
        </ul>
    </div>
</nav>
`;
export class Navbar extends Component {
  static template = NAVBAR_TEMPLATE;
}

The template is defined as a const NAVBAR_TEMPLATE then added as a static property to our Navbar Component declaration.

The content of the template is surrounded by tags.xml/*xml*/. These xmlcomments are used so TextEditor extensions that handle Comment tagged templates can be used to have syntax highlight inside our components. For VisualStudio Code the plugin is here.

For the XML content itself, it is just copy-pasted from the instructions on the RealWorld Repo. We will not implement Navigation just yet.

Creating the Footer Component

Inside src/components/ we will create a new file named Footer.js

import { Component, tags } from "@odoo/owl";

const FOOTER_TEMPLATE = tags.xml/*xml*/ `
<footer>
    <div class="container">
        <a href="/" class="logo-font">conduit</a>
        <span class="attribution">
            An interactive learning project from <a href="https://thinkster.io">Thinkster</a>. Code &amp; design licensed under MIT.
        </span>
    </div>
</footer>
`;
export class Footer extends Component {
  static template = FOOTER_TEMPLATE;
}

Creating the Home Page Component

This component will hold the content of the Home page.

In this tutorial, we will create a new folder src/pages/ that will hold our "pages" Components. This is an architecture decision that you don't have to follow, but as the number of components will start to grow we would ultimately want to do some cleaning to keep things organized.

With the folder created, inside src/pages/, we will create a new file named Home.js, (full structure):

import { Component, tags, useState } from "@odoo/owl";

const HOME_TEMPLATE = tags.xml/*xml*/ `
<div class="home-page">

    <div class="banner" t-on-click="update">
        <div class="container">
            <h1 class="logo-font">conduit</h1>
            <p><t t-esc="state.text"/></p>
        </div>
    </div>

    <div class="container page">
        <div class="row">
            <div class="col-md-9">
                <div class="feed-toggle">
                    <ul class="nav nav-pills outline-active">
                        <li class="nav-item">
                            <a class="nav-link disabled" href="">Your Feed</a>
                        </li>
                        <li class="nav-item">
                            <a class="nav-link active" href="">Global Feed</a>
                        </li>
                    </ul>
                </div>

                <div class="article-preview">
                    <div class="article-meta">
                        <a href="profile.html"><img src="http://i.imgur.com/Qr71crq.jpg" /></a>
                        <div class="info">
                            <a href="" class="author">Eric Simons</a>
                            <span class="date">January 20th</span>
                        </div>
                        <button class="btn btn-outline-primary btn-sm pull-xs-right">
                            <i class="ion-heart"></i> 29
                        </button>
                    </div>
                    <a href="" class="preview-link">
                        <h1>How to build webapps that scale</h1>
                        <p>This is the description for the post.</p>
                        <span>Read more...</span>
                    </a>
                </div>
                <div class="article-preview">
                    <div class="article-meta">
                    <a href="profile.html"><img src="http://i.imgur.com/N4VcUeJ.jpg" /></a>
                    <div class="info">
                        <a href="" class="author">Albert Pai</a>
                        <span class="date">January 20th</span>
                    </div>
                    <button class="btn btn-outline-primary btn-sm pull-xs-right">
                        <i class="ion-heart"></i> 32
                    </button>
                    </div>
                    <a href="" class="preview-link">
                    <h1>The song you won't ever stop singing. No matter how hard you try.</h1>
                    <p>This is the description for the post.</p>
                    <span>Read more...</span>
                    </a>
                </div>
            </div>

            <div class="col-md-3">
                <div class="sidebar">
                    <p>Popular Tags</p>

                    <div class="tag-list">
                        <a href="" class="tag-pill tag-default">programming</a>
                        <a href="" class="tag-pill tag-default">javascript</a>
                        <a href="" class="tag-pill tag-default">emberjs</a>
                        <a href="" class="tag-pill tag-default">angularjs</a>
                        <a href="" class="tag-pill tag-default">react</a>
                        <a href="" class="tag-pill tag-default">mean</a>
                        <a href="" class="tag-pill tag-default">node</a>
                        <a href="" class="tag-pill tag-default">rails</a>
                    </div>
                </div>
            </div>
        </div>
    </div>

</div>

`;
export class Home extends Component {
  static template = HOME_TEMPLATE;
  state = useState({ text: "A place to share your knowledge." });
  updateBanner() {
    this.state.text =
      this.state.text === "A place to share your knowledge."
        ? "An OWL (Odoo Web Library) RealWorld App"
        : "A place to share your knowledge.";
  }
}

Since we will delete ./components/MyComponent we will inject some logic inside this Home Component to test if the framework reactivity is working.

We registered a click event on the banner to fire the updateBanner function:

<div class="banner" t-on-click="update">
    <div class="container">
        <h1 class="logo-font">conduit</h1>
        <p><t t-esc="state.text"/></p>
    </div>
</div>

Inside the Component definition, we created the updateBanner function:

  updateBanner() {
    this.state.text =
      this.state.text === "A place to share your knowledge."
        ? "An OWL (Odoo Web Library) RealWorld App"
        : "A place to share your knowledge.";
  }

So every time the user clicks on the banner, the message will change.

Injecting our components into the main App Component

Now we need to make use of these fine Components. To do so, open the src/components/App.js file and use these Components.

import { Component, tags } from "@odoo/owl";
import { Navbar } from "./components/Navbar";
import { Footer } from "./components/Footer";
import { Home } from "./pages/Home";

const APP_TEMPLATE = tags.xml/*xml*/ `
<main>
  <Navbar/>
  <Home/>
  <Footer/>
</main>
`;

export class App extends Component {
  static components = { Navbar, Footer, Home };
  static template = APP_TEMPLATE;
}

First, we imported the different components/pages like import { Navbar } from "./Navbar";, etc... We use destructuring to get Navbar as a class from the file it is exported and the path of the file is relative (same folder) with the use of ./.

Inside the class App, we filled the static property components to "register" what components App will need to render itself.

Finally, in the XML template, we called these Components as if they were HTML elements with the same name as the ones defined in the static components property.

Our App template now reflects what the basic layout of the website is:

<main>
  <Navbar/>
  <Home/>
  <Footer/>
</main>

Update the tests to check that everything is working correctly.

Inside the ./tests/components/App.test.js we will update the logic to test the reactivity of our Home Component and the presence of Navbar and Footer.

describe("App", () => {
  test("Works as expected...", async () => {
    await mount(App, { target: fixture });
    expect(fixture.innerHTML).toContain("nav");
    expect(fixture.innerHTML).toContain("footer");
    expect(fixture.innerHTML).toContain("A place to share your knowledge.");
    click(fixture, "div.banner");
    await nextTick();
    expect(fixture.innerHTML).toContain(
      "An OWL (Odoo Web Library) RealWorld App"
    );
  });
});

Run the tests with the command:

npm run test

The tests should pass

> jest
 PASS tests/components/App.test.js

Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 1.628 s
Ran all test suites.

Implementing the different Pages Components of the App.

We will create each of the pages corresponding to the specs as components. There is the HomePage, Settings, LogIn, Register, Editor (New article), and Profile pages.

Settings Page

import { Component, tags, hooks } from "@odoo/owl";
const { xml } = tags;

const SETTINGS_TEMPLATE = xml/* xml */ `
<div class="settings-page">
  <div class="container page">
    <div class="row">

      <div class="col-md-6 offset-md-3 col-xs-12">
        <h1 class="text-xs-center">Your Settings</h1>
        <form>
          <fieldset>
              <fieldset class="form-group">
                <input class="form-control" type="text" placeholder="URL of profile picture"/>
              </fieldset>
              <fieldset class="form-group">
                <input class="form-control form-control-lg" type="text" placeholder="Your Name"/>
              </fieldset>
              <fieldset class="form-group">
                <textarea class="form-control form-control-lg" rows="8" placeholder="Short bio about you"></textarea>
              </fieldset>
              <fieldset class="form-group">
                <input class="form-control form-control-lg" type="text" placeholder="Email"/>
              </fieldset>
              <fieldset class="form-group">
                <input class="form-control form-control-lg" type="password" placeholder="Password"/>
              </fieldset>
              <button class="btn btn-lg btn-primary pull-xs-right">
                Update Settings
              </button>
          </fieldset>
        </form>
        <hr/>
        <button class="btn btn-outline-danger">Or click here to logout.</button>
      </div>

    </div>
  </div>
</div>
`;

export class Settings extends Component {
  static template = SETTINGS_TEMPLATE;
}

./src/pages/Settings.js

LogIn Page

import { Component, tags } from "@odoo/owl";
const { xml } = tags;

const LOG_IN_TEMPLATE = xml/* xml */ `
<div class="auth-page">
  <div class="container page">
    <div class="row">

      <div class="col-md-6 offset-md-3 col-xs-12">
        <h1 class="text-xs-center">Sign in</h1>
        <p class="text-xs-center">
          <a href="#register">Need an account?</a>
        </p>

        <ul class="error-messages">
          <li>Invalid credentials</li>
        </ul>

        <form>
          <fieldset class="form-group">
            <input class="form-control form-control-lg" type="text" placeholder="Email"/>
          </fieldset>
          <fieldset class="form-group">
            <input class="form-control form-control-lg" type="password" placeholder="Password"/>
          </fieldset>
          <button class="btn btn-lg btn-primary pull-xs-right">
            Sign In
          </button>
        </form>
      </div>

    </div>
  </div>
</div>
`;
export class LogIn extends Component {
  static template = LOG_IN_TEMPLATE;
}

./src/pages/LogIn.js

Register Page

import { Component, tags } from "@odoo/owl";
const { xml } = tags;

const REGISTER_TEMPLATE = xml/* xml */ `
<div class="auth-page">
  <div class="container page">
    <div class="row">

      <div class="col-md-6 offset-md-3 col-xs-12">
        <h1 class="text-xs-center">Sign up</h1>
        <p class="text-xs-center">
          <a href="#login">Have an account?</a>
        </p>

        <ul class="error-messages">
          <li>That email is already taken</li>
        </ul>

        <form>
          <fieldset class="form-group">
            <input class="form-control form-control-lg" type="text" placeholder="Your Name"/>
          </fieldset>
          <fieldset class="form-group">
            <input class="form-control form-control-lg" type="text" placeholder="Email"/>
          </fieldset>
          <fieldset class="form-group">
            <input class="form-control form-control-lg" type="password" placeholder="Password"/>
          </fieldset>
          <button class="btn btn-lg btn-primary pull-xs-right">
            Sign up
          </button>
        </form>
      </div>

    </div>
  </div>
</div>
`;
export class Register extends Component {
  static template = REGISTER_TEMPLATE;
}

./src/pages/Register.js

Profile Page

import { Component, tags } from "@odoo/owl";
const { xml } = tags;

const PROFILE_TEMPLATE = xml/* xml */ `
<div class="profile-page">
    <div class="user-info">
        <div class="container">
            <div class="row">

            <div class="col-xs-12 col-md-10 offset-md-1">
                <img src="http://i.imgur.com/Qr71crq.jpg" class="user-img" />
                <h4>Eric Simons</h4>
                <p>
                Cofounder @GoThinkster, lived in Aol's HQ for a few months, kinda looks like Peeta from the Hunger Games
                </p>
                <button class="btn btn-sm btn-outline-secondary action-btn">
                <i class="ion-plus-round"></i> Follow Eric Simons 
                </button>
            </div>

            </div>
        </div>
    </div>

    <div class="container">
    <div class="row">

        <div class="col-xs-12 col-md-10 offset-md-1">
        <div class="articles-toggle">
            <ul class="nav nav-pills outline-active">
            <li class="nav-item">
                <a class="nav-link active" href="">My Articles</a>
            </li>
            <li class="nav-item">
                <a class="nav-link" href="">Favorited Articles</a>
            </li>
            </ul>
        </div>

        <div class="article-preview">
            <div class="article-meta">
            <a href=""><img src="http://i.imgur.com/Qr71crq.jpg" /></a>
            <div class="info">
                <a href="" class="author">Eric Simons</a>
                <span class="date">January 20th</span>
            </div>
            <button class="btn btn-outline-primary btn-sm pull-xs-right">
                <i class="ion-heart"></i> 29
            </button>
            </div>
            <a href="" class="preview-link">
            <h1>How to build webapps that scale</h1>
            <p>This is the description for the post.</p>
            <span>Read more...</span>
            </a>
        </div>

        <div class="article-preview">
            <div class="article-meta">
            <a href=""><img src="http://i.imgur.com/N4VcUeJ.jpg" /></a>
            <div class="info">
                <a href="" class="author">Albert Pai</a>
                <span class="date">January 20th</span>
            </div>
            <button class="btn btn-outline-primary btn-sm pull-xs-right">
                <i class="ion-heart"></i> 32
            </button>
            </div>
            <a href="" class="preview-link">
            <h1>The song you won't ever stop singing. No matter how hard you try.</h1>
            <p>This is the description for the post.</p>
            <span>Read more...</span>
            <ul class="tag-list">
                <li class="tag-default tag-pill tag-outline">Music</li>
                <li class="tag-default tag-pill tag-outline">Song</li>
            </ul>
            </a>
        </div>
        </div>
    </div>
    </div>
</div>
`;

export class Profile extends Component {
  static template = PROFILE_TEMPLATE;
}

./src/pages/Profile.js

Editor Page

import { Component, tags } from "@odoo/owl";
const { xml } = tags;

const EDITOR_TEMPLATE = xml/* xml */ `
<div class="editor-page">
  <div class="container page">
    <div class="row">

      <div class="col-md-10 offset-md-1 col-xs-12">
        <form>
          <fieldset>
            <fieldset class="form-group">
                <input type="text" class="form-control form-control-lg" placeholder="Article Title"/>
            </fieldset>
            <fieldset class="form-group">
                <input type="text" class="form-control" placeholder="What's this article about?"/>
            </fieldset>
            <fieldset class="form-group">
                <textarea class="form-control" rows="8" placeholder="Write your article (in markdown)"></textarea>
            </fieldset>
            <fieldset class="form-group">
                <input type="text" class="form-control" placeholder="Enter tags"/><div class="tag-list"></div>
            </fieldset>
            <button class="btn btn-lg pull-xs-right btn-primary" type="button">
                Publish Article
            </button>
          </fieldset>
        </form>
      </div>

    </div>
  </div>
</div>
`;
export class Editor extends Component {
  static template = EDITOR_TEMPLATE;
}

./src/pages/Editor.js

Now that all our pages are created we will now handle the routing and navigation between them.

OWL Router to the rescue

To handle Single Page Applications most of the modern frameworks have a router. OWL is no different.

Creating the routes and adding the router to the env

The router in OWL is an object that has to be instantiated and "attached" to the env of our main App.

Env is an environment is an object which contains a QWeb instance. Whenever a root component is created, it is assigned an environment. This environment is then automatically given to all child components (and accessible in the this.env property).

A router can run in hash or history_mode. Here we will use the hash mode because the expected result for RealWorld App is URLs like /#/profile /#/settings, etc. The router will also handle direct, programmatically navigation/redirection , navigation guards, to protect some routes behind conditions, and routes also accept parameters. Official documentation of OWL router.

To instantiate an OWL router we need an environment and a list of routes.

Inside ./src/main.js we will create our Router. We will have to import router, QWeb from the @odoo/owl.

import { App } from "./App";
import { utils, router, QWeb } from "@odoo/owl";

Before we import each of our pages Components we will create a new file ./pages/index.js that will handle all the import/export of the classes so we can import every Component needed in one line later.

import { LogIn } from "./LogIn";
import { Register } from "./Register";
import { Home } from "./Home";
import { Settings } from "./Settings";
import { Editor } from "./Editor";
import { Profile } from "./Profile";

export { LogIn, Register, Home, Settings, Editor, Profile };

Then back inside our ./src/main.js we can import all the pages and declare the routes that adhere to the specifications of the RealWorld App. These routes have an internal name, a path (without the #), and an associated Component.

import { LogIn, Register, Home, Settings, Editor, Profile } from "./pages";

export const ROUTES = [
  { name: "HOME", path: "/", component: Home },
  { name: "LOG_IN", path: "/login", component: LogIn },
  { name: "REGISTER", path: "/register", component: Register },
  { name: "SETTINGS", path: "/settings", component: Settings },
  { name: "EDITOR", path: "/editor", component: Editor },
  { name: "PROFILE", path: "/profile/@{{username}}", component: Profile },
];

Then we will create our environment and attach the router to it inside a function called makeEnvironement

async function makeEnvironment() {
  const env = { qweb: new QWeb() };
  env.router = new router.Router(env, ROUTES, { mode: "hash" });
  await env.router.start();
  return env;
}

This is our final App.js Component

import { App } from "./App";
import { utils, router, mount, QWeb } from "@odoo/owl";
import { LogIn, Register, Home, Settings, Editor, Profile } from "./pages";

export const ROUTES = [
  { name: "HOME", path: "/", component: Home },
  { name: "LOG_IN", path: "/login", component: LogIn },
  { name: "REGISTER", path: "/register", component: Register },
  { name: "SETTINGS", path: "/settings", component: Settings },
  { name: "EDITOR", path: "/editor", component: Editor },
  { name: "PROFILE", path: "/profile", component: Profile },
];

async function makeEnvironment() {
  const env = { qweb: new QWeb() };
  env.router = new router.Router(env, ROUTES, { mode: "hash" });
  await env.router.start();
  return env;
}

async function setup() {
  App.env = await makeEnvironment();
  mount(App, { target: document.body });
}

utils.whenReady(setup);

Using `<RouteComponent/>`.

Now that our routes are registered we will update our App Component to make use of the OWL <RouteComponent/>. Inside "./src/App.js":

import { Component, tags, router } from "@odoo/owl";
import { Navbar } from "./components/Navbar";
import { Footer } from "./components/Footer";
import { Home } from "./pages/Home";
const RouteComponent = router.RouteComponent;

const APP_TEMPLATE = tags.xml/*xml*/ `
<main>
  <Navbar/>
  <RouteComponent/>
  <Footer/>
</main>
`;

export class App extends Component {
  static components = { Navbar, Footer, Home, RouteComponent };
  static template = APP_TEMPLATE;
}

What we did here is import the RouteComponent from the router package in @odoo/owl. Then register the RouteComponent inside the static components property and then add it inside the template.

Directly trying http://localhost:8080/#/settings in your browser will show you the setting page!

Adding the `<Link>` Components to handle navigation.

<Link> is an OWL Component that has a prop, (Attribute that you can pass directly to the Component from the Template and the value is scoped to inside that Component), named to that navigate to the route name.

Inside ./src/components/Navbar.js let's import Link Component and transform our <a href></a> to <Link to=""> Components

import { Component, tags, router } from "@odoo/owl";
const Link = router.Link;

const NAVBAR_TEMPLATE = tags.xml/*xml*/ `
<nav class="navbar navbar-light">
    <div class="container">
        <!-- <a class="navbar-brand" href="index.html">conduit</a> -->
        <Link to="'HOME'" class="navbar-brand">conduit</Link>
        <ul class="nav navbar-nav pull-xs-right">
            <li class="nav-item">
                <!-- Add "active" class when you're on that page" -->
                <Link to="'HOME'" class="nav-link">Home</Link>
            </li>
            <li class="nav-item">
                <Link to="'EDITOR'" class="nav-link"><i class="ion-compose"></i> New Post</Link>
            </li>
            <li class="nav-item">
                <Link to="'SETTINGS'" class="nav-link"><i class="ion-gear-a"></i> Settings</Link>
            </li>
            <li class="nav-item">
                <Link to="'LOG_IN'" class="nav-link">Sign in</Link>
            </li>
            <li class="nav-item">
                <Link to="'REGISTER'" class="nav-link">Sign up</Link>
            </li>
            <li class="nav-item">
                <Link to="'PROFILE'" class="nav-link">Coding Dodo</Link>
            </li>
        </ul>
    </div>
</nav>
`;
export class Navbar extends Component {
  static template = NAVBAR_TEMPLATE;
  static components = { Link };
}

We can see that class is also passed to the <Link/> Component as a prop, the end result is an "href" with the class that was given to the prop.

Going to http://localhost:8080/#/ we can see that our navigation is working!

But there is a little problem with the styles, the original <Link/> Component applies a class of router-active to the "href" if the route corresponds to that link. But our style guide uses the active class directly.

Creating our custom NavbarLink component via inheritance.

To handle that problem will create our own Custom NavbarLink component in ./src/components/NavbarLink.js

import { tags, router } from "@odoo/owl";
const Link = router.Link;
const { xml } = tags;

const LINK_TEMPLATE = xml/* xml */ `
<a t-att-class="{'active': isActive }"
    t-att-href="href"
    t-on-click="navigate">
    <t t-slot="default"/>
</a>
`;
export class NavbarLink extends Link {
  static template = LINK_TEMPLATE;
}

As you can see we inherit the base Link Component class and just define another Template that is slightly different.

Then inside our Navbar.js component we update our imports, components and replace the <Link> with our own <NavbarLink>:

import { Component, tags, router } from "@odoo/owl";
const Link = router.Link;
import { NavbarLink } from "./NavbarLink";

const NAVBAR_TEMPLATE = tags.xml/*xml*/ `
<nav class="navbar navbar-light">
    <div class="container">
        <!-- <a class="navbar-brand" href="index.html">conduit</a> -->
        <Link to="'HOME'" class="navbar-brand">conduit</Link>
        <ul class="nav navbar-nav pull-xs-right">
            <li class="nav-item">
                <!-- Add "active" class when you're on that page" -->
                <NavbarLink to="'HOME'" class="nav-link">Home</NavbarLink>
            </li>
            <li class="nav-item">
                <NavbarLink to="'EDITOR'" class="nav-link"><i class="ion-compose"></i> New Post</NavbarLink>
            </li>
            <li class="nav-item">
                <NavbarLink to="'SETTINGS'" class="nav-link"><i class="ion-gear-a"></i> Settings</NavbarLink>
            </li>
            <li class="nav-item">
                <NavbarLink to="'LOG_IN'" class="nav-link">Sign in</NavbarLink>
            </li>
            <li class="nav-item">
                <NavbarLink to="'REGISTER'" class="nav-link">Sign up</NavbarLink>
            </li>
            <li class="nav-item">
                <NavbarLink to="'PROFILE'" class="nav-link">Coding Dodo</NavbarLink>
            </li>
        </ul>
    </div>
</nav>
`;
export class Navbar extends Component {
  static template = NAVBAR_TEMPLATE;
  static components = { Link, NavbarLink };
}

Conclusion

Ending this first part of the tutorial, we have a functional, albeit basic, routing system. Each of the pages has been created statically (no dynamic data inside) for now.

The source code for this part of the tutorial is available here. To directly clone that branch (that part of the tutorial):

git clone -b feature/basic-pages-structure-routing https://github.com/Coding-Dodo/owl-realworld-app.git

In the next part, we will tackle:

authentication/registration
Using the OWL Store to get info of the currently logged-in user.
With that, we will add conditionals to our template to show the correct links if the user is logged in or not.

Thanks for reading and consider becoming a member to stay updated when the next part comes out!

Part 2 of this tutorial is available here.

Create an Odoo 14 Markdown Widget Field with TDD - Part 3

Coding Dodo — Sun, 16 May 2021 23:00:00 +0000

Introduction

This is the third part of an article series where we use TDD to develop an Odoo markdown widget.

We continue right where we left last time, writing tests, exploring the JS Framework, making mistakes, and refactoring our code. We saw, by installing and trying to use the widget, that it was not correctly visible and hard to use, so we will fix that.

Managing the built-in the auto-resize of FieldText

Analysis

First, we need to take a look at the FieldText widget inside the source code:

var FieldText = InputField.extend(TranslatableFieldMixin, {
    description: _lt("Multiline Text"),
    className: 'o_field_text',
    supportedFieldTypes: ['text', 'html'],
    tagName: 'span',

    /**
     * @constructor
     */
    init: function () {
        this._super.apply(this, arguments);

        if (this.mode === 'edit') {
            this.tagName = 'textarea';
        }
        this.autoResizeOptions = {parent: this};
    },
    /**
     * As it it done in the start function, the autoresize is done only once.
     *
     * @override
     */
    start: function () {
        if (this.mode === 'edit') {
            dom.autoresize(this.$el, this.autoResizeOptions);
            if (this.field.translate) {
                this.$el = this.$el.add(this._renderTranslateButton());
                this.$el.addClass('o_field_translate');
            }
        }
        return this._super();
    },

In the init function we see the declaration of the autoResizeOptions property, then in the start function it is used in conjunction with the dom.autoresize function.

We could directly override the start function to modify that behavior but in this deep-dive tutorial series we try to understand how things work so we will look at that function inside odoo/addons/web/static/src/js/core/dom.js

autoresize: function ($textarea, options) {
    if ($textarea.data("auto_resize")) {
        return;
    }

    var $fixedTextarea;
    var minHeight;

    function resize() {
        $fixedTextarea.insertAfter($textarea);
        //...
//...

What interests us is right at the beginning of the function. We don't want the autoResize feature to kick in so we need to get inside this condition so the function returns directly.

And to get into that condition, the JQuery Element (in the variable $textarea) should have a property "data" named auto_resize. (Data properties are prefixed with data, so in the XML markup it will be data-auto_resize )

Updating the QWeb Template of our widget?

So we will modify the QWeb template of our widget to add that data and prevent the auto-resize feature. Update web_widget_markdown/static/src/xml/qweb_template.xml with that content

<?xml version="1.0" encoding="UTF-8"?>
<templates>
    <t t-name="FieldMarkdown">
        <div class="o_field_markdown" data-auto_resize="False">
            <textarea name="o_field_markdown" id="o_field_markdown"></textarea>
        </div>
    </t>
</templates>

This seems to do the job, the Editor is now useable and fully scrollable if we go over the limit but there is still a lot of problems:

FieldText transforms our div tag name to <textarea> making the dom in Edit mode having 2 <textarea> inside of each other.
We can't use the Tabulation key, some KeyUp events seem to be in conflict and have different behavior.
The reset function of FieldText wants to trigger a change event on an $input that doesn't exist with self.$input.trigger('change');so we should also override the reset function?

It seems that we are fighting against the implementation of FieldText (with logic about <textarea>, resizing, translation) inheriting InputField with logic about Key Up/down events and injecting input field inside our dom.

What do we actually use from FieldText or InputField?

The answer is quite simple, nothing.

It seemed a good idea at first because our Markdown field is a Text field in essence but conflicts with the basic widgets are becoming an annoyance. So we will go up the inheritance tree and use the DebouncedField. This class contains the logic we actually want and are using in our widget.

Refactoring our widget to extend DebouncedField

Updating the Field declaration

The good news is that we have a full test suite to use against our refactoring, so we can be confident about the changes we will make. Inside web_widget_markdown/static/src/js/field_widget.js

var markdownField = basicFields.DebouncedField.extend({
    supportedFieldTypes: ['text'],
    template: 'FieldMarkdown',
    jsLibs: [
        '/web_widget_markdown/static/lib/simplemde.min.js',
    ],
    //...

Then we run our test suite

Everything seems OK ✅ and we can also edit our template to remove the data-auto_resize as it is no longer useful.

Handling KeyUp/Down events

We still have the problem of using the tab key inside the Editor.

Now that the inheritance chain is simplified we know that the logic handling the Key events is either inside DebouncedField or his parent AbstractField.

A quick look inside DebouncedField gives us nothing so the logic is inside AbstractField, the "super" class that is at the top of all field widgets in odoo/addons/web/static/src/js/fields/abstract_field.js

var AbstractField = Widget.extend({
    events: {
        'keydown': '_onKeydown',
    },
    //...
    _onKeydown: function (ev) {
        switch (ev.which) {
            case $.ui.keyCode.TAB:
                var event = this.trigger_up('navigation_move', {
                    direction: ev.shiftKey ? 'previous' : 'next',
                });
                if (event.is_stopped()) {
                    ev.preventDefault();
                    ev.stopPropagation();
                }
                break;
//...

All fields have this events property that map an event bubbled up by the controller, here keydown, to a function _onKeydown.

And we see here that this where the logic about the TAB keyCode press happens. As a solution we will remove all the key events of our widget because the events are handled by SimpleMDE already, so we update our widget declaration like that:

var markdownField = basicFields.DebouncedField.extend({
    supportedFieldTypes: ['text'],
    template: 'FieldMarkdown',
    jsLibs: [
        '/web_widget_markdown/static/lib/simplemde.min.js',
    ],
    events: {}, // events are triggered manually for this debounced widget
    //...

Run the tests again (after each refactoring) and test the UI to see that now we can press TAB Key again without leaving the Editor.

Directly bind CodeMirror changes to the debounceActions

We will also refactor that part to use the debounceAction function given by DebouncedField. We will also improve our widget to bind on the blur method (where the user clicks out of the markdown editor) so it saves the changes.

Change

this.simplemde.codemirror.on("change", function(){
    self._setValue(self.simplemde.value());
})

Replace with those lines

this.simplemde.codemirror.on("change", this._doDebouncedAction.bind(this));
this.simplemde.codemirror.on("blur", this._doAction.bind(this));

Run the tests again, they should still be all green.

Making our widget translatable

Going away from FieldText inheritance made us lose the Translatable functionality, but it is okay, we didn't have any tests for that feature.

Writing the test suite for our translatable field

When a field has a translation feature, it has a little icon on the right with the code of the language.

Clicking on that button opens a Dialog with as many rows as languages installed on the environment, allowing the user to edit the source and translation value.

For these tests we will inspire us of the basic widget test suite, testing the CharField translatable feature. In our file web_widget_markdown/static/tests/web_widget_markdown_tests.js

QUnit.test('markdown widget field translatable', async function (assert) {
    assert.expect(12);

    this.data.blog.fields.content.translate = true;

    var multiLang = _t.database.multi_lang;
    _t.database.multi_lang = true;

    var form = await testUtils.createView({
        View: FormView,
        model: 'blog',
        data: this.data,
        arch: '<form string="Blog">' +
                '<group>' +
                    '<field name="name"/>' +
                    '<field name="content" widget="markdown"/>' +
                '</group>' +
            '</form>',
        res_id: 1,
        session: {
            user_context: {lang: 'en_US'},
        },
        mockRPC: function (route, args) {
            if (route === "/web/dataset/call_button" && args.method === 'translate_fields') {
                assert.deepEqual(args.args, ["blog", 1, "content"], 'should call "call_button" route');
                return Promise.resolve({
                    domain: [],
                    context: {search_default_name: 'blog,content'},
                });
            }
            if (route === "/web/dataset/call_kw/res.lang/get_installed") {
                return Promise.resolve([["en_US", "English"], ["fr_BE", "French (Belgium)"]]);
            }
            if (args.method === "search_read" && args.model == "ir.translation") {
                return Promise.resolve([
                    {lang: 'en_US', src: '# Hello world', value: '# Hello world', id: 42},
                    {lang: 'fr_BE', src: '# Hello world', value: '# Bonjour le monde', id: 43}
                ]);
            }
            if (args.method === "write" && args.model == "ir.translation") {
                assert.deepEqual(args.args[1], {value: "# Hellow mister Johns"},
                    "the new translation value should be written");
                return Promise.resolve();
            }
            return this._super.apply(this, arguments);
        },
    });
    await testUtils.form.clickEdit(form);
    var $translateButton = form.$('div.o_field_markdown + .o_field_translate');
    assert.strictEqual($translateButton.length, 1, "should have a translate button");
    assert.strictEqual($translateButton.text(), 'EN', 'the button should have as test the current language');
    await testUtils.dom.click($translateButton);
    await testUtils.nextTick();

    assert.containsOnce($(document), '.modal', 'a translate modal should be visible');
    assert.containsN($('.modal .o_translation_dialog'), '.translation', 2,
        'two rows should be visible');

    var $dialogENSourceField = $('.modal .o_translation_dialog .translation:first() input');
    assert.strictEqual($dialogENSourceField.val(), '# Hello world',
        'English translation should be filled');
    assert.strictEqual($('.modal .o_translation_dialog .translation:last() input').val(), '# Bonjour le monde',
        'French translation should be filled');

    await testUtils.fields.editInput($dialogENSourceField, "# Hellow mister Johns");
    await testUtils.dom.click($('.modal button.btn-primary')); // save
    await testUtils.nextTick();

    var markdownField = _.find(form.renderer.allFieldWidgets)[1];
    assert.strictEqual(markdownField._getValue(), "# Hellow mister Johns",
        "the new translation was not transfered to modified record");

    markdownField.simplemde.value(' **This is new English content**');
    await testUtils.nextTick(); 
    // Need to wait nextTick for data to be in markdownField.value and passed 
    // to the next dialog open
    await testUtils.dom.click($translateButton);
    await testUtils.nextTick();

    assert.strictEqual($('.modal .o_translation_dialog .translation:first() input').val(), ' **This is new English content**',
        'Modified value should be used instead of translation');
    assert.strictEqual($('.modal .o_translation_dialog .translation:last() input').val(), '# Bonjour le monde',
        'French translation should be filled');

    form.destroy();

    _t.database.multi_lang = multiLang;
});

Explaining the test suite

This test suite begins by asserting that the translationButton is present. Then the test presses the button and checks that the Dialog opens and contains the right data.

The next step for the tests is to focus the input in that dialog and write something in the source (English), save it and verify that the changes are visible in our widget (SimpleMDE should have this new value).

Then we will change the value in our widget via SimpleMDE. Press the translate button again and inside the dialogue, the new source value should be what we just wrote in the widget. On the other hand, the value in French should have kept its value from the fake RPC Calls made.

Mocking RPC Calls

Each click to open the translate button actually makes multiple RPC calls to the server.

It queries the languages installed on the instance and then it queries for translations rows on that record for that field so we will have to mock the calls to the server.

We will mock the fetching of the translation languages, the fetching of the translation rows, and the writing of a new translation ( by returning an empty resolved Promise).

mockRPC: function (route, args) {
    if (route === "/web/dataset/call_button" && args.method === 'translate_fields') {
        assert.deepEqual(args.args, ["blog", 1, "content"], 'should call "call_button" route');
        return Promise.resolve({
            domain: [],
            context: {search_default_name: 'blog,content'},
        });
    }
    if (route === "/web/dataset/call_kw/res.lang/get_installed") {
        return Promise.resolve([["en_US", "English"], ["fr_BE", "French (Belgium)"]]);
    }
    if (args.method === "search_read" && args.model == "ir.translation") {
        return Promise.resolve([
            {lang: 'en_US', src: '# Hello world', value: '# Hello world', id: 42},
            {lang: 'fr_BE', src: '# Hello world', value: '# Bonjour le monde', id: 43}
        ]);
    }
    if (args.method === "write" && args.model == "ir.translation") {
        assert.deepEqual(args.args[1], {value: "# Hellow mister Johns"},
            "the new translation value should be written");
        return Promise.resolve();
    }
    return this._super.apply(this, arguments);
},

Adding the Translate button

The translation button and event handling logic is located inside a mixin class in odoo/addons/web/static/src/js/fields/basic_fields.js called TranslatableFieldMixin.

We will inherit that mixin to have access to the function to render buttons, so we change the declaration of our widget

var markdownField = basicFields.DebouncedField.extend(basicFields.TranslatableFieldMixin, {
    //...
}

Then, inside the start of our function, we will add the translate button in the edit mode condition

start: function () {
    if (this.mode === 'edit') {
        var $textarea = this.$el.find('textarea');
        this.simplemde = new SimpleMDE({
            element: $textarea[0],
            initialValue: this.value,
        });
        var self = this;
        this.simplemde.codemirror.on("change", function(){
            self._setValue(self.simplemde.value());
        })
        if (this.field.translate) {
            this.$el = this.$el.add(this._renderTranslateButton());
            this.$el.addClass('o_field_translate');
        }
    }
    return this._super();
},

Running the tests

Every test passed ✅ ! It took us longer to write the tests than the functionality as it is oftentimes with TDD. But it gives us confidence in the future when we will have to refactor the code for any reason.

Passing attributes to our widget

Widgets often have an option attribute that you can pass directly inside the XML when you call the widget. These options are then accessible inside the widget itself via the nodeOptions property.

SimpleMDE has options that we can pass inside the configuration object, for example, there is a placeholder property that we can use if the SimpleMDE Editor is empty and show a text to invite the user to write something

var simplemde = new SimpleMDE({placeholder: "Begin typing here..."})

We already use the configuration object in our start function to set the initialValue, we will do the same for other options.

In the end, we want to be able to use our widget like that:

<group>
    <field name="content" widget="markdown" options="{'placeholder':'Write your content here'}"/>
</group>

And see the placeholder text inside our instance of SimpleMDE

Writing the tests

The options will be available in our field simplemde instance with markdownField.simplemde.options object.

QUnit.test('web_widget_markdown passing property to SimpleMDE', async function(assert) {
    assert.expect(1);
    var form = await testUtils.createView({
        View: FormView,
        model: 'blog',
        data: this.data,
        arch: `<form string="Blog">
                <group>
                    <field name="name"/>
                    <field name="content" widget="markdown" options="{'placeholder': 'Begin writing here...'}"/>
                </group>
            </form>`,
        res_id: 1,
    });
    await testUtils.form.clickEdit(form);
    var markdownField = _.find(form.renderer.allFieldWidgets)[1];
    assert.strictEqual(
        markdownField.simplemde.options.placeholder,
        "Begin writing here...", 
        "SimpleMDE should have the correct placeholder"
    );

    await testUtils.form.clickSave(form);
    form.destroy();
});

Run the tests, they will fail obviously.

Handling the options

To handle the attributes passed in the XML declaration we have access to this.nodeOptions. With that in mind let's rewrite our instantiation inside the start function.

start: function () {
    if (this.mode === 'edit') {
        var $textarea = this.$el.find('textarea');
        var simplemdeConfig = {
            element: $textarea[0],
            initialValue: this.value,
        }
        if (this.nodeOptions) {
            simplemdeConfig.placeholder = this.nodeOptions.placeholder || '';
        }
        this.simplemde = new SimpleMDE(simplemdeConfig);
        this.simplemde.codemirror.on("change", this._doDebouncedAction.bind(this));
        this.simplemde.codemirror.on("blur", this._doAction.bind(this));
        if (this.field.translate) {
            this.$el = this.$el.add(this._renderTranslateButton());
            this.$el.addClass('o_field_translate');
        }
    }
    return this._super();
},

Run the tests and you should see all green ✅

Refactoring the options assignment

We have 2 options:

Inside the nodeOptions getting each option possible (that we want available) and passing them as config
Letting the user pass any config options that he can find on SimpleMDE documentation.

We will try to do the latter by refactoring the way we map nodeOptions to config options via the Javascript ...spread operator to combine 2 objects.

if (this.nodeOptions) {
    simplemdeConfig = {...simplemdeConfig, ...this.nodeOptions};
}

If we run the tests again they are still green ✅ and now our user can pass any (for complex objects it will be complicated in the XML declaration) option he wants.

Conclusion

The source code for this Part 3 of the series is available here on GitHub.

In this long-running series, we tried to implement TDD in Odoo JavaScript development through the example of creating a new Field widget.

I hope you found it useful, we will use our widget later in another series where we create a totally new kind of view with Owl and use our widget inside. Become a member to have access to future posts so you don't miss any future articles.

☕️ Buying me a Coffee
🥳 Register on Codingdodo.com

Create an Odoo 14 Markdown Widget Field with TDD - Part 2

Coding Dodo — Wed, 12 May 2021 05:10:03 +0000

Introduction

This is the second part of an article series where we use TDD to develop an Odoo markdown widget.

Create an Odoo 14 Markdown Widget Field with TDD - Part 1

In the last part (code available here) we ended up with a functional widget transforming pure text markdown content into HTML in render mode and behaving like a standard FieldText when in edit mode.

In this tutorial, we are going to use SimpleMDE Editor instead of the standard FieldText <textarea> input.

Refactoring and adding new tests

First of all, we are going to remove the test named web_widget_markdown edit form. As a reminder, this test was used to Edit the form and write into the input like that:

await testUtils.form.clickEdit(form);
await testUtils.fields.editInput(form.$('.o_field_markdown'), ' **bold content**');
await testUtils.form.clickSave(form);

The problem is that the editInput function will not work anymore because SimpleMDE will replace the whole <textarea> with his own editor and writing inside will not be possible.

How to test SimpleMDE presence

To test for SimpleMDE presence we have to analyze how this library insert its editor into the DOM, and a quick inspect gives us more info:

<div class="CodeMirror cm-s-paper CodeMirror-wrap">
    <div style="overflow: hidden; position: relative; width: 3px; height: 0px; top: 15px; left: 38.8281px;" data-children-count="1">
        <textarea autocorrect="off" autocapitalize="off" spellcheck="false" tabindex="0" style="position: absolute; padding: 0px; width: 1000px; height: 1em; outline: none;">
        </textarea>
    </div>
    <div class="CodeMirror-vscrollbar" cm-not-content="true" style="bottom: 0px; width: 12px; pointer-events: none;">
    ...
    </div>
</div>

As we can see, SimpleMDE uses the underlying library CodeMirror to create his editor. So checking for the presence of the div with class .CodeMirror should validate the presence of the Editor. Let's write a new test.

QUnit.test('web_widget_markdown SimpleMDE is present', async function(assert) {
    assert.expect(1);
    var form = await testUtils.createView({
        View: FormView,
        model: 'blog',
        data: this.data,
        arch: '<form string="Blog">' +
                '<group>' +
                '<field name="name"/>' +
                    '<field name="content" widget="markdown"/>' +
                '</group>' +
            '</form>',
        res_id: 1,
    });
    await testUtils.form.clickEdit(form);
    assert.strictEqual(
        form.$('.o_field_markdown').find("div.CodeMirror").length, 
        1, 
        "CodeMirror div should be present"
    )
    form.destroy();
});

How to test that SimpleMDE is working

To test that simple MDE is working we should:

First, go into Edit mode so SimpleMDE is initialized (previous test)
Check that the initial value of our model (data) is passed to SimpleMDE
Change the value of SimpleMDE content (mock behavior of user writing inside the WYSIWYG) and verify that Odoo widget value has been updated
Save the Form and assert that our edits are saved and present

Writing the tests

To go through our test we will need to have access to the widget itself from the mocked FormView. Form object have a renderer attribute that will be helpful in that situation by inspecting it's allFieldWidgets property:

// [1] because in our form the first field is for the name of the blog
// So the first field is in [0] and ours is in [1]
var markdownField = _.find(form.renderer.allFieldWidgets)[1];

Inside the test, we want to be able to have access to the SimpleMDE instance directly from the widget.

Often times, we write tests that drive us to implement the solution in a specific way. In this example we know that we want the Widget Object to hold a property object named simplemde containing the current instance of new SimpleMDE Editor. This will help us to initialize it, destroy it, set, or get its value. This is a powerful way of programming because the test help us make more robust APIs by directly needing us to implement the strict necessary functions for it to be functional.

So given the idea, we have that property available the test can be written like that

QUnit.test('web_widget_markdown edit SimpleMDE', async function(assert) {
    assert.expect(4);
    var form = await testUtils.createView({
        View: FormView,
        model: 'blog',
        data: this.data,
        arch: '<form string="Blog">' +
                '<group>' +
                '<field name="name"/>' +
                    '<field name="content" widget="markdown"/>' +
                '</group>' +
            '</form>',
        res_id: 1,
    });
    await testUtils.form.clickEdit(form);
    var markdownField = _.find(form.renderer.allFieldWidgets)[1];

    assert.strictEqual(
        markdownField.simplemde.value(), 
        "# Hello world", 
        "Initial Value of SimpleMDE should be set"
    )

    markdownField.simplemde.value(' **bold content**');
    assert.strictEqual(
        markdownField._getValue(), 
        " **bold content**", 
        "If we change value in SimpleMDE, value of odoo widget should be updated"
    )

    await testUtils.form.clickSave(form);
    assert.strictEqual(
        form.$('.o_field_markdown').find("strong").length, 
        1, 
        "After Save, b should be present"
    )
    assert.strictEqual(
        form.$('.o_field_markdown strong').text(), 
        "bold content", 
        "After Save, <strong> should contain 'bold content'"
    )
    form.destroy();
});

We cannot properly interact with the CodeMirror editor with JQuery testUtils so we will refer to the CodeMirror user manual to see how to insert a value (this is also what happens when user type) and this is how we will do it from the test function:

markdownField.simplemde.codemirror.setValue(' **bold content**');

And to test that the Odoo field itself has the same value as the Markdown editor we make this assertion.

assert.strictEqual(
    markdownField._getValue(), 
    " **bold content**", 
    "Value of odoo widget should be updated"
)

General knowledge: Understanding _getValue() in Odoo Widget

_getValue() is a function first defined in the DebouncedField (FieldText inherits DebouncedField).

// Inside DebouncedField in odoo/addons/web/static/src/js/fields/basic_fields.js
/**
 * Should return the current value of the field, in the DOM (for example,
 * the content of the input)
 *
 * @abstract
 * @private
 * @returns {*}
 */
_getValue: function () {},

A DebouncedField is a superclass that handles the debouncing of the user input.

Debouncing an input in JavaScript is a common technique to reduce the rate of execution of a function. If a user is typing inside an input and you execute a function on each change of that input (each letter typed) it can quickly lead to a lot of computation power being used on just that. The common technique is called debounced and it will delay the execution of the function listening to the input, only every X secondes. Odoo use _.debounce for this with the underscorejs library.

This is a summarized view of the Odoo Fields Widget inheritance graph

// the super class
var AbstractField = {}
    // handle debouncing
    var DebouncedField = AbstractField.extend({})
        // handle keystroke evnts, state and other things
        var InputField = DebouncedField.extend({})
            // more specific implementations using InputField logic
            var FieldText = InputField.extend({})
            var FieldChar = InputField.extend({})
            var FieldDate = InputField.extend({})
            var FieldDate = InputField.extend({})

Most of all the field inheriting InputField are overriding this _getValue() function to return more than the basic this.value property of a widget and we will do the same.

Running the tests in the current state of our widget expectedly fail.

Initialize SimpleMDE editor in widget Edit mode

As we wrote our tests earlier, we know that we need to have simplemde as a property of our widget, let's then extend the init function of our widgetto do so:

/**
* @constructor
*/
init: function () {
    this._super.apply(this, arguments);
    this.simplemde = {}
},

Attaching SimpleMDE to our Widget dom root element.

And in the start function (available in all Odoo Widgets) we will do this:

/**
 * When the the widget render, check view mode, if edit we
 * instanciate our SimpleMDE
 * 
 * @override
 */
start: function () {
    if (this.mode === 'edit') {
        this.simplemde = new SimpleMDE({element: this.$el[0]});
    }
    return this._super();
},

When we instantiate SimpleMDE we need to at least give him the element option or else it will attach itself to any <textarea> existing (this the the default behavior of the library).

What is this.$el[0] ?

this.$el is a JQuery object and not a pure dom Element as required by SimpleMDE, so by doing this.$el[0] we get the proper dom element.

Keep in mind that we inherit FieldText, and FieldText has some original logic about the HTML element it uses to render itself. In read-only mode, it is a <span> and in edit mode the tag change, as seen here in the source code of the FieldText :

/**
* @constructor
*/
init: function () {
    this._super.apply(this, arguments);

    if (this.mode === 'edit') {
        this.tagName = 'textarea';
    }
}

Running the tests and analyzing the error

Now if we run the tests we will see this error

Cannot read property 'insertBefore' of null@ 121 ms

TypeError: Cannot read property 'insertBefore' of null
    at http://localhost:8069/web_widget_markdown/static/lib/simplemde.min.js:12:1240
    at new t (http://localhost:8069/web_widget_markdown/static/lib/simplemde.min.js:7:31640)
    at new e (http://localhost:8069/web_widget_markdown/static/lib/simplemde.min.js:7:29476)
    at e (http://localhost:8069/web_widget_markdown/static/lib/simplemde.min.js:7:29276)
    at Function.e.fromTextArea (http://localhost:8069/web_widget_markdown/static/lib/simplemde.min.js:12:1213)
    at B.render (http://localhost:8069/web_widget_markdown/static/lib/simplemde.min.js:15:4157)
    at new B (http://localhost:8069/web_widget_markdown/static/lib/simplemde.min.js:14:28861)
    at Class.start (http://localhost:8069/web_widget_markdown/static/src/js/field_widget.js:34:30)
    at Class.prototype.<computed> [as start] (http://localhost:8069/web/static/src/js/core/class.js:90:38)
    at http://localhost:8069/web/static/src/js/core/widget.js:440:25

The error actually comes from the simplemde library trying to insert itself into the DOM. We gave him $el[0] as an element. And as seen in the source code, the actual element given is a <textarea>, this is due to us inheriting FieldText.

But the problem actually comes from the surrounding of the <textarea> element. SimpleMDE will actually use parentNode on the element given to place itself. The element given as $el[0] as is has no parent due to the way the Odoo Framework inserts it in the DOM.

So the base template of our field cannot be as simple as a span, it has to be encapsulated by another div or something else.

Moving to a dedicated Qweb Template for our widget

To create a Template for a widget we need to create an XML file containing our template then explicitly use it in our javascript widget declaration.

The Qweb template

Create the file static/src/xml/qweb_template.xml with this content.

<?xml version="1.0" encoding="UTF-8"?>
<templates>
    <t t-name="FieldMarkdown">
        <div class="o_field_markdown">
            <textarea name="o_field_markdown" id="o_field_markdown"></textarea>
        </div>
    </t>
</templates>

We gave our template the same name t-name="FieldMarkdown as the name we export in our JavaScript file for consistency.

Inside it is just a wrapper div class with the same class .o_field_markdown we used before and inside it a <textare> for SimpleMDE to attach to.

Add it to your __manifest__.py

"qweb": [ 
    'static/src/xml/qweb_template.xml',
],

Using the template in our JavaScript field widget

var markdownField = basicFields.FieldText.extend({
    supportedFieldTypes: ['text'],
    // className: 'o_field_markdown',
    template: 'FieldMarkdown', // name of template in xml Qweb file
    jsLibs: [
        '/web_widget_markdown/static/lib/simplemde.min.js',
    ],
    // ...

We removed the className attribute because it is no longer useful.

Run the tests again and surely it fails again because we still tell SimpleMDE to attach itself to the root $el of our widget.

Refactoring our widget to use the new template

Inside the start function of the widget, we will target the <textarea> inside the <div> we created in the template.

start: function () {
    if (this.mode === 'edit') {
        var $textarea = this.$el.find('textarea');
        this.simplemde = new SimpleMDE({element: $textarea[0]});
    }
    return this._super();
},

Now if we run the tests again:

Markdown Widget Tests: web_widget_markdown SimpleMDE is present (1) ✅
Markdown Widget Tests: web_widget_markdown edit SimpleMDE (3, 0, 3) ❌

It means our SimpleMDE is well initialized but there is no communication of value between the widget and SimpleMDE editor.

Communication between SimpleMDE and the widget

Initialize SimpleMDE with data value

The first test we will try to pass is Initial Value of SimpleMDE should be set. To do so, we will refer to the SimpleMDE documentation on setting and getting value.

We see that there is a simple method set("value") but also an initialValue that can be passed at instantiation. We will choose the second solution and make these changes to the start function of our widget:

start: function () {
    if (this.mode === 'edit') {
        var $textarea = this.$el.find('textarea');
        this.simplemde = new SimpleMDE({
            element: $textarea[0],
            initialValue: this.value, // this.value represents widget data
        });
    }
    return this._super();
},

Now we run the tests again and surely see that our first test passed ✅

In the first part, we handled the _renderReadonly function, now that we work on edit mode we will override the function _renderEdit to set the value into SimpleMDE, add these methods to the widget

    _formatValue: function (value) {
        return this._super.apply(this, arguments) || '';
    },

    _renderEdit: function () {
        this._super.apply(this, arguments);
        var newValue = this._formatValue(this.value);
        if (this.simplemde.value() !== newValue) {
            this.simplemde.value(newValue);
        }
    },

SimpleMDE can't handle false or null value so the function _formatValue is there to help us return an empty string when there is nothing in the field.

_renderEdit and _renderReadonly are called by the main _render function that is defined in odoo/addons/web/static/src/js/fields/abstract_field.js. This main render function handles the conditional logic of the widget being in Edit or Readonly mode and call the correct function:



    _render: function () {
        if (this.attrs.decorations) {
            this._applyDecorations();
        }
        if (this.mode === 'edit') {
            return this._renderEdit();
        } else if (this.mode === 'readonly') {
            return this._renderReadonly();
        }
    },

Again we run the tests and everything is still green ✅ so we can go to the next step.

Listening to change in SimpleMDE to update our widget value.

In our previous test, we wrote that markdownField._getValue() should be equal to what we write inside the SimpleMDE editor.

Naturally we will add that _getValue() function and make it return the inner value of SimpleMDE.

/**
 * return the SimpleMDE value
 *
 * @private
 */
_getValue: function () {
    return this.simplemde.value();
},

Since we have access to the property simplemde that we initialize in our widget it is very easy to get the data.

Then, to listen to changes, we have to get the CodeMirror instance of our SimpleMDE and listen to its change events that CodeMirror is triggering.

start: function () {
    if (this.mode === 'edit') {
        var $textarea = this.$el.find('textarea');
        this.simplemde = new SimpleMDE({
            element: $textarea[0],
            initialValue: this.value,
        });
        var self = this;
        this.simplemde.codemirror.on("change", function(){
            self._setValue(self.simplemde.value());
        })
    }
    return this._super();
},

We had to declare var self = this to be able to use it in the callback function.

With that change made let's run the tests again

The initial Value of SimpleMDE should be set@ 75 ms ✅
If we change the value in SimpleMDE, the value of the odoo widget should be updated@ 81 ms ✅
After Save, b should be present@ 380 ms ✅
After Save, should contain 'bold content' ✅

Victory !

Now that our tests passed we can try the module from the user perspective

Unfortunately, we can see that there is some problem with the aspect of our Markdown Editor.

It seems that the height is fixed so there is not enough space for it. This is coming from the fact that we are extending the FieldText widget and it has built-in auto-resize features.

In the next part, we will see how to deal with that as we improve our widget.

The source code for this tutorial is available here on GitHub.

✨ Update 17/06/2021 🎓 Third part is now available here

Thanks for reading, if you liked this article please consider:

☕️ Buying me a Coffee
🥳 Register on Codingdodo.com

Create an Odoo 14 Markdown Widget Field with TDD - Part 1

Coding Dodo — Thu, 06 May 2021 05:17:31 +0000

Introduction

In this tutorial, we will create a field widget for markdown content. The goal is to use Test Driven Development to make a robust module that we will improve in each chapter of this series.

We will walk through experimentation, the discovery of the core Odoo Javascript Framework and, refactoring. This series is made to be followed along, the source code of the module is available but the learning experience comes from the journey of writing tests that fail, making them pass, refactoring, and writing new tests.

We will not write our own JavaScript Markdown Editor, there is plenty of them out there. Instead, we will focus on using one that is battle-proven and usable in production and plug it inside Odoo JavaScript so it will be usable as a field Widget.

SimpleMDE

There is a lot of awesome JavaScript markdown editors but I settled for simpleMDE as a very easy embeddable Markdown Editor.

We will use simpleMDE underlying API to show content in Markdown into HTML when we see the field in read-only mode:

SimpleMDE.prototype.markdown("# My heading")

Will transform the Markdown content into <h1>My heading</h1>

And then to use the WYSIWYG editor we will use the library like that:

$textarea = $('textarea');
markdownEditor = new SimpleMDE({element: $textarea[0]});
// we now have access to events:
markdownEditor.codemirror.on("change", function(){
    console.log(markdownEditor.value())
})

Odoo widget module structure

This is the end result structure of our module:

├── LICENSE
├── README.md
├── __init__.py
├── __manifest__.py
├── static
│   ├── description
│   │   └── icon.png
│   ├── lib
│   │   ├── simplemde.min.css
│   │   └── simplemde.min.js
│   ├── src
│   │   ├── js
│   │   │   └── field_widget.js
│   │   └── xml
│   │   └── qweb_template.xml
│   └── tests
│   └── web_widget_markdown_tests.js
└── views
    └── templates.xml

Writing our firsts JavaScript tests

We are going to use TDD for the creation of our widget and in the spirit of TDD, we are writing the tests first.

There will be two basic tests:

On the form view, in read-only mode, the markdown content should be transformed into HTML, so a basic example test will be to check if the content of # My heading will be transformed into <h1>My heading</h1> by the simpleMDE library.
In edit mode, we should check that the simpleMDE WYSIWYG is correctly loaded

Including our test suite

First, we declare our tests inside views/templates.xml

<?xml version="1.0" encoding="UTF-8"?>
<odoo>

    <template id="qunit_suite" name="web_widget_markdowntest" inherit_id="web.qunit_suite">
        <xpath expr="." position="inside">
            <script type="text/javascript" src="/web_widget_markdown/static/tests/web_widget_markdown_tests.js" />
        </xpath>
    </template>

</odoo>

Every time you add JS tests to your module, the mode itself should have web as a dependency, as you see we inherit the web.qunit_suite template.

Creating our JavaScript test file

Then we create our test file inside static/tests/ named web_widget_markdown_tests

Basics of a test file:

odoo.define('web_widget_markdown_tests', function (require) {
    "use strict";
    var FormView = require('web.FormView');
    var testUtils = require('web.test_utils');

    QUnit.module('Markdown Widget Tests', {}, function () {
        QUnit.only('Test something', async function(assert) {
            assert.expect(1); // number of assertion we have in this
            assert.strictEqual(1, true);
        })
    })
 })

Explanation:

We pull 2 modules that we will need:

FormView will allow us to define a "fake" (mock) view that will hold our fields and one field with our widget applied to it
testUtils is used to simulate actions and other useful things using it like that testUtils.form.clickEdit(form) to go into Edit mode.

The whole suite of tests is defined by Qunit.module('Name of my suite', {}, function () {});. The first argument is the name of the suite, second is options that we will use later to pass mock data usable by all the test functions. The third argument is the function that will contain all our individual tests.

A single test is defined by QUnit.test('Test something', async function(assert) {}). Note that we wrote Qunit.only(... to run only that test. If you write QUnit.test and go to /web/tests you will see that it will run all the tests.

Remember to always put back QUnit.test( instead of QUnit.only( or else, tests written by other modules will never be executed

Running test

After installing your module with only these 2 files (the XML and the basic JS test), open your browser at http://localhost:8069/web/tests/ and should see:

Seeing our first test fail

Writing better tests

Okay, now that everything is working fine we will create better tests:

QUnit.module('Markdown Widget Tests', {
    beforeEach: function () {
        this.data = {
            blog: { 
                fields: {
                    name: {
                        string: "Name", 
                        type: "char"
                    },
                    content: { 
                        string: "Content", 
                        type: "text"
                    },
                },
                records: [
                    {
                        id: 1, name: "Blog Post 1", 
                        content: "# Hello world",
                    }
                ]
            }
        };
    }}, 
    function () {
        QUnit.only('web_widget_markdown test suite', async function(assert) {
            assert.expect(2);
            var form = await testUtils.createView({
                View: FormView,
                model: 'blog',
                data: this.data,
                arch: '<form string="Blog">' +
                        '<group>' +
                            '<field name="name"/>' +
                            '<field name="content" widget="markdown"/>' +
                        '</group>' +
                    '</form>',
                res_id: 1,
            });
            assert.strictEqual(
                form.$('.o_field_markdown').find("h1").length, 
                1, 
                "h1 should be present"
            );
            assert.strictEqual(
                form.$('.o_field_markdown h1').text(), 
                "Hello world", 
                "<h1> should contain 'Hello world'"
            );
            form.destroy();
        });
    }
);

SetUp in beforeEach

As the second argument of the QUnit.module() call we run some test set-up inside which we create some mock data that represent a basic blog post and assigning it to this.data, it will be run before each test and available inside each function.

Creating a mock FormView

With, we create a fake FormView using the data we defined in the setUp beforeEach. The structure of the form is very basic but the important part is that we apply the widget "markdown" on the field content

<field name="content" widget="markdown"/>

Creating the widget to make our tests pass

The next logical step is to create the actual widget and making it pass our basic test suite.

Including external JavaScript library - SimpleMDE

To pass our tests to green we need to actually create the widget. But before that, we will pull the simpleMDE library inside our module folder

mkdir web_widget_markdown/static/lib && cd web_widget_markdown/static/lib
wget https://raw.githubusercontent.com/sparksuite/simplemde-markdown-editor/master/dist/simplemde.min.js .
https://raw.githubusercontent.com/sparksuite/simplemde-markdown-editor/master/dist/simplemde.min.css .

We include these files inside views/templates.xml by inheriting web.assets_backend to place our external library inside. web.assets_backend contains all the JavaScript and CSS/SCSS file inclusions that are used by the WebClient.

<template id="assets_backend" inherit_id="web.assets_backend">
        <xpath expr="." position="inside">
            <link rel="stylesheet" href="/web_widget_markdown/static/lib/simplemde.min.css"/>
            <script src="/web_widget_markdown/static/lib/simplemde.min.js"></script>
        </xpath>
    </template>

Defining our Odoo widget

Now is the time to create our Odoo Widget. The widgets are defined with a JavaScript file and a specific syntax (more on that later). Widgets can have an external template in an XML file when their render and edit structures are more sophisticated. We will create a template later in this tutorial for our widget.

The Javascript File

For the JavaScript side, we go inside static/src/js/ and will create a file named field_widget.js with the minimal content to make our test pass:

odoo.define('web_widget_markdown', function (require) {
"use strict";
var fieldRegistry = require('web.field_registry');
var basicFields = require('web.basic_fields');

var markdownField = basicFields.FieldText.extend({
    supportedFieldTypes: ['text'],
    className: 'o_field_markdown',

    _renderReadonly: function () {
        this.$el.html("<h1>Hello world</h1>");
    },
});

fieldRegistry.add('markdown', markdownField);

return {
    markdownField: markdownField,
};
});

And don't forget to add it to our views/templates.xml file inside the assets_backend template definition, after the inclusion of the simpleMDE external library:

<script src="/web_widget_markdown/static/src/js/field_widget.js" type="text/javascript" />

Explanation of the widget content

First of all, a widget file is defined inside odoo.define(). We import the necessary module; most of them are in the core Odoo web addon folder.

The newly created Field has to be registered by Odoo with fieldRegistry.add('markdown', markdownField);

and then exported by returning it return {markdownField: markdownField,}

For this very example, to pass the tests, the markdownField is a JavaScript object that extends (heritage in Odoo JS Framework) the basic FieldText (that inherit InputField). Our objective is to have the standard behavior of a text field (used for Text) and override the _renderReadonly method to display something different than the value.

The Odoo FieldText transforms the Dom node of your widget into a <textarea> in edit mode. We can see it in odoo/addons/web/static/src/js/fields/basic_fields.js

init: function () {
    this._super.apply(this, arguments);

    if (this.mode === 'edit') {
        this.tagName = 'textarea';
    }
    this.autoResizeOptions = {parent: this};
},

This behavior is the closest to our expected result so we are inheriting that widget to gain time.

In our widget, we defined the className property to add our class .o_field_markdown to identify our widget in the DOM. Also, it is used in our tests to check widget behavior.

The $el property of a widget

$el property accessible inside the Widget holds the JQuery object of the root DOM element of the widget. So in this case we use the JQuery HTML function to inject the content <h1>Hello World</h1> inside the $el to pass this test. In TDD the workflow is to make the tests pass with minimum effort, then write new tests, refactor to make it pass again, etc...

After updating the module and going to http://localhost:8069/web/tests/ we can see that our tests pass!

Improving our tests and refactoring the widget

Adding more tests

We will add another test to make our test suite slightly more robust and see if our current implementation of the widget still holds up (Spoiler alert: it won't).

QUnit.test('web_widget_markdown readonly test 2', async function(assert) {
    assert.expect(2);
    var form = await testUtils.createView({
        View: FormView,
        model: 'blog',
        data: this.data,
        arch: '<form string="Blog">' +
                '<group>' +
                    '<field name="name"/>' +
                    '<field name="content" widget="markdown"/>' +
                '</group>' +
            '</form>',
        res_id: 2,
    });
    assert.strictEqual(
        form.$('.o_field_markdown').find("h2").length, 
        1, 
        "h2 should be present"
    )
    assert.strictEqual(
        form.$('.o_field_markdown h2').text(), 
        "Second title", 
        "<h2> should contain 'Second title'"
    )
    form.destroy();
});

We changed "QUnit.only" to "QUnit.test" to run multiple tests and then in the test interface we searched for the "Markdown Widget" module to run only them:

Now the tests are failing because we are always injecting <h1>Hello world</h1 as the value!

Refactoring the widget

The value property

Every widget inheriting InputField, DebouncedField or even AbstractField hold their value inside a value property. So inside the _renderReadonly method, we use the same logic as before, injecting directly the HTML content inside the $el. But this time we will use the underlying markdown function of the SimpleMDE library to parse this.value and return the HTML transformed version.

This is the new field_widget.js

odoo.define('my_field_widget', function (require) {
"use strict";
var fieldRegistry = require('web.field_registry');
var basicFields = require('web.basic_fields');

var markdownField = basicFields.FieldText.extend({
    supportedFieldTypes: ['text'],
    className: 'o_field_markdown',
    jsLibs: [
        '/web_widget_markdown/static/lib/simplemde.min.js',
    ],

    _renderReadonly: function () {
        this.$el.html(SimpleMDE.prototype.markdown(this.value));
    },
});

fieldRegistry.add('markdown', markdownField);

return {
    markdownField: markdownField,
};
});

We added the external JavaScript library SimpleMDE in the jsLibs definition of our widget.

Running the tests again now gives us :

Victory! 😊

Simulating Edit mode in our test suite

The current use case of our widget will be, going into Edit mode, writing markdown, Saving, and then seeing it rendered as HTML.

This what we will simulate in this new test function by using some of the most useful functions in the testUtils module.

QUnit.test('web_widget_markdown edit form', async function(assert) {
    assert.expect(2);
    var form = await testUtils.createView({
        View: FormView,
        model: 'blog',
        data: this.data,
        arch: '<form string="Blog">' +
                '<group>' +
                    '<field name="name"/>' +
                    '<field name="content" widget="markdown"/>' +
                '</group>' +
            '</form>',
        res_id: 1,
    });
    await testUtils.form.clickEdit(form);
    await testUtils.fields.editInput(form.$('.o_field_markdown'), ' **bold content**');
    await testUtils.form.clickSave(form);
    assert.strictEqual(
        form.$('.o_field_markdown').find("strong").length, 
        1, 
        "b should be present"
    )
    assert.strictEqual(
        form.$('.o_field_markdown strong').text(), 
        "bold content", 
        "<strong> should contain 'bold content'"
    )
    form.destroy();
});

What is happening inside the test?

We create the mock form similar to the other 2 tests. Then we simulate the click on Edit button with clickEdit. After that, we edit the input with editInput and write some markdown that we will test after. Finally, we simulate the user hitting the Save button via clickSave .

Odoo versions compatibility

clickEdit and clickSave are new functions in the file odoo/addons/web/static/tests/helpers/test_utils_form.js present from Odoo 12 and onwards.

If you use Odoo 11, replace these calls with that

// instead of await testUtils.form.clickEdit(form);
form.$buttons.find(".o_form_button_edit").click();

// intead of await testUtils.form.clickSave(form);
form.$buttons.find(".o_form_button_save").click();

Run the tests again on your browser and you will see that it passes! 🥳

Conclusion

This is already running quite long and for now, our widget is functional in render and edit mode. In the next part, we will add the Markdown Editor itself instead of the <textarea> tag to make it easier for the user to write.

We will view more types of Fields, create a template and change our tests to take into consideration the change of input type.

The code for this Part 1 of the tutorial is available here on Github.

Part 2 of this tutorial is already available at Coding Dodo.

Thanks for reading, if you liked this article please consider:

☕️ Buying me a Coffee
🥳 Register on Codingdodo.com

Working with Dates in Odoo - Analysis and Use Cases

Coding Dodo — Thu, 22 Apr 2021 00:01:00 +0000

Working with Dates and Datetime can be very complicated, especially when you take into account TimeZone. In this how-to guide, we will go through Odoo's source code to analyze and make sense of it all. Then we will review common use cases around this topic in reports, website, backend, ORM, and hopefully dispel some of the mystery.

This analysis will cover Odoo versions 12, 13, 14, and onwards.

Analysis

In this section, we will analyze how Odoo works from experimentation and Code Analysis.

Consider the following basic model

# -*- coding: utf-8 -*-
from odoo import models, fields

class BlogPost(models.Model):
    _name = 'blog.post'
    _description = 'Blog Post'

    name = fields.Char('Title', required=True)
    date_release = fields.Date('Release Date')
    # write_date hidden field present on all models as a fields.Datetime

date_release is a Date field and write_date (filled by Odoo when a user updates the model) is a Datetime field.

The record we will analyze has been last updated from a computer located in Indian/Reunion (UTC + 4) at 20:14:11.

So in UTC the write date should be 16:14:11

With that knowledge, let's dive in.

From Odoo 12.0 onwards, Dates and Datetimes are python objects.

One of the big changes that came in Odoo 12.0 was that Odoo Field returns always native Python objects, so no more fields.Date/Datetime.from_string is needed.

For converting old-style Date/Datetimes strings to Python objects, use fields.Date.to_date , and fields.Datetime.to_datetime methods.

How does it work In the Backend?

Odoo ORM

Let's see what happens when we do some basic operations with the ORM.

blogpost = self.env['blog.post'].search([], limit=1)

type(blogpost.date_release)
# <class 'datetime.date'>
blogpost.date_release
# datetime.date(2021, 4, 14)
str(blogpost.date_release)
# 2021-04-14

type(blogpost.write_date)
# <class 'datetime.datetime'>
blogpost.write_date
# datetime.datetime(2021, 4, 7, 16, 14, 11, 776876)
str(blogpost.write_date)
# 2021-04-07 16:14:11.776876

Datetime and Date objects are well documented here but these are some of the things we need to know:

String representation

For a date d, str(d) is equivalent to d.isoformat().
For a datetime instance d, str(d) is equivalent to d.isoformat(' ').

This string representation happens automatically when you try for example to log the Date into a string or do a string format function.

ORM Datetime objects are naive.

Datetime objects can be "aware" or "naive" and the one returned by Odoo ORM is naive , it can be verified by the fact that the property tzinfo of the object is None.

print(blogpost.write_date.tzinfo)
# None

Is it aware of the user timezone or timezone context?

Inside odoo _context dictionary there is a key called tz that can be filled with the timezone name, eg 'Europe/Brussels' or 'Indian/Reunion'.

Consider these two users

res.users(2,) has timezone set to 'Indian/Reunion'
res.users(6,) has timezone set to 'Europe/Berlin'  In these experiments, consider the current _uid is either user with id 2 or with id 3. And that these users initiated the action leading to these python pieces of code execution.

blogpost_user2 = self.env['blog.post'].with_user(2).browse(1)

blogpost_user2.env.user.tz
# >> 'Indian/Reunion'

blogpost_user2._context
# >> {'lang': 'en_US', 'tz': 'Indian/Reunion', 'uid': 2, 'allowed_company_ids': [1]}

str(blogpost_user2.write_date)
# >> 2021-04-07 16:14:11.776876

blogpost_user6 = self.env['blog.post'].with_user(6).browse(1)

blogpost_user6.env.user.tz
# >> 'Europe/Berlin'

blogpost_user6._context
# >> {'lang': 'en_US', 'tz': 'Europe/Berlin', 'uid': 6, 'allowed_company_ids': [1]}

str(blogpost_user2.write_date)
# >> 2021-04-07 16:14:11.776876

We can see that during the python execution via the ORM, the dates are always still UTC and not converted to the timezone of the user browsing even with context.

Dates and Datetime in PostgreSQL + psycopg

PostgreSQL

If we take a look into the database table description

    Column | Type | Collation | Nullable | Default
--------------+-----------------------------+-----------+----------+---------------------------------------
 id | integer | | not null | nextval('blog_post_id_seq'::regclass)
 name | character varying | | not null |
 date_release | date | | |
 state | character varying | | |
 content | text | | |
 write_date | timestamp without time zone | | |

We can see that fields.Date create a date type and fields.Datetime create a timestamp without time zone column type in PostgreSQL.

 id | date_release | write_date
----+--------------+----------------------------
  1 | 2021-04-14 | 2021-04-07 16:14:11.776876

Odoo stores the Datetime in the database as UTC timestamps.

psycopg

Now if we use the env cursor in Odoo to do our own requests

self.env.cr.execute("SELECT write_date, date_release FROM blog_post where id = 1")
self.env.cr.fetchall()
# results: [(datetime.datetime(2021, 4, 7, 16, 14, 11, 776876), datetime.date(2021, 4, 14))]

We can see that psycopg transforms the Dates and Datetimes into python's respective objects.

Again these Datetimes are in UTC.

How does Odoo convert to Timezone?

In WebClient views

We saw that Odoo ORM doesn't do any conversion when fetching data even with a context or with a specific user, without extra work. Still, when we view the records from the client-side they appear in our Timezone.

Computer with a clock set to 'Indian/Reunion' (UTC +4), from user 2 with tz 'Indian/Reunion' (UTC +4):

Webclient view user 2 Indian/Réunion

Computer with a clock set to 'Indian/Reunion' (UTC +4), from user 6 with tz 'Europe/Berlin' (UTC + 2 // summer):

Webclient view user 6 Europe/Berlin

We can see that a timezone conversion happened into UTC +4, but it took into account only our Browser client clock and not the timezone set as a setting for the user.

Network response from the client

{
    author_ids: [26]
    content: "..."
    date_release: "2021-04-14"
    display_name: "Installation"
    id: 1
    name: "Installation"
    state: "published"
    write_date: "2021-04-07 16:14:11"
}

Then inside odoo/addons/web/static/src/js/views/abstract_model.js the function _parseServerValue handle the conversion of the field from string to Moment object

/**
 * Processes date(time) and selection field values sent by the server.
 * Converts data(time) values to moment instances.
 * Converts false values of selection fields to 0 if 0 is a valid key,
 * because the server doesn't make a distinction between false and 0, and
 * always sends false when value is 0.
 *
 * @param {Object} field the field description
 * @param {*} value
 * @returns {*} the processed value
 */
_parseServerValue: function (field, value) {
    if (field.type === 'date' || field.type === 'datetime') {
        // process date(time): convert into a moment instance
        value = fieldUtils.parse[field.type](value, field, {isUTC: true});
    } else if (field.type === 'selection' && value === false) {
        // process selection: convert false to 0, if 0 is a valid key
        var hasKey0 = _.find(field.selection, function (option) {
            return option[0] === 0;
        });
        value = hasKey0 ? 0 : value;
    }
    return value;
},

This function calls the parse function of the 'web.field_utils' module defined in odoo/addons/web/static/src/js/fields/field_utils.js the will then call the parseDateTime function when it sees that the field is of type datetime.

function parseDateTime(value, field, options) {
    if (!value) {
        return false;
    }
    var datePattern = time.getLangDateFormat(),
        timePattern = time.getLangTimeFormat();
    var datePatternWoZero = datePattern.replace('MM','M').replace('DD','D'),
        timePatternWoZero = timePattern.replace('HH','H').replace('mm','m').replace('ss','s');
    var pattern1 = datePattern + ' ' + timePattern;
    var pattern2 = datePatternWoZero + ' ' + timePatternWoZero;
    var datetime;
    const smartDate = parseSmartDateInput(value);
    if (smartDate) {
        datetime = smartDate;
    } else {
        if (options && options.isUTC) {
            value = value.padStart(19, "0"); // server may send "932-10-10" for "0932-10-10" on some OS
            // phatomjs crash if we don't use this format
            datetime = moment.utc(value.replace(' ', 'T') + 'Z');
        } else {
            datetime = moment.utc(value, [pattern1, pattern2, moment.ISO_8601]);
            if (options && options.timezone) {
                datetime.add(-session.getTZOffset(datetime), 'minutes');
            }
        }
    }
    // ...

the getTZOffset just calls the basic Date JavaScript object function getTimezoneOffset so there is no user Timezone / Context timezone taken into consideration. It is purely based on the Client Browser Timezone.

Inverse operations are done when sending RPC calls to the server, the UTC value of the moment object is sent as data.

In reports

Consider this simple Report document

<template id="report_blog_post">
    <t t-call="web.html_container">
        <t t-foreach="docs" t-as="o">
            <t t-call="web.external_layout">
                <div class="page">
                    <h2 t-field="o.name"></h2>
                    <p>Write date <span t-field="o.write_date"/></p>
                    <div>
                        <div t-field="o.content"></div>div>
                    </div>
                </div>
            </t>
        </t>
    </t>
</template>

Same computer setup set in Timezone UTC +4 'Indian/Reunion'.

For our User 2 with Timezone "Indian/Reunion" (UTC +4), the report gives us

Report with user 2 Indian/Reunion

From the same computer, User 6 with Timezone "Europe/Berlin" (UTC + 2), the report gives us

Report with user 6 Europe/Berlin

How does it work?

In the file odoo/odoo/addons/base/models/ir_qweb_fields.py

class DateTimeConverter(models.AbstractModel):
    _name = 'ir.qweb.field.datetime'
    _description = 'Qweb Field Datetime'
    _inherit = 'ir.qweb.field'

    @api.model
    def value_to_html(self, value, options):
        if not value:
            return ''
        options = options or {}
        // value is 2021-04-07 16:14:11.776876

        lang = self.user_lang()
        locale = babel_locale_parse(lang.code)
        format_func = babel.dates.format_datetime
        if isinstance(value, str):
            value = fields.Datetime.from_string(value)

        value = fields.Datetime.context_timestamp(self, value)
        // value is 2021-04-07 20:14:11.776876+04:00
        //...

context_timestamp is a static function on the field Datetime Class and is used to convert to the timezone passed in context or fallback to the timezone of the user via record.env.user.tz.

In Website/Portal views

For website and portal views, it works the same way as in a report, the browser client timezone is not used.

<div class="col-xs-12">
    <t t-foreach="blog_posts" t-as="blog_post">
        <h3 t-field="blog_post.name"></h3>
        Last updated <span t-field="blog_post.write_date"/>
        <br/>
        Test context-timestamp: <span t-esc="blog_post.write_date" t-options="{'widget': 'datetime'}"/>
        <br/>
        Test Europe/Berlin: <span t-esc="blog_post.write_date" t-options="{'widget': 'datetime', 'tz_name': 'Europe/Berlin'}"/>
        <hr/>
    </t>
</div>

With user 2 (Preference TZ is set to 'Indian/Reunion')

Website view with user 2

Using t-field on a real Datetime field or using the options widget 'datetime' helps us achieve the converted timezone display.

How does it work?

It works the same way as in reports, using the DateTimeConverter function value_to_html.

So, be careful when you get user input from the website, you should convert it to UTC before sending it to the server if you use Moment.js and handle the ajax request yourself.

During export

When you use the Odoo export functionality, the browser Timezone is not taken into consideration.

For our User 2 with Timezone "Indian/Reunion" (UTC +4), the CSV export gives us

"Title","Release Date","Last Updated on"
"Installation","2021-04-14","2021-04-07 20:14:11"

From the same computer, User 6 with Timezone "Europe/Berlin" (UTC +2), the CSV export contains

"Title","Release Date","Last Updated on"
"Installation","2021-04-14","2021-04-07 18:14:11"

How does it work?

The logic is contained inside odoo/odoo/fields.py inside the Datetime Field.

def convert_to_export(self, value, record):
    if not value:
        return ''
    value = self.convert_to_display_name(value, record)
    return self.from_string(value)

def convert_to_display_name(self, value, record):
    assert record, 'Record expected'
    return Datetime.to_string(Datetime.context_timestamp(record, Datetime.from_string(value)))

The convert_to_export method is used on every field to add some presentation layer when the fields are to be exported. Here we can see that the context_timestamp is used to calculate the Datetime into the user Timezone.

This timezone is fetched from the record._context.get('tz) , or record.env.user.tz. So the record browsed must have the correct info either by having the correct User that did the action or with_context() specifying the Timezone.

Dates and Datetimes common use cases

Now let's go over some common uses

Assign the current Datetime to a field in ORM

You should assign written value in UTC so use this utility function

my_model.write({
    'datetime_field': fields.Datetime.now()
})

Using Python basic datetime.now() is not good enough because you will have to remove microseconds to comply with the server Datetime default format

Assign the current Date to a field in ORM

my_model.write({
    'date_field': fields.Date.context_today(my_model)
})

context_today expect a record as the argument so either give it self, containing the record you are on, or an explicit record. The function itself will:

Look inside the _context of the record and search for the tz key containing the name of the timezone.
Or fall back to the record.env.user.tz value.

Set a Datetime as Now + 600 seconds

Let's say you need to set a short expiration Datetime for some token access or any short-time access record. You will want to have an expiration Datetime 10 min in the future:

my_model.write({
    'token_expiration_datetime': fields.Datetime.now() + timedelta(minutes=10) 
})

now() function on Datetime class is in UTC.

Example uses in search method of the ORM

Get records younger than 3 days old

Date Field

from odoo import fields
from dateutil.relativedelta import relativedelta

date_limit = fields.Date.context_today(self) - relativedelta(days=3)
results = self.env['my.model'].search([
    ('my_date_field', '>' date_limit)
])

Datetime Field

from odoo import fields
from dateutil.relativedelta import relativedelta

datetime_limit = fields.Datetime.now() - relativedelta(days=3)
results = self.env['my.model'].search([
    ('my_datetime_field', '>' datetime_limit)
])

See the relativedelta documentation for more information and be careful that -

singular arguments like year, hour, etc, REPLACE the corresponding value in the original Datetime
plural arguments like years, hours, etc, DO THE ARITHMETIC operation on the original Datetime.

For simpler operations that don't need REPLACING value of a Datetime and just do simple arithmetic operations, you can use timedelta

from odoo import fields
from datetime import timedelta

datetime_limit = fields.Datetime.now() - timedelta(days=3)
results = self.env['my.model'].search([
    ('my_datetime_field', '>' datetime_limit)
])

Example converting a Date to Datetime 7:00 AM

Let's say you have a Date and you want to transform it into a Datetime with hour 00:00:00

import datetime

# record.initial_date is for this example 2021-04-21
new_datetime = datetime.combine(record.initial_date, datetime.time(7, 0))

# We can also do
datetime.combine(record.initial_date, datetime.time.min).replace(hour=7)

Odoo Dates and Datetimes utils functions

Odoo gives us some useful functions to handle Dates and Datetimes manipulation that are located in odoo/odoo/tools/date_utils.py

`start_of` and `end_of`

Given a current Date or Datetime we can use these functions to get the boundaries of a time period surrounding it.

The granularity can be year, quarter, month, week, day, hour.

from odoo.tools import date_utils

today = fields.Date.today()
first_day = date_utils.start_of(today, 'week')
last_day = date_utils.end_of(today, 'week')

`date_range(start, end, step=relativedelta(months=1))` to get an iterator of Datetimes between start and end

from odoo.tools import date_utils

start = datetime.datetime(2021, 1, 1)
end = datetime.datetime(2021, 4, 1)

result = date_utils.date_range(start, end)

# result = [
# datetime.datetime(2021, 1, 1, 0, 0),
# datetime.datetime(2021, 2, 1, 0, 0),
# datetime.datetime(2021, 3, 1, 0, 0),
# datetime.datetime(2021, 4, 1, 0, 0),
# ]

`get_quarter` for the start and end Dates of the quarter surrounding a Date

from odoo.tools import date_utils

today = fields.Date.today()
quarter_start, quarter_end = date_utils.get_quarter(today)

`get_month` for the start and end Dates of the month surrounding a Date

from odoo.tools import date_utils

today = fields.Date.today()
month_start, month_end = date_utils.get_month(today)

Printing current Datetime (for user Timezone) in QWeb report

Inside a report, you have access to the context_timestamp function, you can see this inside the _render_template of base ir_actions_report.

# def _render_template(self, template, values=None):
values.update(
    time=time,
    context_timestamp=lambda t: fields.Datetime.context_timestamp(self.with_context(tz=user.tz), t),
    user=user,
    res_company=user.company_id,
    website=website,
    web_base_url=self.env['ir.config_parameter'].sudo().get_param('web.base.url', default=''),
)
return view_obj._render_template(template, values)

Note that you also have access to time and datetime module, so to print the current datetime:

<span t-esc="context_timestamp(datetime.datetime.now()).strftime('%Y-%m-%d %H:%M')"/>

Qweb filter on Date Last Week, Month, Year

<filter string="Last Week" 
        name="week" 
        domain="[('date','&gt;=', (context_today() - datetime.timedelta(days=7)).strftime('%%Y-%%m-%%d'))]"/>
<filter string="Last Month" 
        name="month" 
        domain="[('date','&gt;=', (context_today() - datetime.timedelta(days=30)).strftime('%%Y-%%m-%%d'))]"/>
<filter string="Last Year" 
        name="year" 
        domain="[('date','&gt;=', (context_today() - datetime.timedelta(days=365)).strftime('%%Y-%%m-%%d'))]"/>

Qweb filter on Datetime last 24h hours.

<filter string="Last 24h"
        name="last_24h"  
        domain="[('start_date','&gt;', (context_today() - datetime.timedelta(days=1)).strftime('%%Y-%%m-%%d') )]"/>

QWeb filter on Datetime: this week.

The goal here is to filter between last Monday 00:00 and next Monday 00:00

<filter name="start_date_filter" 
        string="This Week" 
        domain="[
('start_date', '>=', (datetime.datetime.combine(context_today() + relativedelta(weeks=-1,days=1,weekday=0), datetime.time(0,0,0)).to_utc()).strftime('%Y-%m-%d %H:%M:%S')),
('start_date', '&lt;', (datetime.datetime.combine(context_today() + relativedelta(days=1,weekday=0), datetime.time(0,0,0)).to_utc()).strftime('%Y-%m-%d %H:%M:%S'))
        ]"
/>

Let's explain this part

datetime.datetime.combine(context_today() + relativedelta(days=1,weekday=0), datetime.time(0,0,0)).to_utc()

We use context_today() to get the current Date
Add relativedelta that will, (in this order) add 1 day, then replace with Monday. The Monday chosen will automatically be the next Monday relative to the context_today + 1 day. So if we are on a current Monday it will get us the next Monday and if we are on a Sunday it will be also okay.
We combine this Date with a time representing midnight 0,0,0.
Convert back to UTC.

For the "Last Monday" it is the same logic by using weeks=-1 and then finding next Monday.

Basic use case on the Website/Portal

Displaying the datepicker with browser timezone in your template

This is the basic structure to have the Datepicker widget trigger in your website template

<form action="/ssg_post_update" method="POST" class="pl-0 col-6 ssg-blog-form">
    <input type="hidden" name="blog_post_id" t-att-value="blog_post.id" />
    <t t-set="datepickerID" t-value="'datepicker' + str(blog_post.id)"/>
    <div class="s_website_form_datetime input-group date" 
         t-att-id="datepickerID" 
         data-target-input="nearest">
        <t t-set='datetime_test'><t t-options='{"widget": "datetime"}' t-esc="blog_post.datetime_test"/></t>
        <input
            type="text"
            class="form-control datetimepicker-input s_website_form_input"
            t-attf-data-target="##{datepickerID}"
            name="datetime_test"
            placeholder="Chose date"
            t-attf-id="datetime_test#{blog_post.id}"
            t-att-value="datetime_test"
        />
        <div class="input-group-append" t-attf-data-target="##{datepickerID}" data-toggle="datetimepicker">
            <div class="input-group-text">
                <i class="fa fa-calendar"></i>
            </div>
        </div>
    </div>
</form>

The problem here is that the value in the form is still a pure string in the Timezone of the user.

So if we submit it directly it will arrive on the server in an unadapted format and not in UTC. We could think that we have the user so we also have the user Timezone and with that, we could convert it to UTC before storing it. But Moment.js used by the datetimepicker base timezone on the Browser clock.

So it is better to handle it with JavaScript, by preventing the submit, converting data, and then send it.

var $form = $(ev.currentTarget);
ev.preventDefault();

// get the Moment.js Datetime object
let datetime_test = $form.find("input[name=datetime_test]").datetimepicker('viewDate').clone().locale('en');
let blog_post_id = parseInt($form.find("input[name=blog_post_id]").val());
// Convert to UTC
datetime_test.utc();
// Convert to SERVER FORMAT
datetime_test = datetime_test.format('YYYY-MM-DD HH:mm:ss')

this._rpc({
    route: "/ssg_post_update_json",
    params: {
        blog_post_id: blog_post_id,
        datetime_test: datetime_test
    },
}).then(function (data) {
    window.location.reload();
})

Now that we send data in UTC we can update our record directly in our controller

@http.route(['/ssg_post_update_json',], type='json', method="POST", auth="public", website=True, sitemap=True)
def ssg_post_update_json(self, blog_post_id, datetime_test, **kwargs):
    blog_post = request.env['blog.post'].browse(blog_post_id)
    if blog_post.exists():
        blog_post.write({
            'datetime_test': fields.Datetime.from_string(datetime_test)
        })
    return {}

Here we used fields.Datetime.from_string function to get a Datetime Python Object. But this is also correct:

# Insert directly as a string
blog_post.write({
    'datetime_test': datetime_test 
})

Be careful when you write directly as string, the Datetime must be in DATETIME_FORMAT which by default is %Y-%m-%d %H:%M:%S.

The string to Object conversion is done automatically in the to_datetime method inside the class Datetime(Field).

Moment.js

Moment.js has good documentation giving us examples of manipulations so I will advise you to read it to be more familiar.

The Moment.js object we are manipulating are oftentimes already converted into User Timezone so it is necessary to use utc() function when we send back data to be stored server-side.

Conclusion

To recap our analysis, internal handling of times in Odoo is done in UTC, and display in the web client is done with local time of the user's browser.

Be careful of the addons you install, if default Dates are set in UTC with time.strftime for example, causing problems when the time is near day breaks and offset, always use context_today.

If 2 users living in different places want to have identical reports they probably should switch their time to UTC. If you work with accountants they should be aware of that info and you should plan accordingly.

There is still a lot of examples I probably didn't think about, so please share them in the comment section and I will add them. The goal is to have an extensive set of common use cases for future developers to be comfortable working with Dates and Datetimes.

Thanks for reading, if you liked this article please consider:

☕️ Buying me a Coffee
🥳 Register on Codingdodo.com

Install and Deploy Odoo 14 from source on DigitalOcean

Coding Dodo — Sun, 04 Apr 2021 07:56:09 +0000

In this tutorial, we will deploy a production-ready Odoo 14 instance. Install it from GitHub source on a brand new DigitalOcean Droplet Ubuntu 20.04 (LTS) x64. What we will do:

Going through DigitalOcean registration
Installing all the Ubuntu 20.4 requirements necessary to install Odoo from the source
Using Pyenv to prepare our server for multiple python versions and virtualenvs in case you want to host other versions of Odoo
Creating odoo user and making Odoo run as a service
Install Let's Encrypt SSL Certificate
Making Odoo multiprocess and using Nginx as a reverse proxy
Basic security with ufw

DigitalOcean offers you 100€ credit to use in 6 months since you can create machines and destroy them quickly it's a great place to experiment with Odoo installs or to choose it as your production server!

Creating a DigitalOcean account

First of all, go to DigitalOcean and create an account using the link

DigitalOcean Register

Create your credentials, validate your email and follow the steps until you arrive on that page

DigitalOcean Register Choose Control panel

Here it can get a bit confusing because most of the links direct you to the DigitalOcean platform but we want the regular dashboard so click on Explore our control panel

When on the Control Panel click on Get Started with a Droplet or Create / Droplet to arrive on this screen

Create Ubuntu Droplet

Choose Ubuntu 20.04 and choose the right machine based on your needs. Remember that you are only billed for the time that the machine is up so you can choose a good machine and destroy it later. Choose at least 2 CPUs or everything will feel very slow.

Scrolling down you will see a space to add your ssh-key

Adding the SSH KEY

Adding SSH Key

If you don't have an SSH Key yet you have to generate it with the command. You probably already have an id_rsa.pub file in your .ssh folder. For this example, we will create a new SSH key that will be used to connect to our DigitalOcean Droplets. Feel free to skip that part or read it to create your first key or handle multiple ssh keys.

ssh-keygen -C "contact@codingdodo.com"

When prompted for the name of the file we choose that

/Users/codingdodo/.ssh/id_rsa_codingdodo

Show the content of the newly generated key:

cat ~/.ssh/id_rsa_codingdodo.pub

On DigitalOcean, click on New SSH Key and copy/paste the content printed out. Scroll down more and click on Create Droplet. It will take a minute then your Droplet will be ready

Droplet is Ready

Copy the IP Address , we will add it to our SSH config file to make things easier for us. If you handle multiple SSH Keys this is a nice way to handle with which SSH Key you connect to each server.

vim ~/.ssh/config

Add this section with your IP address and the name of the public key you created.

 Host testingdodo
   Hostname 143.198.123.151
   User root
   IdentityFile ~/.ssh/id_rsa_codingdodo
   IdentitiesOnly yes

We name our Host testingdodo so in our shell, we can type this shortcut to ssh into the machine.

ssh testingdodo

And answer yes to the security prompt, and you will be logged in

Welcome to Ubuntu 20.04.1 LTS (GNU/Linux 5.4.0-51-generic x86_64)

...

root@ubuntu-s-1vcpu-1gb-intel-nyc1-01:~#

Ubuntu 20.4 Prerequesites

We start by updating our packages

apt update

Installing PostgreSQL

apt install postgresql postgresql-contrib

We will later create a Unix user named Odoo, so we will create a PostgreSQL user with the same name. If you would prefer a different name, remember to keep that consistency to make things easier when you come back later to your environment.

su - postgres
createuser --interactive -P odoo

With the --interactive flag, PostgreSQL will ask us for a password and the privileges that will be given to our odoo PostgreSQL user.

Enter password for new role:
Enter it again:
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n

Next, we will already create that database that will hold our Odoo 14 instance. In this example, it's gonna be named coding_dodo.

createdb -O odoo codingdodo_demo
exit

The -O flag represents the owner of the database, we choose odoo because it's the name of the PostgreSQL user we created just before

Wkhtmltopdf

Wkhtmltopdf is used by Odoo to generate documents and is a necessary evil. We will pull the deb of version 0.12.6-2 from Github and install it

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-1/wkhtmltox_0.12.6-1.bionic_amd64.deb
apt install ./wkhtmltox_0.12.6-1.bionic_amd64.deb

Python dev dependencies, git, Node, and other requirements

apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
xz-utils tk-dev libffi-dev liblzma-dev python-openssl git libpq-dev libsasl2-dev libldap2-dev ccze node-less

Creating the Unix odoo user

useradd -m -U -r -s /bin/bash odoo

-r indicate that it's a system account so useradd will not create a home directory for such a user. We want a folder so we use -m

-U create a group and -s specify the shell that will be used.

Or if you don't want to have /home/odoo created to hold your odoo install and would prefer a different directory. This is an example that will create the home directory in /opt for example.

useradd -m -d /opt/odoo -U -r -s /bin/bash odoo

-d [path] indicates we want to create a home but in different place.

Preparing a good Python environment with Pyenv

Log in as the odoo user

The pyenv will be installed as the odoo system user. That user is gonna run the odoo instance as a service later.

su - odoo

Installing pyenv

curl https://pyenv.run | bash
echo 'export PATH="/home/odoo/.pyenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc
exec $SHELL

Installing python 3.9.2

pyenv install 3.9.2

Depending on the CPU power you choose, it may take some time, but in the end, you should see:

Installed Python-3.9.2 to /home/odoo/.pyenv/versions/3.9.2

Creating the virtualenv

pyenv virtualenv 3.9.2 odoo-14-env

Installing Odoo from GitHub source

Creating a folder for our custom addons (Optional)

mkdir /home/odoo/odoo-14-custom-addons

This is the folder you will use to store your custom addons. Be careful if you add the custom addon patch to the --addons-path command-line argument and there are no valid addons inside, it will not work.

To make it work we will clone our own module inside that folder

cd /home/odoo/odoo-14-custom-addons
git clone https://github.com/Coding-Dodo/web_widget_markdown.git
cd ~/

Pulling Odoo 14 and activating the virtualenv

We will pull Odoo version 14 with the -b flag for the branch and put it in a folder named odoo-14

git clone -b 14.0 --single-branch --depth 1 https://github.com/odoo/odoo.git odoo-14

Since we created our virtualenv called odoo-14-env, we will "park" it in the odoo-14 folder we just created. With that every time we cd into this folder it will activate our virtualenv.

cd odoo-14
pyenv local odoo-14-env

The prompt should change and you should see (odoo-14-env) odoo@ubuntu-s-1vcpu-1gb-intel-nyc1-01

Installing python dependencies

pip install --upgrade pip
pip install setuptools wheel
pip install -r requirements.txt -e .

If you see any error please refer to the part "Python dev dependencies, git, Node and other requirements" and make sure you installed everything.

Launching Odoo for the first time to test and generate a config file

We will test launch Odoo with some command-line arguments that will be saved in our Odoo configuration file

./odoo-bin --database=codingdodo_demo --db_user=odoo --db_password=codingdodo -i base --without-demo=all --save -c /home/odoo/.odoorc_codingdodo_demo --stop-after-init

If you chose to create a custom addons folder and it's not empty. The command will be


./odoo-bin --database=codingdodo_demo --db_user=odoo --db_password=codingdodo -i base --addons-path="/home/odoo/odoo-14/addons,/home/odoo/odoo-14-custom-addons" --without-demo=all --save -c /home/odoo/.odoorc_codingdodo_demo --stop-after-init

We directly typed the db name, user, and password and initialized it with the iflag.

--without-demo=all is used because we are installing a production-ready environment. If you want demo data, omit that flag.

With the -c flag we told odoo where the config file will be /home/odoo/.odoorc_codingdodo_demo

The --save flag is used to save everything we just typed into the newly created config file.

(Optional) Updating config file admin_passwd with a random strong password:

If you want to quickly change the password inside your config file

sed -i "s/\badmin\b/$(openssl rand -base64 32 | awk '{print $1}')/g" /home/odoo/.odoorc_codingdodo_demo

This will replace the line admin_passwd = admin with a new password randomly generated via OpenSSL.

To check what the new admin_passwd is:

cat /home/odoo/.odoorc_codingdodo_demo | grep admin_passwd

...
admin_passwd = C4Yiyiez4CHMl5tsmRHVZHflfnITd3nF5oXh8l3ZPc8=

Keep it somewhere safe because after running the instance it will be hashed.

Create the logs directory

We want our log files to be inside /var/log/odoo/ so we create that folder and give odoo user access to it.

mkdir /var/log/odoo
touch /var/log/odoo/odoo-14.log
chown odoo: /var/log/odoo
chown -R odoo: /var/log/odoo/*

vim /home/odoo/.odoorc_codingdodo_demo

Modify the config file to reflect that change

logfile = /var/log/odoo/odoo-14.log

Odoo as service

Log out of odoo user and create a service file

exit
vim /etc/systemd/system/odoo-14.service

Inside the file

[Unit]
Description=Odoo14
Requires=postgresql.service
After=network.target postgresql.service

[Service]
Type=simple
SyslogIdentifier=odoo-14
PermissionsStartOnly=true
User=odoo
Group=odoo
ExecStart=/home/odoo/.pyenv/versions/odoo-14-env/bin/python /home/odoo/odoo-14/odoo-bin -c /home/odoo/.odoorc_codingdodo_demo
StandardOutput=journal+console

[Install]
WantedBy=multi-user.target

Reload service

systemctl daemon-reload
systemctl enable --now odoo-14

Check status:

systemctl status odoo-14

Install Nginx and add SSL with Let's Encrypt

Installing Nginx

apt install nginx

Let's Encrypt with Certbot

Certbot will be used to install our first certificate and to renew it every months

apt install certbot

Generate a new set of 2048 bit DH parameters by typing the following command:

sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Let's Encrypt Nginx Snippet

Let's Encrypt need to do its acme-challenge to validate our domain name and creating the certificate with certbot. If we plan to install multiple instances / different domain names pointing to this server, it is a good habit to isolate the let's encrypt acme-challenge location to its custom snippet.

mkdir -p /var/lib/letsencrypt/.well-known
chgrp www-data /var/lib/letsencrypt
chmod g+s /var/lib/letsencrypt

We create a Let's Encrypt snippet

vim /etc/nginx/snippets/letsencrypt.conf

With this content

location ^~ /.well-known/acme-challenge/ {
  allow all;
  root /var/lib/letsencrypt/;
  default_type "text/plain";
  try_files $uri =404;
}

SSL Conf Nginx Snippet

vim /etc/nginx/snippets/ssl.conf

Copy-paste that content

ssl_dhparam /etc/ssl/certs/dhparam.pem;

ssl_session_timeout 1d;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers on;

ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;
resolver_timeout 30s;

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
add_header X-Frame-Options SAMEORIGIN;
add_header X-Content-Type-Options nosniff;

Create A Record with your DNS Provider pointing to the Droplet IP

For the following parts, you must have a domain name that will point to your droplet or else the acme-challenge of Let's Encrypt will not pass and you will not have SSL so the final Nginx config file will not apply to you.

Adding a domain name

Here we created a subdomain of codingdodo.com with an A record pointing to our Droplet IP Value.

Our final address will be odoo-14.codingdodo.com

Installing the Let's Encrypt certificate

In case the Odoo service is still running.

service odoo-14 stop

Basic Nginx Conf file to pass the Certbot acme-challenge

cd /etc/nginx/site-available
vim odoo-14.codingdodo.com

We will first create a basic Nginx conf file to pass certbot acme-challenge:

upstream odoo_14 {
 server 127.0.0.1:8069;
}

upstream odoochat_14 {
 server 127.0.0.1:8072;
}

server {
    listen 80;
    listen [::]:80;
    server_name odoo-14.codingdodo.com;
    include snippets/letsencrypt.conf;
}

Symlink your site declaration from site-available to site-enabled.

ln -s /etc/nginx/sites-available/odoo-14.codingdodo.com /etc/nginx/sites-enabled/odoo-14.codingdodo.com

Always test the config with nginx -t and if everything is okay we reload Nginx

service nginx reload

Certbot acme-challenge

It is now time to create our SSL certificate.

certbot certonly --agree-tos --email contact@codingdodo.com --webroot -w /var/lib/letsencrypt/ -d odoo-14.codingdodo.com

You should see

 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/odoo-14.codingdodo.com/fullchain.pem

Managing Auto renew

Let's Encrypt already created a cron in the crontab but Nginx needs to reload to take into consideration the new certificate so we will edit this file

vim /etc/letsencrypt/cli.ini

And add the line at the end.

deploy-hook = systemctl reload nginx

To test if our renew will work we can use the --dry-run flag to test it

certbot renew --dry-run

Final Nginx site conf for proxy mode multi workers

Now edit the odoo-14.codingdodo.com file again:

vim /etc/nginx/sites-available/odoo-14.codingdodo.com

upstream odoo_14 {
 server 127.0.0.1:8069;
}

upstream odoochat_14 {
 server 127.0.0.1:8072;
}

server {
    listen 80;
    listen [::]:80;
    server_name odoo-14.codingdodo.com;
    include snippets/letsencrypt.conf;

    location / {
        return 301 https://odoo-14.codingdodo.com$request_uri;
    }
}

server {
    listen 443 ssl http2 default_server;
    listen [::]:443;
    server_name odoo-14.codingdodo.com ;

    ssl_certificate /etc/letsencrypt/live/odoo-14.codingdodo.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/odoo-14.codingdodo.com/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/odoo-14.codingdodo.com/chain.pem;
    include snippets/ssl.conf;
    include snippets/letsencrypt.conf;

    proxy_buffers 16 64k;
    proxy_buffer_size 128k;

    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X_ODOO_DBFILTER "codingdodo_demo";
    proxy_next_upstream error timeout invalid_header http_500 http_502 http_503 http_504;

    location / {
        proxy_pass http://odoo_14;
    }

    location /longpolling {
        proxy_pass http://odoochat_14;
    }

    location ~* /web/static/ {
        proxy_cache_valid 200 60m;
        proxy_buffering on;
        expires 864000;
        proxy_pass http://odoo_14;
    }

    location ~* /website/image/ir.attachment/ {
        proxy_cache_valid 200 60m;
        proxy_buffering on;
        expires 864000;
        proxy_pass http://odoo_14;
    }

    gzip_types text/css text/less text/plain text/xml application/xml application/json application/javascript;
    gzip on;
}

Use nginx -t to test the new config and if everything is okay run

service nginx reload

Updating the Odoo config file

vim /home/odoo/.odoorc_codingdodo_demo

Now that we have our reverse proxy we need to modify/add these lines

proxy_mode = True
workers = 4
max_cron_threads = 1
limit_memory_hard = 2684354560
limit_memory_soft = 2147483648
limit_request = 8192
limit_time_cpu = 600
limit_time_real = 1200

The number of workers depends on the RAM and CPU you choose during the creation of your droplet. Refer to this official documentation to calculate the appropriate number of workers.

Server with 2 CPU, 4 Thread
30 concurrent users
30 users / 6 = 5 <- theorical number of worker needed
(2 * 2) + 1 = 5 <- theorical maximal number of worker
We’ll use 4 workers + 1 for cron.
RAM = 9 * ((0.8*150) + (0.2*1024)) ~= 3Go RAM for Odoo

Restart Odoo and see logs

service odoo-14 restart

Go to https://odoo-14.codingdodo.com and in the meantime on the server check the logs

tail -f /var/log/odoo/odoo-14.log | ccze

Setting the Firewall

ufw app list

If you followed this guide it should show you :

Available applications:
  Nginx Full
  Nginx HTTP
  Nginx HTTPS
  OpenSSH

First, we secure ssh connection

ufw allow OpenSSH

Now if you have installed Nginx with an SSL certificate

ufw allow 'Nginx Full'
ufw enable

Create a sudo user for day to day actions

adduser codingdodo

usermod -aG sudo codingdodo

rsync --archive --chown=codingdodo:codingdodo ~/.ssh /home/codingdodo

With DigitalOcean we already uploaded our ssh-key to the authorized_keys of the root so we are using Rsync to copy the folder with a new owner.

Wrapping up

This is the final Odoo config file

[options]
addons_path = /home/odoo/odoo-14/addons,/home/odoo/odoo-14-custom-addons
admin_passwd = $pbkdf2-sha512$25000$TwkBoDRGqBUi5LyXMiaE8A$SUyyCVfU1jk0YqiuTbHqVNmT31jw33fyh6tLMkA6t6lLSKpbnutYuQ.dVwQ2wIgWs2hf1OQmhNcHR9ofqGtSFg
csv_internal_sep = ,
data_dir = /home/odoo/.local/share/Odoo
db_host = False
db_maxconn = 64
db_name = codingdodo_demo
db_password = codingdodo
db_port = False
db_sslmode = prefer
db_template = template0
db_user = odoo
dbfilter =
demo = {}
email_from = False
geoip_database = /usr/share/GeoIP/GeoLite2-City.mmdb
http_enable = True
http_interface =
http_port = 8069
import_partial =
limit_memory_hard = 2684354560
limit_memory_soft = 2147483648
limit_request = 8192
limit_time_cpu = 60
limit_time_real = 120
limit_time_real_cron = -1
list_db = False
log_db = False
log_db_level = warning
log_handler = :INFO
log_level = info
logfile = /var/log/odoo/odoo-14.log
longpolling_port = 8072
max_cron_threads = 2
osv_memory_age_limit = False
osv_memory_count_limit = False
pg_path =
pidfile =
proxy_mode = True
reportgz = False
screencasts =
screenshots = /tmp/odoo_tests
server_wide_modules = base,web
smtp_password = False
smtp_port = 25
smtp_server = localhost
smtp_ssl = False
smtp_user = False
syslog = False
test_enable = False
test_file =
test_tags = None
transient_age_limit = 1.0
translate_modules = ['all']
unaccent = False
upgrade_path =
without_demo = all
workers = 2

And that's it for today. We will still need to do daily backups for our database and our filestore (located at

/home/odoo/.local/share/Odoo/filestore/codingdodo_demo)

Thanks for reading, if you liked this article please consider:

☕️ Buying me a Coffee
🥳 Register on Codingdodo.com

Forem: Coding Dodo

OWL in Odoo 14 - How to extend and patch existing OWL Components.

Introduction

Odoo OWL utils patch, and patchMixin functions.

With the patchMixin, the Component exposes a "patch" function.

Import "web.utils", patch function for a "non-patchable" Component as a last resort.

Patchable Component (returned with "patchMixin"): Extend, monkey-patch, override.

Basic syntax

Example: the ControlPanel Component.

Describing the functionality.

Implementing the code

Non-Patchable Component: Override a regular function with "web.utils" patch.

Example: the FileUpload Component.

Describing the functionality

Implementing the code.

Non-patchable Component: Override the "getter" of an OWL Component.

Describing the problem

Solution 1 - Redefining prototype property.

Solution 2 - Putting the defineProperty inside the Component setup function (overridable).

Solution 3 - Force apply the "patchMixin" on the Component and replace it in the Components tree.

Conclusion

Coding-Dodo / owl_tutorial_extend_override_components

This is repository with examples on how to extend, override and monkey patch OWL Components in Odoo v14

Coding Dodo - OWL Tutorial Extend/Override Components

Author

RealWorld App with OWL (Odoo Web Library) - Part 1

What is the RealWorld App?

gothinkster / realworld

"The mother of all demo apps" — Exemplary fullstack Medium.com clone powered by React, Angular, Node, Django, and many more 🏅

Stay on the bleeding edge — join our GitHub Discussions! 🎉

See how the exact same Medium.com clone (called Conduit) is built using different frontends and backends. Yes, you can mix and match them, because they all adhere to the same API spec 😮😎

Implementations

Create a new implementation

Introducing OWL Framework(Odoo Web Library)

Components

Hooks and reactivity

Passing data from Parent to Child via props

Starting our project

Prerequisites

Using the OWL starter template

Coding-Dodo / OWL-JavaScript-Project-Starter

OWL JavaScript Project Starter with Rollup

OWL Javascript Project Starter

Features

Installation

Components

App Component

Installing dependencies and running the dev server.

Importing styles from RealWorld App resources kit.

Implementing the elements of the layout as Components.

Creating the Navbar Component

Creating the Footer Component

Creating the Home Page Component

Injecting our components into the main App Component

Update the tests to check that everything is working correctly.

Implementing the different Pages Components of the App.

Settings Page

LogIn Page

Register Page

Profile Page

Editor Page

OWL Router to the rescue

Creating the routes and adding the router to the env

Using <RouteComponent/>.

Adding the <Link> Components to handle navigation.

Creating our custom NavbarLink component via inheritance.

Conclusion

Create an Odoo 14 Markdown Widget Field with TDD - Part 3

Introduction

Managing the built-in the auto-resize of FieldText

Analysis

Updating the QWeb Template of our widget?

What do we actually use from FieldText or InputField?

Refactoring our widget to extend DebouncedField

Updating the Field declaration

Handling KeyUp/Down events

Directly bind CodeMirror changes to the debounceActions

Making our widget translatable

Writing the test suite for our translatable field

Explaining the test suite

Solution 2 - Putting the `defineProperty` inside the Component `setup` function (overridable).

Using `<RouteComponent/>`.

Adding the `<Link>` Components to handle navigation.