Build Views & Widgets

Quickstart Guide: Views & Widgets

Build a simple board view, dashboard widget or item view using React, step by step!

07ee9ccd-2e48-49ce-9176-1a8305647ef1_buildyourfirstviewwidgetthumbnail.jpg

In this tutorial we will build a simple Hello World app with React. This tutorial will start simple, and build a more complex app as it goes along. The same code can be used as a board view, item view or a dashboard widget.

The monday apps framework is a set of tools you can use to build on top of monday.com. A single monday app can contain multiple features, and the platform supports adding board views, item views, dashboard widgets, automations and integrations to your apps. A simple app might contain just a single board view, or use multiple views, widgets and integrations to create a set of functionality that extends across contexts.

The final code for this tutorial can be found here.

Note: This tutorial is written with React, but it's just an example. You can use any JS framework you want (or none at all) when building your monday apps.

Before we begin

You will learn:

  • How to build a simple "Hello world" app in React
  • How to package and build your app
  • How to allow users to configure settings for your app
  • How to use our SDK to get data from connected boards

Prerequisites

  • Basic understanding of how to create a monday app. To learn more, check out this guide.
  • Basic understanding of web programming (HTML, CSS, JS)
  • Working environment of NodeJS on your computer, as well as a package manager like npm or yarn.

Part 1: Set up your development environment

Create a monday app

Open the developers section and create a new monday app. Go to the "Features" tab and add a new board view (or widget).

Update your view's basic information

In the feature editor, open the "feature details" tab. This is where you can add a title and description to your board view or widget. The user will see the title and description when they see your view or widget when they explore the view or dashboards center.

Add a new feature

Set up your development environment

We will be using the monday-cli package to download the example code and run it locally. To set up your dev environment, follow these steps:

  1. Run the following command. This will download the project quickstart-react to your current folder, install the dependencies (npm install), and run the project locally (npm run start).
npx @mondaydotcomorg/monday-cli scaffold run ./ quickstart-react
  1. Wait for the installation process to finish. It may take a few minutes.
  2. After the app is installed and running, you will get the message "Your app is served from this URL" with a link to your app, e.g. https://abc1234asdlqwe.ngrok.com
  3. Paste this URL to the "Custom URL field" in the "View Setup" pane.

To run your application manually in the future: navigate to the folder with the project (quickstart-react), and run "npm run start" command.

Note: We use a tool called ngrok to expose our localhost to a public URL. You can always find your current ngrok URL by visiting http://localhost:4040/status settings page in the command_line=>URL section.

Part 2: Build a simple "Hello monday Apps" app

In this section, we will write some code to display "Hello monday Apps" in a board view or widget.

Edit src/App.js to include a simple UI

Navigate to quickstart-react folder.

Open App.js file that you downloaded in the starter code package.

In the class App() you will see a render() function. Replace all the text between the first and last <div> tags with the words Hello monday Apps!. This will display the text "Hello monday Apps!" in your board view or widget.

After this step, your App() class will look something like this:

class App() extends React.Component {
  render() {
    return (
      <div className="App">
        Hello, monday Apps!
      </div>
    );
  }
}

When you open the "View Setup" section, go to "preview" and you will see this: hello_monday_first_step

Part 3: Use settings to let the user customize their experience

Now that we have built a simple app, we will extend the functionality of this app to include user configuration. In this section, we will allow the user to select the color of app's background (the same way we can use any monday field type).

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

Adding a color picker settings field to your view or widget

In this step, we will add a color picker setting to our view (or widget). Later, we will update our code to retrieve this setting.

  1. Open your app's feature. Open the "View Setup" (or "Widget Setup") pane.
  2. On the "View Settings" pane on the right, select the blue "Add Field" button. This will let you add a new field to your feature's settings.
  3. In the field selector, choose "Color Picker". This setting field will let the user choose a color.
  4. In the field configuration page, change the title to "Background Color". Change the "name" field to "background" -- this is the key we will use to access the setting's value later.
  5. Click done, and save.

Note: These are the same settings fields we use in native monday.com views!

Accessing the color picker from your view or widget

