How to create an action for Standard Notes
Have you recently started to use Standard Notes? Maybe you noticed that it provides few functionalities for your notes. This is not a big problem. Everyone can easily develop extensions like editors, themes, or actions.
In this article, we will look at the basics to develop action for Standard Notes. But first, what is an action?
What is an action?
For this definition, we can use the official documentation.
Actions are menu-based extensions that allow you to build simple APIs that do not require a user interface. Actions have the power to receive the working note and modify it. We use actions for our Note History extension, as well as Listed and File Attachments.
https://docs.standardnotes.org/extensions/actions
Main endpoint
Every action must have a main endpoint that, for each GET request, replies with this body.
{
"identifier": "com.my.action",
"name": "My action",
"content_type": "Extension",
"url": "my.action.com/main-endpoint",
"description": "My action description",
"supported_types": [
"Note"
],
"actions": [
{
"label": "Action 1",
"url": "action-1-endpoint",
"verb": "post",
"context": "Item",
"content_types": [
"Note"
],
"access_type": "decrypted"
},
{
"label": "Action 2",
"url": "action-2-endpoint",
"verb": "post",
"context": "Item",
"content_types": [
"Note"
]
}
]
}
Body structure:
- identifier: action package identifier
- name: action public name
- content_type: for an action should be set to “Extension”
- url: action url, usually is the main endpoint
- description: action description shown in extension menu
- supported_types: for now, only “Note” type is supported
- actions: an array of object that describes the available actions for this call
When the main endpoint is called?
- Every time the user clicks on the action menu on the top of the note editor
- Every time the user clicks on an action entry
Action description
{
"label": "Action 1",
"url": "action-1-endpoint",
"verb": "post",
"context": "Item",
"content_types": [
"Note"
],
"access_type": "decrypted"
}
- label: name of the action shown in the action menu
- url: action url which will be called for the request, can be easily customize for each request
- verb: indicates the type of request, can be show, post, render and get
- context: for now, can be only “Item”
- content_types: for now, can be only “Note”
Show
Standard Notes will open the url in a browser.
https://docs.standardnotes.org/extensions/actions/#properties
Standard Notes add automatically to the URL the item_uuid as a query parameter. The item_uuid is the note unique identifier from which the action is called.
Post
Standard Notes will make a POST request to the url with the current item included in the parameters.
https://docs.standardnotes.org/extensions/actions/#properties
Standard Notes inserts the current note in the body of the request with this format:
{
"items":
[
{
"uuid": "note uuid",
"content_type": "Note",
"content":
{
"text": "Note text",
"title": "Note title",
"references": [],
"appData":
{
"org.standardnotes.sn":
{
"client_updated_at": "2021-01-02T09:46:05.815Z",
"pinned": true
},
"org.standardnotes.sn.components":
{
"component uuid": {}
}
},
"preview_plain": "### "
},
"created_at": "2020-12-28T20:55:17.586Z",
"updated_at": "2021-01-02T09:46:05.912Z",
"duplicate_of": null
}
]
}
Now, you should know the basics to develop your actions for Standard Notes. You could also make your extensions public for the community by publishing them on Listed.to. Follow this guide for further information