Build views & widgets

Advanced Topics

Enhance your board views and widgets with the advanced functionality of the apps framework

In this article, we'll go over some of the advanced tools that you can use to build views and widgets for your users.

You'll learn:

  • Adding settings to your views and widgets
  • Using our API to get data from connected boards
  • Saving persistent data using the monday.com storage API
  • Filtering the data your app shows based on the board filter
  • Executing actions in the monday.com UI

Prerequisites

Adding settings to your views and widgets

Every view or widget in monday.com has a set of fields that lets a user customize that view or widget. Our apps framework allows you to add these fields to your custom views and widgets, and then your app can access the values that the user has configured via our SDK.

For example, the Timeline allows users to choose which columns are displayed, and the Chart lets users change the X axis and chart type. You can use any of the 12 fields we support.

To do this, first add a settings field to your feature to get the color value as an input. Then, we'll use the monday SDK to retrieve this setting's value and use it in our view or widget.

For example, here's a snippet that listens for changes and calls a callback when the settings field is changed by the user:

monday.listen("settings", res => {
  console.log(res.data);
  // {"fieldName": "fieldValue", "fieldName2": "fieldValue2"...}
});

Using the monday.com API to get and change data from connected boards

In this section, we’ll use the monday.com API to read/write data in the user's monday.com account.

You can use the monday.api() method in the SDK to get and change data on behalf of the user who is using your app. Your app will have access based on the permission scopes defined within your app.

Tip: Our GraphQL API exposes methods to get board data, create items, notify people, and much more. Check out our API documentation for more information.

Using the SDK to get your app's context

Every board view and widget runs in a specific context and our SDK exposes methods to retrieve this information. The context data looks like this:

// Board view context
{
  "instanceId": 19324, // unique instance ID for the feature on the board
  "instanceType": "board_view", // feature type
  "boardIds": [3423243], // list of connected boards
  "viewMode": "fullscreen", // or "split"
  "theme": "light"  // or "dark"
}

// Dashboard widget context
{
  "instanceId": 54236,
  "instanceType": "dashboard_widget",
  "boardIds": [3423243, 943728],
  "viewMode" : "widget", // or "fullscreen"
  "theme": "light",  // or "dark"
  "editMode" : false // or true
}

Add the following context listener to your code:

monday.listen("context", res => {
  console.log(res.data);
  // do Something
})

Saving persistent data using the monday.com storage API

The monday apps infrastructure includes a persistent key-value database storage that developers can leverage to store data without having to create their own backend and maintain their own database.

The database currently offers instance-level storage, meaning that each application instance (i.e. a single board view or a dashboard widget) maintains its own storage. Apps cannot share storage across accounts or even across apps installed in the same location.

Here is how you get a value from the storage API:

monday.storage.instance.getItem('mykey').then(res => {
   console.log(res.data.value);
})

This is how you set a new value in your database:

monday.storage.instance.setItem('mykey', 'Lorem Ipsum').then(res => {
  console.log(res);
})

Here is how you delete an item in your database:

monday.storage.instance.deleteItem('mykey').then(res => {
  console.log(res);
  // { "success": true }
}

Filtering your app's data based on the board filter

The monday SDK also lets your app check if the user has filtered any items on their boards. With this approach, you can add flexibility to your app and create a unified experience for your users.

By using monday.listen("itemIds", callback), you can get a list of items that are displayed on the board.

The following example sets up a listener when the user filters data on the board:

monday.listen("itemIds", (res) => {
  console.log(res.data );
  // [12345, 12346, 12347]
});

Executing actions in the monday.com UI

The SDK exposes methods to let your app execute commands in the monday.com UI. For example, you can open a UI component that lists the values of a given item, display a confirmation dialog, etc.

Open a card for a specific item

Apps that show data from items in the board can allow users to view and edit all of the data about the item by opening the item card.

You can do it using monday SDK with a simple call:

monday.execute('openItemCard', { itemId: item.id });

Open confirmation dialog

You can use monday.execute("confirm", options) to open a confirmation dialog to your users.

monday.execute("confirm", {
   message: "Are you sure?", 
   confirmButton: "Let's go!", 
   cancelButton: "No way", 
   excludeCancelButton: false
}).then((res) => {
    console.log(res.data);
    // {"confirm": true}
});

Here's what the confirmation dialog will look like:

Display a notice message to the user

You can use monday.execute("notice", options) to display a message at the top of the user's page. Here is an example:

monday.execute("notice", { 
   message: "I'm a success message",
   type: "success", // or "error" (red), or "info" (blue)
   timeout: 10000,
});

This is what the success message will look like:

Read this next

Check out our SDK documentation for a detailed look at our SDK methods and our Frequently Asked Questions for other topics.