Now that we have configured the setting field, we need to retrieve this setting and use the value in our app. To do this, we will set up an event listener with the monday.listen() method in the SDK.

In the componentDidMount function, we will add the monday.listen() method. This will create a listener to save the settings data to our app's state every time the settings change.

Add the following lines to your componentDidMount:

componentDidMount() {
    monday.listen("settings", res => {
      this.setState({ settings: res.data });
    });
  }

A note about the settings data: it is a Javascript object, where each key is the "name" of the field as configured in your app feature. Since we set the "name" of our color picker field to "background", we can access this particular value by calling settings.background.

Incorporating the color setting in your app

Now that we've added functions to retrieve and store our color setting, we need to use this in our app. To set the color of our "hello world" text, we will use the style attribute to add the color to our text:

<div className="App" style={{background: (this.state.settings.background)}}>
  Hello, monday Apps!
</div>

By the end of this step, your render() function should look like this:

render() {
  return (
    <div
      className="App"
      style={{background: (this.state.settings.background)}}
      >
      Hello, monday Apps!
    </div>
  );
}

Well done!

We've now used the monday SDK to let your users configure what your app shows them. Next, we will use the monday SDK to count the number of items that are on the boards connected to the view/widget, and display them.

background-color-changing

Tip: In a similar way to settings, you can also use the monday SDK in order to get other useful fields. The "context" field for example is an important one, and used to understand where your app is currently rendered. The context object contains the id of the board you're at, and other useful properties as well. You can get the app context by adding another listener - monday.listen(“context”, this.getContext);

You can find the full details in our SDK documentation

Part 4: Use the monday API to get board data

In this section, we will use the monday.com API to get the user's name.

Set up your app's permission scopes

We need to set up your app's permission scopes to access the user's name. To do this:

  1. Open your app's details by going to the Developers section and clicking your app.
  2. Click "OAuth and Permissions" on the left.
  3. Enable the "boards:read" scope.
  4. Hit save.

Set up a context listener that calls the monday API

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

// Board view context
{
  "boardViewId": 19324,
  "boardIds": [3423243],
  "mode": "fullScreen", // or "split"
  "theme": "light"  // or "dark"
}

// Dashboard widget context
{
  "widgetId": 54236,
  "boardIds": [3423243, 943728],
  "theme": "light"  // or "dark"
}

// Item view context 
{
    "boardId" : 12345,
    "itemId" : 123456
}

We will update our code to get the context of your board view/widget, and then make an API call to get the first item from each connected board.

Add the following context listener to your componentDidMount function:

monday.listen("context", res => {
      this.setState({context: res.data});
      console.log(res.data);
      monday.api(`query ($boardIds: [Int]) { boards (ids:$boardIds) { name items(limit:1) { name column_values { title text } } } }`,
        { variables: {boardIds: this.state.context.boardIds} }
      )
      .then(res => {
        this.setState({boardData: res.data});
      });
    })

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.

Change your render() function to include the boardData field:

render() {
    return (
      <div
        className="App" style={{background: (this.state.settings.background)}}
        >
        {JSON.stringify(this.state.boardData, null, 2)} 
      </div>
    );
  }

Great job!

Your final app should look like this:

final_product

Part 5: Build your app

To build our simple application, we will bundle it in a ZIP file and upload it to the monday.com server.

  1. Compile your React code into a production build by running npm run-script build. This will create a new "build" folder in your directory.
  2. Create an archive of the contents of your "build" folder (ZIP file).
  3. Open your feature, and select the "Builds" tab. Click "New Build" to upload your production code.
  4. Upload the ZIP you just created.
  5. Open a board, and add your view to it. You should see your app display data for the first item on the board.

Note: Our apps CDN does not have authentication on it. That is, any views or widgets uploaded to our platform will be publicly-accessible via a randomly-generated (and difficult to guess) URL.

Congrats Builder!

You've now built a simple monday app that displays data, is configurable by the user, and can be used by anyone in your account. You and your collaborators will now see your app on your boards.

As you learn more about the apps framework, check out our SDK documentation and Frequently Asked Questions.