1. Reference
  2. UIKit
  3. Notifications

Notifications

Weavy automatically creates notifications for reactions, mentions and other activities. Many of our components such as <wy-comments> and <wy-posts> comes with a built-in notification UI, but there is also the <wy-notifications> component which can display an aggregated view of all notifications regardless of their origin. Additionally, there is <wy-notification-toasts> that displays realtime notification toasts or native browser notifications.

Handling navigation

To navigate to the correct page or make the UI respond to a notification click you should add an event listener for the wy:link event on the document to catch all link events (or on a specific notification component, e. g. <wy-comments> to just catch those events). After navigation, and once the corresponding app is loaded, Weavy will automatically show and highlight the linked entity.

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";
});

As seen in the following example the event details (e.detail) contains the data needed to evaluate where to navigate and which Weavy block/component to show.

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

The wy:link event details contains all link data available to make an educated decision on where to navigate or what to show. The most relevant data is in the app property.

To make a basic routing decision, follow this strategy.

  1. When the wy:link event is triggered, any visible block that the link belongs to will automatically scroll and highlight the entity. No action is needed in these cases.
  2. To navigate to the Messenger, look at the e.detail.app.type and see if it is a conversation app guid. The ConversationTypes map contains the guid:s for all Messenger conversation types and can be used to evaluate the app type.
  3. To navigate to a contextual app, evaluate the e.detail.app.uid and compare it to the different uid:s used for your blocks.
  4. After checking the app.uid and app.type, decide if a navigation or action is needed and how to do it. This could be by changing the window.location or by showing a panel or a page.
  5. Once the correct app is visible it will consume the link and scroll to the correct entity and highlight it.
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)) {
    // Show the messenger 
    
    // Toggle a panel to show the Messenger
    document.querySelector("#myMessengerPanel").hidden = false;

  } else if (appUid) {
    // Show a contextual block by navigation to another page

    // Compose a navigation url
    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;
    }
  }
});

To prevent the default internal automatic link-handling, simply call e.preventDefault() in the event. This enables custom link-handling.

When preventing the default functionality in the event, the link can be set for automatic handling manually by calling e.target.provideStorageLink(e.detail).

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

document.addEventListener("wy:link", (e) => {
  // prevent the link from being internally auto handled or consumed by blocks 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 set the link to a specific block
  document.querySelector("wy-chat").link = e.detail;
});

Reference: TypeScript definition of event.details for the wy:link event.

type EntityType = {
  id: number;
  type: "app" | "file" | "message" | "user" | "comment" | "post";
  app: {
    id: number;
    type?: AppTypeGuid;
    uid?: string;
  };
  parent?: EntityType;
};

enum AppTypeGuid {
  Chat = "d65dd4bc-418e-403c-9f56-f9cf4da931ed",
  Comments = "88f96a08-c6c1-4eac-a0bd-5bf8fba1a3fd",
  Files = "523edd88-4bbf-4547-b60f-2859a6d2ddc1",
  Posts = "5ebfa152-de85-48da-82dd-30a1b560c313",
  ChatRoom = "edb400ac-839b-45a7-b2a8-6a01820d1c44",
  PrivateChat = "7e14f418-8f15-46f4-b182-f619b671e470",
  BotChat = "2352a1c6-abc6-420e-8b85-ca7d5aed8779",
}

Notification events

Weavy can optionally be configured 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);
});

All event details share the following properties, but specific actions can return additional data, e.g. notification as seen in the example below.

  • id – Unique identifier for the event (shared with all listeners that subscribe to this event).
  • action – The type of activity that triggered the event (notification_created, notification_updated or notifications_marked).
  • actor – The user that triggered the event.

Example: event.detail for the notification_created action.

{
  "id": 11606,
  "action": "notification_created",
  "actor": {
    "id": 1126,
    "uid": "marvin",
    "display_name": "Marvin Acme"
  },
  "notification": {
    "id": 4118,
    "type": "activity",
    "action": "message_created",
    "actor": {
      "id": 1126,
      "uid": "marvin",
      "display_name": "Marvin Acme"
    },
    "link": {
      "id": 2199,
      "type": "message",
      "app": {
        "id": 227,
        "type": "7e14f418-8f15-46f4-b182-f619b671e470"
      }
    },
    "user": {
      "id": 2,
      "display_name": "Bugs Bunny"
    },
    "created_at": "2024-07-09T10:05:32.4269839Z",
    "is_unread": true
  }
}