Commenting

  1. Overview
  2. Use cases
  3. How to activate it
  4. How it works
  5. Disable Commenting for specific customers
  6. Managing notifications
  7. Sample code for email notifications
  8. Comments schema
  9. Commenting callback

Overview

With Commenting, teams using your app can collaborate asynchronously on the same email or page, to get their work done more quickly and reach approval for going live more efficiently.

 

Leaving a comment in a thread

 

When Commenting is enabled, your end-users (or contributors, as we’ll call them in this context) can:

  • add a new comment in any content block or row, so that the context of the discussion is always visible;
  • reply to an existing comment and start a thread;
  • mark existing threads as resolved, and reopen solved threads if necessary.

Use cases

With Commenting,  you enable asynchronous, visual collaboration when multiple collaborators work in BEE. This collaborative feature can prove extremely beneficial in different contexts, regardless if contributors are in the same team, in separate teams, or even in different companies (e.g. agencies):

  • have a single source of truth for feedback and requests on the content created with BEE;
  • cut time-to-publish, reducing back and forth conversations, both online and offline;
  • get sign-off for going live for email and web campaigns more efficiently.

How to activate it

Commenting – as most BEE Plugin features – is made available to BEE Plugin customers as OFF by default, and must be activated in the BEE Plugin developer portal.

To do so:

  • Login into the developer portal
  • Click Details next to the application you want to configure
    • We recommend you first familiarize with Commenting under a DEV or QA application
  • Click view more under Application configuration.
  • Toggle Enable commenting ON and click the Save button to activate Commenting for the application.

To activate Commenting when launching BEE Plugin, you will need to pass a username, userHandle, and a userColor in the configuration parameters. See this example:



const beeConfig = {
    uid: 'dev-user',
    language: 'en-US',
    ...
    username: 'Test User',
    userColor: '#cae5f1'
    userHandle: 'd09b0f5d-e08b-4dca-b7ae-6010b5da04d3' // unique id
    ...
}

How it works

Adding comments and starting threads

 

When opening an email or page in BEE, a contributor can add a new comment to a content block or a row by clicking the “Balloon” icon, available in two spots:

  • in the row or block outline, inside the editing stage
  • in the header of the Row properties or Content properties

 

 

Clicking one of these two icons will activate the commenting panel, which takes over the editor sidebar. From there, the user can insert a new comment. After the first comment, another contributor can start a thread by adding a second comment.

Adding the first comment

 

Interacting with threads

 

If there has already been some activity, the editing stage shows whether a content block or row has any comments by displaying a small comment icon. The sidebar instead indicates the number of existing comments for the selected row or content block, three in this case.

 

Show comments in toolbar

 

Activating the Commenting panel will bring up the thread. In this case, it will show the three comments.

Existing comments can be edited or deleted by the contributor that added them. Contributors may also resolve comments when they have reached consensus and completed any pending task.

 

Commenting thread

Browsing threads and closing the commenting panel

 

Clicking on < All comments in the top section will bring up a list of all comment threads, indicating which ones have been resolved and which ones are still open. Contributors can search inside comments and filter out solved threads, or threads that were part of a deleted content.

 

All comments

 

To go back to the editor sidebar, contributors can close the Commenting panel by clicking the X icon in the upper right, or they can just click on another row or content block in the stage.

 

Disable Commenting for specific customers

Once you turn on the feature in the developer portal, you may want to disable Commenting for some customers. You can do so via the client-side configuration document that you feed to BEE Plugin when initializing the editor.

Why? Because you may decide to make the feature available to customers of your application:

  • depending on the subscription plan that they are on (i.e. you could push users to a higher plan based on the ability to use Commenting);
  • depending on the purchase of an optional feature (same);
  • only if they are “beta” customers, so they see it while keeping it hidden from the rest of your users.

Here’s how to do so:

  • Enable Commenting in the developer portal, as mentioned above.
  • Add the configuration parameter commenting to the beeConfig document
  • Set it to false for all users that cannot comment.

