[REF] mail: JS mail refactoring

----------------------
 Summary
----------------------

The purpose of this commit is to improve the JS code of the `mail` module.
It applies the new coding guidelines and makes some changes on the design
of some modules, such as the old ChatManager module.

Here is a short summary of the changes that have been made:

  1. New coding guidelines
    - snake_case to camelCase
    - prefix private attributes and methods with '_'
    - jsdoc on most methods
    - one class per module
  2. Rename/Merge some classes
    - 'chat manager' becomes 'mail manager' (internal) and 'mail service' (external)
    - 'chat window manager' is now included in mail manager
    - 'thread' widget now named 'thread widget'
  3. New model abstraction for mail objects:
    - modules 'mail.model.*'
    - modeling:

                    0..1    0..1        *     *
      ThreadWindow  <------>  Thread <-------> Message
                              /    \
                             /      \
              Thread With Cache     Document Thread
               /      |       \
              /       |        \
        Mailbox    Channel    Support Channel
                      |
                      |
                      DM

    - Thread: the superclass of threads.
    - ThreadWindow: the window component of a thread.
    - Message: mail objects representing messages.
    - Thread With Cache: threads that can be used with search view (Discuss app compatible).
    - Document Thread: represents the thread part of a chatter.
    - Mailbox: represents what was previously called 'static' channel, e.g. 'Inbox'.
    - Channel: mail objects representing channels, including livechat.
    - DM: special kind of Channel for 1:1 communication in the backend.
    - Support Channel: special channel for im_support module.

  This new modeling approach let us easily add features on all threads, such as the
  possibility to put any thread in a small window.

----------------------
 Known issues
----------------------

 [Already Present in Master]

    1. When the Discuss app is in the background with 'Inbox' as the selected
       Thread, when clicking on a document thread preview in the messaging menu
       of the systray, the rainbow man appears.

    2. When a document with the chatter is in the background, when receiving an
       inbox notification from this document thread, the document thread is
       automatically marked as read, which removes the notification right away.

    3. Sometimes, opening a DM window from the "blank" thread window does not work.

    4. Reply-to feature on Inbox is not working: no message is sent in the document
       thread.
    5. On the first login of admin user with demo data, the inbox counter is wrong
       (it displays 6, instead of 3).

       Explanation after investigation:

        > On page load, it fetches the correct number of Inbox messages (3),
          but the server notifies of 3 needaction messages right away,
          so it wrongly assumes these are new needaction messages.
        > Not possible for web client to detect that these messages should not
          increment the Inbox counter while keeping same API.

    6. Notifications for new document thread messages only work when the user sets
       'handle with Odoo' for the Notification Management in the preferences.

        > due to notifications on the longpoll bus for document thread
          messages that come from needaction notifications.
        > requires server-side changes to send notification on the longpoll
          bus to mentionned user.

  [New]

    7. When receiving a message on a unjoined channel, thread window flickers
       ('open' > 'close' > 'open')

        Explanation after investigation:

          > JS logic:

            a) On auto-join, ask server to join the channel and get channel infos.
            b) The info tells the channel is not detached, but JS code makes decision
               to detach it, and tells server the channel is now detached.
            c) From (a), server notifies on longpoll bus the state of channel, which is
               not detached. The web client thinks that the window state of the channel
               has been changed somewhere else, and the channel is now closed.
            d) From (b), server notifies on longpoll bus the state of channel, which is
               detached. The web client opens the thread window of this channel.

          > The flicker didn't occur before refactoring because the web client was only
            updating the model of channel when it receives the longpoll notification.
          > Server behaviour on 1st longpoll notification is necessary for cross-tab
            synchronization for channel window state.
          > New design implies that model and view should be synchronized, hence the
            issue now.
          > Solution: remove server-side thread window synchronization and replace with
            client-side synchronization.

----------------------
 Hacks
----------------------

The module `im_livechat` now uses mail objects that are compatible with Message
and Window objects:

      Modeling for messages:

                             AbstractMessage
                              /           \
                             /             \
                    LivechatMessage      Message

      - AbstractMessage: message compatible with the thread widget.
      - LivechatMessage: message used by im_livechat.
      - Message: message used with the mail manager.

      Modeling for thread windows:

                          AbstractThreadWindow
                              /           \
                             /             \
                    LivechatWindow    ThreadWindow

      - AbstractThreadWindow: behaviour share between all types of thread windows.
      - LivechatWindow: window used by im_livechat.
      - ThreadWindow: window used with mail_manager.

