Controlling the Widget

Methods

Once you have access to a Widget instance there are methods you can use to control it.

widget.open()

Open the Widget.

widget.close()

Close the Widget.

widget.toggle()

Toggle (open/close) the Widget.

widget.destroy()

Destroy the Widget and remove it from the DOM.

widget.viewSection(section: 'ideas' | 'roadmap' | 'announcements')

Route the Widget to a section.

widget.viewAnnouncement(announcementSlug: string)

Route to an Announcement in the Widget. The announcementSlug can be found in the URL from the Announcement page.

widget.viewIdea(ideaSlug: string)

Route to an Idea in the Widget. The ideaSlug can be found in the URL from the Idea page.

widget.createIdea(defaultValues?: { name?: string, topics?: string[] })

Route the Widget to the Create Idea form. Accepts an optional default values object for the Idea name and topics. Topic IDs can be found in the URL if you filter your Ideas board in the platform.

widget.setBadgeCount(count: number)

Set the count. If 0 the badge will be removed.

Events & Callbacks

The Widget will emit different events that you can subscribe to. You can subscribe to events when you call the widget method, or use the widget.events.on function once you have the Widget instance.

Callbacks are defined by:

type FrillWidgetCallbacks = {
  /**
   * Fired when the Widget is ready and Announcements have loaded
   * widget.events.on('ready', () => {})
   */
  onReady(widget: FrillWidget) {},
  /**
   * Fired after the Widget has been opened
   * widget.events.on('open', () => {})
   */
  onOpen() {},
  /**
   * Fired after the Widget has been closed
   * widget.events.on('close', () => {})
   */
  onClose() {},
  /**
   * Fired when the Widget is destroyed
   * widget.events.on('destroy', () => {})
   */
  onDestroy() {},
  /**
   * Fired when a user logs in
   * widget.events.on('login', () => {})
   */
  onLogin(event: { user: { name: string; email: string } }) {},
  /**
   * Fired when a user logs out
   * widget.events.on('logout', () => {})
   */
  onLogout() {},
  /**
   * Fired after the badge count changes
   * widget.events.on('badgeCount', () => {})
   */
  onBadgeCount(event: {
    announcements: { idx: string; slug: string; published_at: string }[];
    count: number;
  }) {},
  /**
   * Fired after a boosted Announcement notification has been opened
   * widget.events.on('notificationOpen', () => {})
   */
  onNotificationOpen() {},
  /**
   * Fired after a boosted Announcement notification has been closed
   * widget.events.on('notificationClose', () => {})
   */
  onNotificationClose() {},
};

Here's an example of how you would subscribe to the onBadgeCount event.

const widget = await window.Frill('widget', {
  key: 'YOUR_WIDGET_KEY', // <-- Add Widget key here
  callbacks: {
    // Add callback functions here, e.g.
    onBadgeCount({ count }) {
      console.log(`Widget has ${count} unread Announcements`);
    }
  },
});

Or you can use widget.events to subscribe/unsubscribe at any time:

const unsubscribe = widget.events.on('badgeCount', () => {
  console.log(`Widget has ${count} unread Announcements`);
});