DEVELOPER DOCS

Table of Contents

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:

The context object has the following fields:

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:

The return value is either:

Migrating from JavaScript Commands

On July 4th, 2022, all SmartBlock commands that execute arbitrary Javascript were deprecated as they could pose harm for users from attackers who are looking to circumvent Roam's extension review process.

For workflows that use IF, THEN, ELSE, and IFTRUE, commands, they could in most cases could be replace with the various other IF commands available, in particular IFVAR. If you have a use case that cannot be covered by the current conditional command set, feel free to reach out to support@roamjs.com.

For workflows that use the various JavaScript commands (JAVASCRIPT, J, JAVASCRIPTASYNC, JA, ONBLOCKEXIT), there are various strategies one could turn to, depending on the workflow in question.

The first step is to review the SmartBlocks Command Reference. In several cases, you may be writing code replicating features that are already available as a command. For example, this workflow:

<%SET:pageName,Quotes%><%NOBLOCKOUTPUT%>
<%JAVASCRIPTASYNC:
var results = await roamAlphaAPI.q(`
  [:find (rand 1 ?t) 
   :in $ ?page_title 
   :where [?e :node/title ?page_title] 
          [?e :block/children ?x] 
         [?x :block/string ?t] ] `,
    pageName);
return results[0][0];
%>

Could easily be replaced by:

<%RANDOMBLOCKFROM:Quotes,1,{text}%>

If the logic in your Javascript Command is complex enough that it could not be replaced by preexisting commands, I would then ask whether your workflow would be better served as an extension instead of a SmartBlock workflow. Any workflow that is integrating with some third party service or is manipulating existing data in your graph should probably be its own extension instead of being confined within a templating language. Roam has a command palette accessible from hitting CMD+p and adding to this menu with your own functionality is as easy as invoking:

window.roamAlphaAPI.ui.commandPalette.addCommand({
  label: "My Command",
  callback: () => console.log("Hello, World!"),
});

Extensions could then optionally integrate with SmartBlocks if they want to expose the same features as a SmartBlock command anyway:

const callback = () => console.log("Hello, World!");
window.roamAlphaAPI.ui.commandPalette.addCommand({
  label: "My Command",
  callback,
});
window.roamjs.extension.smartblocks.registerCommand({
  text: "MYCOMMAND",
  handler: (context) => callback,
});

One thing to keep in mind is that there is a race condition between your extension and the SmartBlocks extension. Meaning, you cannot guarantee the order in which the extensions load. To mitigate this issue, you can listen for when the SmartBlocks extension is loaded:

const args = {
  text: "MYCOMMAND",
  handler: (context) => () => console.log("Hello, World"),
};
if (window.roamjs?.extension?.smartblocks) {
  window.roamjs.extension.smartblocks.registerCommand(args);
} else {
  document.body.addEventListener(
    `roamjs:smartblocks:loaded`,
    () =>
      window.roamjs?.extension.smartblocks &&
      window.roamjs.extension.smartblocks.registerCommand(args)
  );
}

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.

Slack Invite Here

Back to Overview