Working with actions

Learn how to define custom JavaScript actions with arguments, events, and cleanup functions to add specialized capabilities to your Nordcraft workflows.

Create an action

Live

To create an action:

1. 1

   Open the project sidebar by clicking the folder icon or using Cmd/Ctrl + K
2. 2

   Locate the Actions section, click the + button and enter a name
3. 3

   Add a short description for your action
4. 4

   Write your JavaScript code in the code editor

Custom actions have a specific structure with an entry function that receives two parameters:

• args: contains all arguments passed to the action
• ctx: provides access to Nordcraft-specific functionality

The function can return a cleanup function that will be called when the component unmounts.

Configure arguments

Live

To add arguments to your action:

1. 1

   Click the + button in the Arguments section
2. 2

   Enter a name for the argument
3. 3

   Select the argument type from the dropdown ( String, Number, etc.)

In your code, access these arguments through the args parameter, using the names you defined. If you have an argument named value, access it in the code editor using args.value.

Set up events

Live

To create events that your action can trigger:

1. 1

   Click the + button in the Events section
2. 2

   Enter a name for the event
3. 3

   Optionally provide example output to define the data structure

In your code, you can trigger events using the context object's triggerActionEvent method with the event name and data. When using the action in a workflow, you can then handle these events by adding actions to them.

For example, to trigger an event named update_user in your action, use triggerActionEvent("update_user", data) where data is an object that has been passed as an argument into the action, which you can modify in the action if necessary.

When developing actions, keep these important considerations in mind:

• Client-side only: Actions run in the browser only (client-side), not during server-side rendering
• DOM access: Use ctx.root instead of document for DOM operations to ensure compatibility with Shadow DOM when components are exported as web components
• Asynchronous code: Actions can be asynchronous using the async/await syntax or Promises
• Cleanup: Return a function from your action to automatically clean up resources when the component that triggered the action is unmounted (e.g. remove event listener)
• Error handling: Actions should handle errors gracefully to avoid breaking your application

Custom actions can be used just like built-in workflow actions. When creating a workflow, you can add your custom actions as nodes by selecting them from the Project Actions section. You can provide values for any arguments defined in the action and handle any events it might trigger.

Here is an example of a custom action in Norcraft. It demonstrates how the canvas-confetti library can be integrated to create a celebratory effect when triggered.