Building apps for workdocs using the doc action feature allows you to create new collaboration tools for monday users, such as text validation and idea generation.

In this guide, we're going to build a simple doc action app that lets users automatically capitalize a highlighted portion of a document.

Build your first app

Download the example code

Download the example code from the monday Github repo. You can either download the zip file from Github or use the git clone command:

$ git clone https://github.com/mondaycom/welcome-apps.git

Install ngrok

This example uses a service called ngrok to securely connect your local environment to the internet. To use it, you'll need to set up a free account and install the software.

If you've used ngrok before, you can skip this step.

1. Download and install the software from the ngrok website
2. Create an ngrok account
3. Get your authtoken from your account dashboard
4. Add your authtoken to your local installation by running ngrok config add-authtoken <token>

Run the app locally

Once you have the example code and ngrok set up, it's time to run your app.

Open the welcome apps folder in the terminal of your choice and navigate to the apps/quickstart-workdocs folder.

$ cd apps/quickstart-workdocs

Install the dependencies using npm.

$ npm install --loglevel error

Run the code.

$ npm run start

Navigate to the ngrok dashboard at localhost:4040 and copy your tunnel URL from there. Make sure to use the URL that starts with https://.

Create the doc action feature

Next, you need to add the doc action feature to an existing app and connect that feature to the tunnel URL from the previous step.

1. Click the Add feature button on your app's left-side menu.
2. Select Doc Action in the modal.
3. On the Feature Details page, check the Contextual Toolbar box under the Supported Locations section.
4. Click Save Feature.
5. Once you save your feature, click the New Build button on the right of the screen.
6. Add your tunnel URL from the previous step to the Custom URL field.
7. Press Create build to save the URL.

Use your app in a monday workdoc

Now you're ready to add the app to a doc and test it out!

1. Create a new workdoc through the Add menu on the top left of your workspace. If you've never created a workdoc before, check out this article before moving on.
2. Write some text in your doc.
3. Highlight the text, and a contextual menu will appear.
4. Select the Apps puzzle piece icon in the contextual menu.
5. This will open a dropdown menu so that you can select your app feature from the list. A modal will appear with your app embedded inside it.
6. Click the Capitalize button.
7. The highlighted text will become capitalized.

Why it works

After running the example code, you can inspect the code and app configuration to understand why it works the way it does.

Below, we've broken down some guiding principles to explain why the app behaves the way it does to help you use them in your apps.

Choosing your app's location

Since our app edits existing text, we selected the contextual toolbar location. This way, it will only appear when someone highlights content in a workdoc.

We recommend placing your app in the add block menu if it creates new workdoc content rather than updating it. If your app has both capabilities, you can add it to each location!

Using the context object

In the example app, we use an object called context that contains information about your app's context. You can retrieve this object using the monday.get or monday.listen SDK methods.

In line 20, we use the monday.get() method to retrieve the current context. We then use the focusedBlocks and range attributes to know what content to update.

In this example, we only use two fields from the context. The complete context object contains much more helpful information, like the ID of the current document, what blocks are currently selected, and if the app was launched from the toolbar or add block menu. You can examine the full structure of the context object [here].

Using monday.updateBlock() to update doc content

We update the doc's content using the SDK method monday.updateBlock() without needing to authenticate or construct a GraphQL query. We recommend using the addBlock, addMultiBlocks, and updateBlock methods in client-side applications. Our GraphQL API supports adding blocks, but the SDK methods are much more straightforward.

Referencing the Delta library

The content inside each block is defined in Delta format, a specification built by Quill. The app uses the quill-delta library to manipulate block content instead of doing it manually. We recommend using this library to prevent any validation errors in your content.

Since the Delta format is just an array of objects, you may be tempted to manipulate the delta-formatted content without a library. We don't recommend this because you will get validation errors if your content has the wrong structure.

📘

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