The reason for these hacks are twofold:

  1. Use the thread widget in the frontend and livechat external lib bundles.
  2. Do not have a dependency with the mail manager in the frontend and external
     lib bundles.

1 files changed, 446 insertions, 0 deletions

diff --git a/addons/mail/static/src/js/models/thread.js b/addons/mail/static/src/js/models/thread.js
new file mode 100644
index 00000000000..de2c6628d67
--- /dev/null
+++ b/addons/mail/static/src/js/models/thread.js
@@ -0,0 +1,446 @@
+odoo.define('mail.model.Thread', function (require) {
+"use strict";
+
+var emojis = require('mail.emojis');
+var mailUtils = require('mail.utils');
+
+var Class = require('web.Class');
+var Mixins = require('web.mixins');
+var ServicesMixin = require('web.ServicesMixin');
+
+/**
+ * This is the super class modeling threads in JS.
+ * Such threads are stored in the mail manager, and any piece of JS code whose
+ * logic relies on threads must ideally interact with such objects.
+ *
+ * In particular, channels and mailboxes are two different kinds of threads.
+ */
+var Thread = Class.extend(Mixins.EventDispatcherMixin, ServicesMixin, {
+    /**
+     * @param {mail.Manager} parent
+     * @param {Object} data
+     * @param {string} [data.channel_type]
+     * @param {integer|string} data.id
+     * @param {string} data.name
+     * @param {string} [data.type]
+     */
+    init: function (parent, data) {
+        Mixins.EventDispatcherMixin.init.call(this, arguments);
+        this.setParent(parent);
+
+        this._id = data.id;
+
+        // threads are not detached by default
+        this._detached = false;
+        // threads are unfolded by default
+        this._folded = false;
+        // if this._massMailing is set, display subject on messages, use
+        // extended composer and show "Send by messages by email" on discuss
+        // sidebar
+        this._massMailing = false;
+        this._name = data.name;
+        // on 1st request to getPreview, fetch data if incomplete. Otherwise it
+        // means that there is no message in this channel.
+        this._previewed = false;
+        this._type = data.type || data.channel_type;
+        // any new message that has not been read yet
+        this._unreadCounter = 0;
+        // max number of fetched messages from the server
+        this._FETCH_LIMIT = 30;
+    },
+
+    //--------------------------------------------------------------------------
+    // Public
+    //--------------------------------------------------------------------------
+
+    /**
+     * Add a message to this thread.
+     *
+     * @abstract
+     * @param {mail.model.Message} message
+     */
+    addMessage: function (message) {},
+    /**
+     * Updates the _detached state of the thread. Must be overriden to reflect
+     * the new state in the interface.
+     */
+    close: function () {
+        this._detached = false;
+        this._folded = false;
+        this._warnUpdatedWindowState();
+    },
+    /**
+     * Updates the _detached state of the thread. Must be overriden to reflect
+     * the new state in the interface.
+     *
+     * @param {Object} [options={}]
+     * @param {boolean} [options.keepFoldState=false] if set, keep the fold state
+     *   of this thread. Otherwise unfold it while detaching it.
+     * @param {boolean} [options.passively=false] if set, if the thread window
+     *   will be created passively.
+     */
+    detach: function (options) {
+        options = options || {};
+        this._detached = true;
+        this._folded = options.keepFoldState ? this._folded : false;
+        this._warnUpdatedWindowState({
+            passively: options.passively,
+        });
+    },
+    /**
+     * Updates the _folded state of the thread. Must be overriden to reflect
+     * the new state in the interface.
+     */
+    fold: function (folded) {
+        this._detached = true;
+        this._folded = folded;
+        this._warnUpdatedWindowState();
+    },
+    /**
+     * Get the list of available commands for the thread.
+     * By default, threads do not have any available command.
+     *
+     * @returns {Array}
+     */
+    getCommands: function () {
+        return [];
+    },
+    /**
+     * Get the ID of the thread
+     *
+     * @returns {integer|string} string for mailboxes (e.g. 'mailbox_inbox')
+     */
+    getID: function () {
+        return this._id;
+    },
+    /**
+     * Get the listeners of the thread.
+     * By default, a thread has not listener.
+     *
+     * @abstract
+     * @returns {$.Promise<Object[]>}
+     */
+    getMentionPartnerSuggestions: function () {
+        return $.when([]);
+    },
+    /**
+     * Get the list of messages in this thread.
+     * By default, a thread has no messages.
+     *
+     * Note that this method only returns some messages, as we do not want to
+     * fetch all messages of a thread at once, just to read the last message.
+     *
+     * As a result, this method fetches only some messages of the thread,
+     * starting from the last message in the thread. At most, it fetches
+     * `this.LIMIT` number of messages at a time.
+     *
+     * @abstract
+     * @returns {$.Promise<mail.model.Message[]>}
+     */
+    getMessages: function () {
+        return $.when([]);
+    },
+    /**
+     * Get the name of this thread
+     *
+     * @returns {string|Object} object for lazy translated names with _lt
+     */
+    getName: function () {
+        return this._name;
+    },
+    /**
+     * Returns the information required to render the preview of this channel.
+     *
+     * @returns {Object} a valid object for the rendering of previews
+     *   (@see mail.Preview template)
+     */
+    getPreview: function () {
+        return {
+            id: this.getID(),
+            imageSRC: '/mail/static/src/img/smiley/avatar.jpg',
+            isChat: this.isChat(),
+            status: this.getStatus(),
+            title: this.getName(),
+            unreadCounter: this.getUnreadCounter(),
+        };
+    },
+    /**
+     * Get the status of the thread (e.g. 'online', 'offline', etc.)
+     *
+     * @returns {string}
+     */
+    getStatus: function () {
+        return this._status;
+    },
+    /**
+     * Returns the title to display in thread window's headers.
+     *
+     * @returns {string|Object} the name of the thread by default (see @getName)
+     */
+    getTitle: function () {
+        return this.getName();
+    },
+    /**
+     * @returns {string}
+     */
+    getType: function () {
+        return this._type;
+    },
+    /**
+     * @returns {integer}
+     */
+    getUnreadCounter: function () {
+        return this._unreadCounter;
+    },
+    /**
+     * State whether this channel has been previewed
+     *
+     * A channel that has been previewed means that it had the necessary data
+     * to display its preview format. A channel needs its meta data and the
+     * last message in order to build its preview format.
+     *
+     * This is useful in order to not fetch preview info on this channel more
+     * than once on channels that have no message at all.
+     *
+     * Any received message updates the last_message, so a channel should
+     * always have all the necessary information to display its preview after
+     * the 1st time.
+     *
+     * @returns {boolean}
+     */
+    hasBeenPreviewed: function () {
+        return this._previewed;
+    },
+    /**
+     * State whether there are unread messages in this thread
+     *
+     * @returns {boolean}
+     */
+    hasUnreadMessages: function () {
+        return this._unreadCounter !== 0;
+    },
+    /**
+     * Increments the needaction counter of this thread
+     * FIXME: this method makes only sense for channels. Not sure, but I think
+     * this method is necessary at this level because of the model
+     * im_support.SupportChannel
+     *
+     * @abstract
+     */
+    incrementNeedactionCounter: function () {},
+    /**
+     * Increment the unread counter of this thread by 1 unit
+     */
+    incrementUnreadCounter: function () {
+        this._unreadCounter++;
+        this._warnNewUnreadCounter();
+    },
+    /**
+     * States whether the thread should be auto-selected on creation
+     *
+     * Note that this is not of the responsibility of the thread: it only
+     * provides guidance for the object that uses threads (e.g. mail.Discuss
+     * must listen on threads and auto-select the thread if autoswitch is set).
+     *
+     * By default, threads are not in autoswitch mode.
+     *
+     * @returns {boolean}
+     */
+    isAutoswitch: function () {
+        return false;
+    },
+    /**
+     * States whether this thread is a channel or not. A thread is a channel if
+     * it is an instance of mail.model.Channel (direct or indirect).
+     * By default, any thread is not a channel
+     *
+     * @returns {boolean}
+     */
+    isChannel: function () {
+        return false;
+    },
+    /**
+     * States whether this thread is a chat or not. In particular, public and
+     * private channels are not chat, but DMs and Livechats are chats. Chats
+     * are threads used for communication between two users.
+     * By default, any thread is not a chat
+     *
+     * @returns {boolean}
+     */
+    isChat: function () {
+        return false;
+    },
+    /**
+     * States whether this thread is detached or not.
+     * A thread that is detached must have a thread window linked to itself.
+     *
+     * @return {boolean}
+     */
+    isDetached: function () {
+        return this._detached;
+    },
+    /**
+     * States whether this thread is folded or not.
+     *
+     * @return {boolean}
+     */
+    isFolded: function () {
+        return this._folded;
+    },
+    /**
+     * States whether the thread is linked to a document
+     * By default, threads are not linked to a document.
+     *
+     * @returns {boolean}
+     */
+    isLinkedToDocument: function () {
+        return false;
+    },
+    /**
+     * States whether this thread has the mass mailing setting active or not.
+     * This is a server-side setting, that determine the type of composer that
+     * is used (basic or extended composer).
+     *
+     * @return {boolean}
+     */
+    isMassMailing: function () {
+        return this._massMailing;
+    },
+    /**
+
+     * States whether the thread is moderated or not.
+     * By default, threads are not moderated.
+     *
+     * @returns {boolean}
+     */
+    isModerated: function () {
+        return false;
+    },
+    /**
+     * States whether the current user is moderator of this thread.
+     * By default, the current user is not moderator of this thread.
+     *
+     * @returns {boolean}
+     */
+    isModerator: function () {
+        return false;
+    },
+    /**
+     * Mark this channel as previewed
+     *
+     * This is useful in order to not fetch preview info on this channel
+     * is the server has no preview in the first place.
+     *
+     * Note: preview fetch is useful only when the channel contains messages
+     * that have not been fetched at all. After that, this channel instance
+     * is updated regularly so that the most up-to-date info are available
+     * to make the preview of this channel.
+     */
+    markAsPreviewed: function () {
+        this._previewed = true;
+    },
+    /**
+     * Mark the thread as read, which resets the unread counter to 0.
+     *
+     * @returns {$.Promise} resolved
+     */
+    markAsRead: function () {
+        if (this._unreadCounter > 0) {
+            this._unreadCounter = 0;
+            this._warnNewUnreadCounter();
+        }
+        return $.when();
+    },
+    /**
+     * Post a message on the thread.
+     *
+     * This method must be completed by concrete threads,
+     * As it currently only pre-process the messages at the moment.
+     *
+     * @abstract
+     * @param {Object} data
+     * @returns {$.Promise<Object>} resolved with the message object to be sent
+     *   to the server
+     */
+    postMessage: function (data) {
+        // This message will be received from the mail composer as html content
+        // subtype but the urls will not be linkified. If the mail composer
+        // takes the responsibility to linkify the urls we end up with double
+        // linkification a bit everywhere. Ideally we want to keep the content
+        // as text internally and only make html enrichment at display time but
+        // the current design makes this quite hard to do.
+        var body = mailUtils.parseAndTransform(_.str.trim(data.content), mailUtils.addLink);
+        body = this._generateEmojis(body);
+        var messageData = {
+            partner_ids: data.partner_ids,
+            body: body,
+            attachment_ids: data.attachment_ids,
+        };
+        if ('subject' in data) {
+            messageData.subject = data.subject;
+        }
+        return $.when(messageData);
+    },
+    /**
+     * @private
+     */
+    resetUnreadCounter: function () {
+        this._unreadCounter = 0;
+        this._warnNewUnreadCounter();
+    },
+
+    //--------------------------------------------------------------------------
+    // Private
+    //--------------------------------------------------------------------------
+
+    /**
+     * @abstract
+     * @private
+     * @return {$.Promise}
+     */
+    _fetchMessages: function () {
+        return $.when();
+    },
+    /**
+     * Replace character representations of emojis by their unicode
+     * representation in the provided HTML string. Note that the provided html
+     * string is altered by this function.
+     *
+     * @param {string} htmlString
+     * @returns {string}
+     */
+    _generateEmojis: function (htmlString) {
+        _.each(emojis, function (emoji) {
+            _.each(emoji.sources, function (source) {
+                var escapedSource = String(_.escape(source)).replace(/([.*+?=^!:${}()|[\]/\\])/g, '\\$1');
+                var regexp = new RegExp("(\\s|^)(" + escapedSource + ")(?=\\s|$)", 'g');
+                htmlString = htmlString.replace(regexp, '$1' + emoji.unicode);
+            });
+        });
+        return htmlString;
+    },
+    /**
+     * Warn other mail components that the window state of this thread has
+     * changed (it has become closed, folded, unfolded, detached, etc.)
+     *
+     * @private
+     * @param {Object} [options={}]
+     */
+    _warnUpdatedWindowState: function (options) {
+        options = options || {};
+        this.call('mail_service', 'updateThreadWindow', this.getID(), options);
+    },
+    /**
+     * Warn on the chat bus that the unread counter has been updated
+     *
+     * @private
+     */
+    _warnNewUnreadCounter: function () {
+        this.call('mail_service', 'getMailBus')
+            .trigger('update_thread_unread_counter', this);
+    },
+});
+
+return Thread;
+
+});