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:
text
: the label of the command. Label must be all capital lettershelp
: the description of the command, appears when command is selected from autocomplete menuhandler
: 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:
srcName
: The name of the workflow to trigger. Either this parameter orsrcUid
must be defined.srcUid
: The block reference of the workflow to trigger. Either this parameter orsrcName
must be defined.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 ortargetUid
must be defined.targetUid
: The block reference of the workflow to trigger. Either this parameter ortargetName
must be defined.variables
: Any variables to define at the start of the workflow to be accessible by variable-related commands.
The return value is either:
0
if there are no blocks outputted as a result of this SmartBlockstring
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.