Here is a simple example:




const beeConfig = {
    uid: 'dev-user',
    language: 'en-US',
    ...
    commenting: false // boolean
    ...
}


Managing notifications

BEE allows you to build a notification system around commenting by triggering a callback for events in the Commenting layer. When these events happen, BEE Plugin triggers the onComment callback.

You can react to that callback by taking the information provided in it (e.g. the user that created the comment, the text of the comment, date & time of the comment, etc.) and send notifications.

You are free to define:

  • which events will trigger a notification
  • how it is sent (e.g. Email, In-app, Slack, etc.)
  • what exactly it says

Again, remember that BEE only triggers the callback, and it’s up to you to react, if you want. Below you can find the technical details on the comments schema and the onComment callback.

Sample code for email notifications

We’ve put together a sample code that illustrates how to send email notifications, triggered by a mention in a comment. This code shows how to:

  • Define an array to hold the list of mentioned users in the comment payload.
  • Loop through the comment payload and add any strings matching a regex to the array
  • Compare each value in the array with the ‘handle’ property of each user (as defined by the host application), to grab the active users
  • Loop through your array and pull the respective email address for the handle matches (for use in notification)
  • Send the notification through email (via ajax), slack, etc… (you decide and implement how to send the notification)

Comments schema

The following JSON is saved as part of the template:




"comments": {
    "aab0227f-766d-439d-b3d9-8bf7d04d551f": {
      "content": "Here is a comment",
      "parentCommentId": null,
      "elementId": "ab35241d-dd69-4980-9385-862fedd094e4",
      "responses": [
        "84f11738-a5a2-49db-956a-ae95b4d1db67"
      ],
      "timestamp": "2020-09-07T13:58:43.147Z",
      "author": {
        "userHandle": "abfb7e82-3b9a-45fc-a40d-b22221f6a7f5",
        "username": "Test User",
        "userColor": "#dddddd"
      },
      "isElementDeleted": false
    },
    "84f11738-a5a2-49db-956a-ae95b4d1db67": {
      "content": "Here is a second comment",
      "parentCommentId": "aab0227f-766d-439d-b3d9-8bf7d04d551f",
      "elementId": "ab35241d-dd69-4980-9385-862fedd094e4",
      "responses": [],
      "timestamp": "2020-09-07T13:59:51.954Z",
      "author": {
        "userHandle": "d09b0f5d-e08b-4dca-b7ae-6010b5da04d3",
        "username": "Test User B",
        "userColor": "#cae5f1"
      },
      "isElementDeleted": false
    }
  }


You may want to save multiple copies of a template, e.g. to create a history/revision or a draft feature.

In such cases, you may decide to store the comments in a database, and add the schema back to the template when it’s loaded. Alternatively, you can keep the comments inside the template, and it will become a static part of the history.

Comments can also be added dynamically, but it’s an advanced task, which requires matching the comment schema to the target content by its “elementId”.

Commenting callback

When a thread or comment changes, BEE Plugin triggers the onComment callback.  The callback returns the following details:

change

  • JSON contains all the details on the change

comments

  • JSON array of the entire comments schema, as described in the previous section.

change schema

type

  • NEW_COMMENT
  • COMMENT_THREAD_RESOLVED
  • COMMENT_THREAD_REOPENED
  • COMMENT_EDITED
  • COMMENT_DELETED

payload

JSON contains all the details of the change

example of new comment payload




{
    "type": "NEW_COMMENT",
    "payload": {
      "commentId": "9b08e5d6-5170-4840-a14e-12cd2a6d707d",
      "comment": {
        "content": "test",
        "parentCommentId": null,
        "elementId": "ab35241d-dd69-4980-9385-862fedd094e4",
        "responses": [],
        "timestamp": "2020-09-09T02:07:14.347Z",
        "author": {
          "userHandle": "abfb7e82-3b9a-45fc-a40d-b22221f6a7f5",
          "username": "Test User",
          "userColor": "#cae5f1"
        }
      }
    }
  }