extensions
projects
contribute

DEVELOPER DOCS

Table of Contents

  7. Alternative Methods

Overview

SmartBlocks exposes a set of functions and objects for interacting with workflows. Roam developers can read from and write to these values from a roam/js block or as part of existing RoamJS extensions. This section includes technical notes for JavaScript developers working with SmartBlocks.

All methods below are attached to the window.roamjs.extensions.smartblocks object. Be careful before invoking any of them on load, as you will need to wait until the SmartBlocks extension is fully loaded.

registerCommand

This function allows you to create a custom command that users could include in their workflows for specialized functionality. The following example adds the <%GOOGLECALENDAR%> command to Smart Blocks:

window.roamjs.extension.smartblocks.registerCommand({
  text: 'GOOGLECALENDAR',
  handler: (context) => (arg1, arg2, ...etc) => [
    'Meeting with RoamJS!', 
    arg1, // each argument is a string
    arg2
  ],
});

The parameters are:

  1. text: the label of the command. Label must be all capital letters

  2. help: the description of the command, appears when command is selected from autocomplete menu

  3. handler: a callback method. It takes in a context object and returns a second callback. The second callback takes in a list of string arguments and returns the text or list of texts to be outputted by the command

The context object has the following fields:

  • targetUid - the target block uid the smart block workflow is outputting to.

  • variables - the set of variables defined by the workflow so far.

To help with the race condition of which script loads first between SmartBlocks and the one housing your custom command, there is a registerSmartBlocksCommand available in the roam client npm library for those who use node.js to develop extensions.

triggerSmartblock

This function allows you to trigger a SmartBlock workflow defined in the user's graph anywhere in the graph. The following example runs a "Daily" workflow on the Daily Note Page for 10/6/2021:

window.roamjs.extension.smartblocks.triggerSmartblock({
  srcName: 'Daily',
  targetName: 'October 6th, 2021'
});

The parameters are:

  1. srcName: The name of the workflow to trigger. Either this parameter or srcUid must be defined.

  2. srcUid: The block reference of the workflow to trigger. Either this parameter or srcName must be defined.

  3. targetName: The name of the page to trigger the workflow. By default, the workflow is triggered at the bottom of the page. Either this parameter or targetUid must be defined.

  4. targetUid: The block reference of the workflow to trigger. Either this parameter or targetName must be defined.

  5. variables: Any variables to define at the start of the workflow to be accessible by variable-related commands.

The return value is either:

  1. 0 if there are no blocks outputted as a result of this SmartBlock

  2. string representing the uid of the first block of the outputted SmartBlock

Support

There is an active community at roamresearch.slack.com channels #roam42 and #roamjs discussing and building SmartBlocks. Stop by if you need help or want to share your ideas.

Back to Overview