1. Learn
2. Notifications

Notifications

Weavy automatically creates notifications for reactions, mentions and other activities. Many of our components such as posts and comments come with a built-in notification UI, but there is also the standalone notifications component which can display an aggregated view of all notifications regardless of their origin.

Handling notifications

Normally you don't need to handle notifications as the notification components are automatically updated when needed. But, if required, you can configure Weavy to emit a wy:notifications event when notifications are created or updated, or when mark all as read is clicked.

// configure Weavy to emit the wy:notifications event
const weavy = new Weavy();
weavy.notificationEvents = true;

After enabling the event you can register a listener using the standard addEventListener() method on the document.

document.addEventListener("wy:notifications", (e) => {
  console.log(e.type, e.detail);
});

The event detail (e.detail) contains the following information.

• id – Unique identifier for the event.
• action – The type of activity that triggered the event (notification_created, notification_updated or notifications_marked).
• actor – The user that triggered the event.
• notification – Data about the notification.

Example: Event details for the notification_created action.

{
  "id": 11606,
  "action": "notification_created",
  "actor": {
    "id": 1126,
    "uid": "marvin",
    "display_name": "Marvin Acme"
  },
  "notification": {
    "id": 4118,
    "type": "reaction",
    "action": "reaction_added",
    "actor": {
      "id": 1126,
      "uid": "marvin",
      "display_name": "Marvin Acme"
    },
    "template": "**{0}** reacted to your post: {1}",
    "args": ["Marvin Acme", "😎"],    
    "text": "**Marvin Acme** reacted to your post: 😎",
    "html": "<p><strong>Marvin Acme</strong> reacted to your post: 😎</p>",
    "plain": "Marvin Acme reacted to your post: 😎",    
    "link": {
      "id": 2199,
      "type": "post",
      "app": {
        "id": 1971,
        "type": "5ebfa152-de85-48da-82dd-30a1b560c313",
        "uid": "demo-posts"
      }
    },
    "user": {
      "id": 2,
      "display_name": "Bugs Bunny"
    },
    "created_at": "2024-07-09T10:05:32.4269839Z",
    "is_unread": true
  }
}

Handling navigation

When a notification in one of the notification components is clicked, Weavy dispatches a wy:link event. The event details (e.detail) for the event includes data about the linked entity in the notification. You can use this information to navigate to the corresponding page or view on your application.

Example: Event details for the wy:link event that links to a comment in a post.

{
  id: 3616,
  type: "comment",
  app: {
    id: 1971,
    type: "5ebfa152-de85-48da-82dd-30a1b560c313",
    uid: "demo-posts",
  },
  parent: {
    id: 3554,
    type: "post",
  },
};

To handle the wy:link event you should add an event listener on the the document (alternatively you can register event listeners on specific notification enabled components). After navigation, and once the corresponding Weavy component is loaded, the linked entity will automatically be highlighted.

document.addEventListener("wy:link", (e) => {
  const data = e.detail;

  // Evaluate the data and navigate to the correct page/view in your application
  // ...

  window.location = "./some-page.html";
});

Navigation strategy

With details from the wy:link event you can make an educated decision on where to navigate or what to show. The most relevant data can be found in the app property.

To make a basic routing decision, follow this strategy.

1. When the wy:link event is triggered, any visible component that the linked entity belongs to will automatically scroll and highlight the entity. No action is needed in these cases.
2. To investigate if the linked entity belongs to the Messenger component, look at the e.detail.app.type and check if it is a conversation (private chat, chat room or bot chat). The ConversationTypes map contains the guid:s for all Messenger conversation types and can be used to evaluate the app type.
3. Otherwise, evaluate the e.detail.app.uid and compare it to the uid used in your components.
4. After checking the app.type and app.uid, decide if and how navigation is required, e.g. by setting window.location or by toggling the visibility of hidden element etc.
5. Once the correct app/component is visible it will consume the link and scroll to the linked entity and highlight it.

Example: Event listener for wy:link.

import { ConversationTypes } from "@weavy/uikit-web";

document.addEventListener("wy:link", (e) => {
  const appType = e.detail.app.type;
  const appUid = e.detail.app.uid;

  // Check if the appType guid exists in the ConversationTypes map
  if (ConversationTypes.has(appType)) {
    // Toggle a panel to show the Messenger component
    document.querySelector("#messages").hidden = false;

  } else if (appUid) {
    // Reverse lookup from uid to page/url where app is located
    const navigationUrl = new URL(`./${appUid}.html`, window.location);

    // Navigate if the page is not the current page
    if (window.location.href !== navigationUrl.href) {
      window.location = navigationUrl;
    }
  }
});

As seen in the example above it very useful being able to do a reverse lookup from a uid to a location in your app. It is therefore a good idea to base the uid for components on something that identifies the location in your app where the Weavy component is being rendered. Typically you would use something like a product id, page id, path or URL.

Custom link handling

To prevent the default internal automatic link-handling that scrolls to, and highlights linked entities, you can call e.preventDefault() in your event listener. When preventing the default functionality, the link can be set for automatic handling manually by calling e.target.provideStorageLink(e.detail).

The .link property can also be set on a component to trigger the link handling, e.g. document.querySelector("wy-chat").link = e.detail.

Example: Custom wy:link event handling

document.addEventListener("wy:link", (e) => {
  // prevent the link from being automatically handled by components on the page
  e.preventDefault();

  // optionally save the link for internal auto handling later
  //e.target.provideStorageLink(e.detail);

  // do custom things to transfer the link somewhere...

  // ...or pass the link to a specific component
  document.querySelector("wy-chat").link = e.detail;
});