MIGRATION GUIDE
This page outlines all the changes made from V1 to V2 that are not backwards compatible.
Subcommands
Smartblocks V1 had this notion of "subcommands" - commands that only resolved when paired with a supported command. For example:
<%TODOTODAY%> <%PAGE%>
Would resolve in a block text that looks like:
[[Name of page with todo block]]
This introduced an antipattern of nested command logic residing outside of the commands. In V2, subcommands are now simply formatting options for the output of the parent command. For example, the above should now be written as:
<%TODOTODAY:5,(({uid})) {page}%>
TODO Commands
Related to the subcommands bullet above, TODO commands used to have the following arguments:
Limit
Search terms
They now have the following arguments:
Limit
Format
Search terms
BLOCKMENTIONS Commands
Related to the subcommands bullet above, BLOCKMENTIONS commands now have a formatting argument before the search terms.
Date Formats
The underlying date formatting library was switched to start using date-fns. This means format parameters for DATE
commands will be using different conventions. Please consult the formatting docs to see how to achieve desired behavior.
JavaScript Commands Return Values
For both async and regular JavaScript commands, you could return any of the following types and it will be handled by the SmartBlocks engine.
A string - will output the value to a single block
An array of strings - will output the value to multiple sibling blocks
An array of Nodes - will output the value to multiple sibling and child blocks
A Node is an object with a
text
field of typestring
and achildren
field which maps to an array of Nodes.
RESOLVEBLOCKREFATEND Removed
Due to how commands now resolve, RESOLVEBLOCKREFATEND
is now a redundant command with RESOLVEBLOCKREF
.
REPEAT
Command Changed
The REPEAT
command now repeats the second argument in the command. So now instead of repeating blocks like this:
<%REPEAT:5%>
Repeat Me!
It repeats blocks like this:
<%REPEAT:5, Repeat Me!%>
GOTOBLOCK
and GRAPH
are now parameters.
Related to the sub commands bullet above, the GOTOBLOCK and GRAPH sub commands have been removed in favor of being used as blocks.
GOTOBLOCK
should simply be specified as the second argument for its two supported commands, like this:
<%OPENPAGE:08-27-2021,GOTOBLOCK 2%>
<%SIDEBARWINDOWOPEN:08-27-2021,GOTOBLOCK 2%>
Similarly, GRAPH
should be specified as the second argument to its one supported command:
<%SIDEBARWINDOWOPEN:08-27-2021,GRAPH%>
Additionally, GOTOBLOCK
now supports any numerical value, not just 1 or -1.
42Setting
Removed
A goal of creating the SmartBlocks extension was so that it could live independently, absent the original Roam42 extension. This means removing any Roam42 specific functionality. This resulted in the removal of the 42Setting
command.
This command can be replaced using the existing SmartBlocks command set. For example, to replace a block that had this:
<%42SETTING:name%>
Can be replaced with this block:
<%REPLACE:<%REPLACE:<%RESOLVEBLOCKREF:<%BLOCKMENTIONS:1,42Setting,{uid},name%>%>,<%HASHTAG:42Setting%>%>, name %>
It will be supported when the SmartBlocks extension is in included with the Roam42 bundle.
roam42
methods
If you used JAVASCRIPT
commands that contain roam42.common
methods, these methods will no longer be available by default with SmartBlocks v2. Here are a list of common Roam42 methods with their mitigation nested under it:
roam42.common.createBlock(parent_uid, order, block_string)
const uid = window.roamAlphaAPI.util.generateUID(); window.roamAlphaAPI.createBlock({ location: { "parent-uid": parent_uid, order }, block: { string: block_string, uid } }); return uid;
roam42.common.createSiblingBlock(fromUID, block_string, bBelow)
const [{order}, {uid: parent_uid}] = window.roamAlphaAPI.q(`[:find (pull ?b [:block/order]) (pull ?p [:block/uid]) :where [?b :block/uid "${fromUID}"] [?p :block/children ?b] ]`)[0]; const uid = window.roamAlphaAPI.util.generateUID(); window.roamAlphaAPI.createBlock({ location: { "parent-uid": parent_uid, order: order + bBelow }, block: { string: block_string, uid } }); return uid;
roam42.common.moveCursorToNextBlock
This method is pretty hacky and would not recommend using until Roam releases an API for doing this. In any case, if you're still interested, I would look at the source code directly.
roam42.common.moveCursorToPreviousBlock
This method is pretty hacky and would not recommend using until Roam releases an API for doing this. In any case, if you're still interested, I would look at the source code directly.
roam42.common.updateBlock(uid, block_string, open)
window.roamAlphaAPI.updateBlock({ block: { uid, string: block_string, open } })
roam42.settings.get
I would use
SET
andGET
commands instead. If insistent on using Roam42 Settings, then see this section
roam42.smartBlocks.activeWorkflow.vars[name]
Smartblock Variables are not available by default in
JAVASCRIPT
commands. Simply use the variablename
.