This guide will teach you how to build your first app on top of monday workdocs using the doc action feature.
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 example, 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
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.
- Download and install the software from the ngrok website
- Create an ngrok account
- Get your authtoken from your account dashboard
- 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
$ cd /apps/quickstart-workdocs
Install the dependencies using
$ 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
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.
- Click the Add feature button on your app's left-side menu.
- Select Doc Action in the modal.
- On the Feature Details page, check the Contextual Toolbar box under the Supported Locations section.
- Click Save Feature.
- Once you save your feature, click the New Build button on the right of the screen.
- Add your tunnel URL from the previous step to the Custom URL field.
- 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!
- 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.
- Write some text in your doc.
- Highlight the text, and a contextual menu will appear.
- Select the Apps puzzle piece icon in the contextual menu.
- 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.
- Click the Capitalize button.
- 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.listen SDK methods.
In line 20, we use the
monday.get() method to retrieve the current context. We then use the
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
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.
You deserve it.
Updated about 1 month ago