COMMAND REFERENCE

Table of Contents


SmartBlocks Command Reference

This is a directory of all of the supported commands in the SmartBlocks extension.

Date/Time Commands

Date/Time commands use relative timing to resolve to Roam dates and times

DATE

Purpose: Use a date natural language processor to return a properly formatted Roam date. An optional second parameter allows you to control the format of the returned date.

Parameters:

  1. An expression that will resolve to a date

  2. Optional parameter that tells SmartBlocks to not return a Roam formatted date, but a date formatted in the format you specify. Supported date formats defined here: https://date-fns.org/v2.22.1/docs/format. Examples:

    • yyyy-MM-dd: 2020-10-12

    • MMM dd: Oct 12

    • ww: 42

Examples:

  • <%DATE:Today%>

  • <%DATE:Friday%>

  • <%DATE:Friday%>

  • <%DATE:5 days from now%>

  • <%DATE:In two weeks%>

  • <%DATE:In two weeks,yyyy-MM-dd%>

Special notes:

  • DATE also supports special abbreviations:

    • DBOM or DEOM = Beginning/End of month

    • DBONM or DEONM = Beginning/End of next month

    • DBOY or DEOY = Beginning/End of year

    • DBONY or DEONY = Beginning/End of next year

TIME

Purpose: Inserts the time in 24 hour format

Parameters:

  1. An optional expression that can resolve to a time

Example:

  • <%TIME%>

TIMEAMPM

Purpose: Inserts the time in AM/PM format

Parameters:

  1. An optional expression that can resolve to a time

Example:

  • <%TIMEAMPM%>

DATEBASIS

Purpose: Changes the date basis used by SmartBlocks in determining the context in which dates are calculated. By default, TODAY's date is the basis for all commands.

  • Video explanation of DATEBASIS:

  • This command sets the mode for the workflow. You can change between modes in one workflow.

Parameters:

  1. Date basis to be used in the workflow

    • If DNP - will use the date of the Daily Notes Page if the workflow is run on a DNP, otherwise will still use today.

    • Otherwise provide a natural language date command to determine the date basis

Examples:

  • <%DATEBASIS:DNP%>

    • Uses the Daily Note Page date that the workflow is run on, if it's not a DNP it will use Today's date

  • <%DATEBASIS:today%>

    • Use today's date as the basis

  • <%DATEBASIS:in 3 days%>

    • Use the date 3 days from now as the date basis

  • <%DATEBASIS:in two weeks%>

Serendipity Commands

Serendipity commands are commands that help resolve to a random block from your page.

RANDOMBLOCK

Purpose: Grabs a random block from your graph and inserts it as a block reference.

Parameters: no parameters

Example:

  • <%RANDOMBLOCK%>

RANDOMBLOCKFROM

Purpose: Returns a random block from a page or a child block from a parent block provided in the parameter

Parameters: One parameter that could be either:

  • Option 1: Page name or tag name (brackets [[]] or hashtag # are optional)

  • Option 2: Parent block UID

Example:

  • <%RANDOMBLOCKFROM:Evergreen Notes%>

  • <%RANDOMBLOCKFROM:935dpJL8X%>

RANDOMBLOCKMENTION

Purpose: Returns a random block from places where the page is referenced.

Parameters: One or more parameters as a Page name or tag name (brackets [[]] or hashtag # are optional)

Example:

  • <%RANDOMBLOCKMENTION:Evergreen Notes%>

RANDOMCHILDOF

Purpose: Returns a random child block of a block that's referencing the input page

Parameters: One parameter that could be either:

  • Option 1: Page name or tag name (brackets [[]] or hashtag # are optional)

  • Option 2: Parent block UID

Example:

  • <%RANDOMCHILDOF:Evergreen Notes%>

RANDOMPAGE

Purpose: Grabs a random page from your graph and inserts it.

Parameters: no parameters

Example:

  • <%RANDOMPAGE%>

TODO Commands

TODO commands are multi-block commands that query multiple TODOs from your graph based on a set of conditions.

TODOTODAY

  • Purpose: Returns a list of block references of TODOs for today

  • Parameters:

    1. Maximum amount of block references to return. Default value is 20

    2. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

      1. {uid} - resolves to the block reference

      2. {page} - resolves to the page the block originated from

      3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

      4. {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

      5. {text} - resolves to the raw text of the block

    3. optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

      • toRead,Pinnacle

        • returns blocks with toRead AND Pinnacle in the text

      • toRead|Pinaccle

        • returns blocks with toRead OR Pinnacle in the text

      • toRead,-Pinnacle

        • returns blocks with toRead but not if they have pinnacle

  • Example: <%TODOTODAY:20,(({uid}))%>

TODOOVERDUE

  • Purpose: Returns a list of block references of TODOs for overdue TODOs. That is TODOs that have a dated page reference in them.

  • Parameters:

    1. Maximum amount of block references to return. Default value is 20

    2. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

      1. {uid} - resolves to the block reference

      2. {page} - resolves to the page the block originated from

      3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

      4. {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

      5. {text} - resolves to the raw text of the block

    3. optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

      • toRead,Pinnacle

        • returns blocks with toRead AND Pinnacle in the text

      • toRead|Pinaccle

        • returns blocks with toRead OR Pinnacle in the text

      • toRead,-Pinnacle

        • returns blocks with toRead but not if they have pinnacle

  • Examples: <%TODOOVERDUE:20,(({uid}))%>

TODOOVERDUEDNP

  • Purpose: Returns a list of block references of TODOs for overdue TODOs. That is TODOs that have a dated page reference in them. Additionally TODOs that are on a Daily Notes Page (DNP) without a date from the past.

  • Parameters:

    1. Maximum amount of block references to return. Default value is 20

    2. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

      1. {uid} - resolves to the block reference

      2. {page} - resolves to the page the block originated from

      3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

      4. {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

      5. {text} - resolves to the raw text of the block

    3. optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

      • toRead,Pinnacle

        • returns blocks with toRead AND Pinnacle in the text

      • toRead|Pinaccle

        • returns blocks with toRead OR Pinnacle in the text

      • toRead,-Pinnacle

        • returns blocks with toRead but not if they have pinnacle

  • Examples: <%TODOOVERDUEDNP:20,(({uid}))%>

TODOFUTURE

Purpose: Returns a list of block references of TODOs for future TODOs. That is TODOs that have a dated page reference in them.

Parameters:

  1. Maximum amount of block references to return. Default value is 20

  2. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

    1. {uid} - resolves to the block reference

    2. {page} - resolves to the page the block originated from

    3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

    4. {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

    5. {text} - resolves to the raw text of the block

  3. optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

    • toRead,Pinnacle

      • returns blocks with toRead AND Pinnacle in the text

    • toRead|Pinaccle

      • returns blocks with toRead OR Pinnacle in the text

    • toRead,-Pinnacle

      • returns blocks with toRead but not if they have pinnacle

Examples:<%TODOFUTURE:20,(({uid}))%>

TODOFUTUREDNP

  • Purpose: Returns a list of block references of TODOs for future TODOs. That is TODOs that have a dated page reference in them. Additionally TODOs that are on a Daily Notes Page (DNP) without a date on a future date.

  • Parameters:

    1. Maximum amount of block references to return. Default value is 20

    2. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

      1. {uid} - resolves to the block reference

      2. {page} - resolves to the page the block originated from

      3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

      4. {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

      5. {text} - resolves to the raw text of the block

    3. optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

      • toRead,Pinnacle

        • returns blocks with toRead AND Pinnacle in the text

      • toRead|Pinaccle

        • returns blocks with toRead OR Pinnacle in the text

      • toRead,-Pinnacle

        • returns blocks with toRead but not if they have pinnacle

  • Examples: <%TODOFUTUREDNP:20,(({uid}))%>

TODOUNDATED

  • Purpose: Returns a list of block references of TODOs with no date

  • Parameters:

    1. Maximum amount of block references to return. Default value is 20

    2. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

      1. {uid} - resolves to the block reference

      2. {page} - resolves to the page the block originated from

      3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

      4. {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

      5. {text} - resolves to the raw text of the block

    3. optional filter parameter based on a comma separated list (case-insensitive). Can use - in front of a word to exclude it. Examples:

      • toRead,Pinnacle

        • returns blocks with toRead AND Pinnacle in the text

      • toRead|Pinaccle

        • returns blocks with toRead OR Pinnacle in the text

      • toRead,-Pinnacle

        • returns blocks with toRead but not if they have pinnacle

  • Examples: <%TODOUNDATED:20,(({uid}))%>

Block Related Commands

Block Related commands provide commands for grabbing values in blocks and other properties from your graph.

ATTRIBUTE

Purpose: Returns the arguments as a Roam attribute, so that your workflow definition doesn't create a reference

Parameters:

  1. Text to turn into attribute

Example:

  • <%ATTRIBUTE:Date%>

BLOCKMENTIONS

Purpose: returns a list of blocks that mention a page reference, with optional filtering. This is a multi-block command and has some limitations how it interacts with other commands.

Parameters: List of comma separated parameters

  1. Maximum amount of block references to return.

    1. if set to -1, will return only count of matches

  2. Page name or tag name (This parameter is case-sensitive and must match your page or tag name as used in your graph)

  3. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

    1. {uid} - resolves to the block reference

    2. {page} - resolves to the page the block originated from

    3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

    4. {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

    5. {text} - resolves to the raw text of the block

  4. Optional filtering parameters, with support for include and excluding blocks based on their text with simple text comparison

Example:

  • <%BLOCKMENTIONS:15,toRead%>

    • Returns up to 15 blocks that mention #toRead or [[toRead]]

  • <%BLOCKMENTIONS:15,toRead,book%>

    • Returns up to 15 blocks that mention #toRead or [[toRead]] that also have the word "book" in the text of the block

  • <%BLOCKMENTIONS:15,toRead,book,pinnacle%>

    • Returns up to 15 blocks that mention #toRead or [[toRead]] that also have the words "book" and "pinnacle" in the text of the block

  • <%BLOCKMENTIONS:15,toRead,book,-pinnacle%>

    • Returns up to 15 blocks that mention #toRead or [[toRead]] that also have the word "book" but not "pinnacle" in the text of the block

BLOCKMENTIONSDATED

Purpose: returns a list of blocks that mention a page reference, based on a specified date range, with optional filtering. This is a multi-block command and has some limitations how it interacts with other commands.

  • Video of how to use: (No Audio)

Parameters: List of comma separated parameters

  1. Maximum amount of block references to return.

    1. if set to -1, will return only count of matches

  2. Page name or tag name (This parameter is case-sensitive and must match your page or tag name as used in your graph)

  3. Start date - tasks with a date from start date and beyond until parameter 3 (End Date). Date NLP is supported, so you can do something like: Today, yesterday, 2020-12-31 and other formats.

    1. Set to 0 for no start date

    2. Set parameter 3 and 4 to -1 to have it return blocks that have no date in them

  4. End Date - all tasks from the end date and before, until parameter 2 (start date). Date NLP is supported, so you can do something like: Today, yesterday, 2020-12-31 and other formats.

    1. Set to 0 for no end date

  5. Sort Order

    • ASC - oldest dated blocks to newest

    • DESC - newest dated blocks to oldest

    • NONE - no date sort defined, just return them alphabetically

  6. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

    1. {uid} - resolves to the block reference

    2. {page} - resolves to the page the block originated from

    3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

    4. {attr:name:format} - resolves the attribute value of the attribute found on the page with the block. Replace name with the name of the attribute. The format is optional and could be used to specify additional text that only appears if the attribute is on the page.

    5. {text} - resolves to the raw text of the block

  7. Optional filtering parameters, with support for include and excluding blocks based on their text with simple text comparison. Filters are processed before date processing. This means if filters are designed to include or exclude text, they will be processed before the dates are processed.

Example:

<%BLOCKMENTIONSDATED:10,TODO,2020-12-1,2020-12-30,ASC%>

Returns all blocks with [[TODO]] with a date reference from date Dec 1 to Dec 30, 2020 and do so in ascending order

<%BLOCKMENTIONSDATED:10,toRead,0,yesterday,DESC,-book%>

Returns all blocks with [[toRead]] with a date reference up to end of December but don't have book in the text and the list the blocks in date descending order

BREADCRUMBS

Purpose: Returns the path of parents for a given block reference.

Parameters:

  1. Block Reference UID

    • Add a + to front of UID to get back just the page title

    • Add a - to get back just the path, without the page title

  2. Separator to be used to separate each parent

Example:

  • <%BREADCRUMBS:(( UID )),>%>

    • Will use > as a separator between block refs

  • <%BREADCRUMBS:+(( UID )),>%>

    • Returns just the page title

  • <%BREADCRUMBS:-(( UID )),>%>

    • Returns just the path blocks, no page title

CHILDREN

Purpose: Gets the block tree nested under the input block reference.

Parameters:

  1. Variable name or a block reference.

Examples:

  • <%CHILDREN:%>

CONCAT

Purpose: Combines a comma separated list of strings into one string.

Parameters Comma separated list

Examples:

  • <%CONCAT:[,[pageName],]%>

    • outputs [[pageName]]

  • <%CONCAT:[,[pageName],]]\, followed by more text%>

    • outputs [[pageName]]], followed by more text

    • Special note: if you want a comma to be a part of the output, put a \ in front of it as in this last example

CURRENTPAGENAME

Purpose: Returns the name of the current page. Stores it in a variable if present.

Parameters:

  1. Variable name. If parameter is equal to base, then will return the base page name of a namespaced title instead.

Example:

  • <%CURRENTPAGENAME%>

CURRENTUSER

Purpose: Return the display name of the user.

Parameters: None

Example:

  • <%CURRENTUSER%>

CURRENTBLOCKREF

Purpose: Gets the current block reference. Stores it in a variable if present.

Parameters:

  1. Name of variable

Example

  • <%CURRENTBLOCKREF:varName%>

    • Will store the current block reference into a variable named varName

CURRENTBLOCKCONTENT

Purpose: Gets the current block content. Stores it in a variable if present.

Parameters:

  1. Name of variable

Example

  • <%CURRENTBLOCKCONTENT:varName%>

    • Will store the current block reference into a variable named varName

GETATTRIBUTE

Purpose: Returns the attribute value nested under the input block with a given input name.

Parameters:

  1. Page name or block ref

  2. A behavior to perform after navigating.

Example:

  • <%GETATTRIBUTE:ref,Name%>

TRIGGERREF

Purpose: Gets the block reference where the Smartblock was triggered from. Stores it in a variable if present.

Parameters:

  1. Name of variable

Example

  • <%TRIGGERREF:varName%>

    • Will store the current block reference into a variable named varName

RESOLVEBLOCKREF

Purpose: Converts a block reference (()) into its text equivalent

Parameters: Block Reference

Example:

  • <%RESOLVEBLOCKREF:8tRgishTE%>

  • <%RESOLVEBLOCKREF:[**Example**: ](/extensions/smartblocks/command_reference#8tRgishTE)%>

SEARCH

Purpose: searches all blocks for a specific string of case-sensitive text and returns a list of matching block references, with optional filtering

  • Video of how to use: (No Audio)

Parameters:

  1. Maximum amount of block references to return.

  2. Format to output the block in. Default value is (({uid})). Supports the following placeholders:

    1. {uid} - resolves to the block reference

    2. {page} - resolves to the page the block originated from

    3. {path} - resolves to the uids of blocks that are parents of the current block, delimited by >

    4. {attr:name} - resolves the attribute value of the attribute found on the page with the block. Replace name with name of attribute

  3. string of text to find (CASE-SENSITIVE)

  4. Parameter 3 to X: Optional filtering parameters, with support for include and excluding blocks based on their text with simple text comparison. Prefix with - to say that the text shouldn't include a term

Example:

<%SEARCH:15,(({uid})),apple pie%>

Returns up to 15 blocks that contain "apple pie"

<%SEARCH:15,(({uid})),apple pie,ice cream%>

Returns up to 15 blocks that contain "apple pie" and "ice cream"

<%SEARCH:15,(({uid})),apple pie,ice cream. chocolate%>

Returns up to 15 blocks that contain "apple pie" and "ice cream" and "chocolate"

<%SEARCH:15,(({uid})),apple pie,ice cream. chocolate,-vanilla%>

Returns up to 15 blocks that contain "apple pie" and "ice cream" and "chocolate", but not including "vanilla"

HASHTAG

Purpose: Returns the arguments as a Roam hashtag, so that your workflow definition doesn't create a reference

Parameters:

  1. Text to tag

Example:

  • <%HASHTAG:Projects%>

TAG

Purpose: Returns the arguments as a Roam tag, so that your workflow definition doesn't create a reference

Parameters:

  1. Text to tag

Example:

  • <%TAG:<%DATE:today%>%>

REPLACE

Purpose: Replaces the contents of the first argument by searching for the expression of the second argument with the result of the third argument.

Parameters:

  1. Content to replace. Can be raw text, a SmartBlock Variable, or a block reference.

  2. Expression to search for. Supports wrap in inline code styling.

  3. Content to replace with. Can be raw text or a SmartBlock Variable

Example:

  • <%REPLACE:This is a sentence,sentence,block%>

UPDATEBLOCK

Purpose: Updates the block in the first argument with the contents of the second

Parameters:

  1. Reference of block to replace. Can be a SmartBlock variable

  2. Content to replace with. Can be a SmartBlock variable

Example:

  • <%UPDATEBLOCK:ref,hello world!%>

Logic Control Commands

Logic Control Commands are commands that facilitate control flow and decision points in the workflow.

IF

Purpose: Performs simple IF/Then/Else type logic commands. Use in combination with <%THEN%> and <%ELSE%>

Parameters:

  1. Logic to be evaluated. Uses Javascript-like comparison logic. Strings require quotes

    • == Equals Example: <%IF:2==(1+1)%>

    • != Not Equals Example: <%IF:2!=(1+1)%>

  2. (Optional) Text returned if true. Can use this instead of THEN

  3. (Optional) Text returned if false. Can use this instead of ELSE

Example:

  • <%IF:2==(1+1)%>``<%THEN:The result is true%>``<%ELSE:The result is false%>

THEN and ELSE

Purpose: When an IF command evaluates to true, render the THEN commands. If it evaluates to FALSE render the ELSE commands.

Parameters:

  1. Text to be inserted into block

Example:

  • <%IF:2==(1+1)%>``<%THEN:The result is true%>``<%ELSE:The result is false%>

IFTRUE

Purpose: Tests if the parameter is true. If it evaluates to true, the rest of the block is output. If false, the block (and all child blocks of the IFTRUE block) is skipped.

Parameters:

  1. Logic to be evaluated. Uses Javascript like comparison logic. Strings require quotes

    • == Equals Example: <%IFTRUE:2==(1+1)%>

    • != Not Equals Example: <%IFTRUE:2!=(1+1)%>

Example:

  • <%IFTRUE:2==2%> this block will get output

  • <%IFTRUE:2==3%> this block will NOT get output

IFDATEOFYEAR

Purpose: Using today's date, compares to the date of the year to see if there is a match.

  • If they match, the block is inserted

  • If there is no match, the block is not inserted

Parameters:

  1. A number from 1 to 31 corresponding to the day in the month. Optionally, a comma separated list of numbers to test for multiple days

Example:

  • <%IFDATEOFYEAR:07/27%> (Inserts this block if it is July 27th)

  • <%IFDATEOFYEAR:01/01,04/01,09/01,12/01%> (Inserts this block if it is the first day of the quarter)

IFDAYOFMONTH

Purpose: Using today's date, compares to the day in the month to see if there is a match.

  • If they match, the block is inserted

  • If there is no match, the block is not inserted

Parameters:

  1. A number from 1 to 31 corresponding to the day in the month. Optionally, a comma separated list of numbers to test for multiple days

Example:

  • <%IFDAYOFMONTH:1%> (Inserts this block if it is the first day of the month)

  • <%IFDAYOFMONTH:15,30%> (Inserts this block if it is the it is the 15th or 30th of the month)

IFDAYOFWEEK

Purpose: Using today's date, compares to the day of the week to see if there is a match.

  • If they match, the block is inserted.

  • If there is no match, the block is not inserted

Parameters:

  1. A number from 1 to 7, 1 is Monday, 2 is Tuesday and so on. Optionally, a comma separated list of numbers to test for multiple days

Example:

  • <%IFDAYOFWEEK:7%> (This block will be inserted if today is Sunday)

  • <%IFDAYOFWEEK:1,3,5%> (This block will be inserted if today is Monday, Wednesday or Friday)

IFTAGINBLOCK

Purpose: Using the block reference, compares to see if the tag is in the block.

  • If it is, the block is inserted.

  • If it isn't, the block is not inserted

Parameters:

  1. Page or uid to check

  2. A block reference to check

Example:

  • <%IFTAGINBLOCK:TODO,%>

IFCHILDREN

Purpose: Compares whether the current block produced children, and if not, skips.

Parameters: No Parameters

Example:

  • <%IFCHILDREN:TODO,%>

INPUT

  • Purpose: prompts user for input which will then be inserted into the block

  • Parameters: Parameters in this command are delimited by %%

    1. Text that will be displayed to the user.

      1. Could add a {page} placeholder to turn the input into a Page Input that accepts page values.

      2. Could add a {block} placeholder to turn the input into a Block Input that accepts block values and returns the text.

      3. Could add a {ref} placeholder to turn the input into a Block Input that accepts block values and returns the reference.

    2. Default value for the input

    3. Any number of other options. Specifying 3 or more parameters turn the input from a text input to a dropdown.

  • Example 1: (No default value for input)

    • <%INPUT:Attendees for this meeting?%>

  • Example 2: (Default value for input)

    • <%INPUT:Attendees for this meeting?%%Jim, Sally, Bob%>

  • Example 3: (Dropdown for input)

    • <%INPUT:Guest for this meeting?%%Jim%%Sally%%Bob%>

  • Example 4: (Page Input)

    • <%INPUT:Guest for this meeting?{page}%>

SET

Purpose: Sets the value of a variable in memory. Variables are case-sensitive.

Parameters:

  1. Variable name

  2. Value of Variable

Example:

<%SET:MyVariableName,my value%>

GET

Purpose: retrieves a variable from memory

Parameters:

  1. Variable name. Should contain only letters and number, no special symbols. Variables are case-sensitive.

Example:

  • <%GET:MyVariableName%>

HAS

Purpose: checks if a variable is defined within the SmartBlock workflow, returns "true" or "false"

Parameters:

  1. Variable name. Should contain only letters and number, no special symbols. Variables are case-sensitive.

Example:

  • <%HAS:MyVariableName%>

CLEARVARS

Purpose: Removes all variables from memory

Parameters: none

Example:

  • <%CLEARVARS%>

SUM

Purpose: Sum any number of parameters together and output the value. If one of them is a Daily Note Page, the result will be a Daily Note Page summing by the number of days.

Parameters:

  1. Addend to sum

Example:

  • <%SUM:2,3,4%>

DIFFERENCE

Purpose: Finds the difference between two values. If the two values are daily note pages, returns the difference in number of days. If only one of the two values is a daily note page, the result with return a new daily note page based on the number of days before.

Parameters:

  1. The minuend

  2. The subtrahend

Example:

  • <%DIFFERENCE:2,1%>

PRODUCT

Purpose: Multiplies all of the parameters together and output the value.

Parameters:

  1. Factor to multiply

Example:

  • <%PRODUCT:2,3,4%>

DIVISION

Purpose: Find the quotient between two parameters and output the value.

Parameters:

  1. The dividend

  2. The divisor

Example:

  • <%DIVISION:6,3%>

SMARTBLOCK

Purpose: Calls another smartblock workflow, outputting the result in place. The SmartBlock workflow will inherit variables defined in the parent smart block.

Parameters:

  1. The workflow name

  2. An optional page name to execute the workflow on another page. The command will return a block reference to the other page if this parameter is set.

Example:

  • <%SMARTBLOCK:Daily%>

  • <%SMARTBLOCK:Daily,<%DATE:Tomorrow%>%>

REPEAT

Purpose: Repeats the second argument a specified amount of times.

Parameters:

  1. Count of repeats

  2. Content to repeat

Example:

  • <%REPEAT:5,hello%>

Cursor Commands

These commands affect focus and other DOM-related properties.

CLIPBOARDCOPY

Purpose: Writes text content to the clipboard.

May not work in all browsers, please test in your environment

Parameters: text to be written to the clipboard.

Example:

  • <%CLIPBOARDCOPY:This text is written to clipboard%>

CLIPBOARDPASTETEXT

Purpose: Reads the text of the clipboard as text

May not work in all browsers, please test in your environment

Parameters: no parameters

Example:

<%CLIPBOARDPASTETEXT%>

CURSOR

Purpose: define where cursor should be located after the workflow completes.

If a workflow contains multiple <%CURSOR%> commands, the last instance of it will be used. If there were multiple <%CURSOR%> commands left over after workflow is run, only the last instance is replaced.

Parameters: no parameters

Example:

  • <%CURSOR%>

INDENT

Purpose: Indent the current block if possible. Only works if preceded by a block in the same level.

Parameters: None

UNINDENT

Purpose: Un-indent the current block if possible. Only works if the block lives in a nested level

Parameters: None

FOCUSONBLOCK

Purpose: Focus on this block after the workflow finishes running by navigating to its page. If a workflow contains multiple <%FOCUSONBLOCK%> commands, the last instance of it will be used.

Parameters: no parameters

Example:

  • <%FOCUSONBLOCK%>

Commands With Effects

These are special commands that have side effects that affect your graph and the running workflow in different ways.

EXIT

Purpose: Stops the workflow from going further after completing the current block.

Parameters: no parameters

Example:

  • <%EXIT%>

NOTIFICATION

Purpose: Displays a small pop-up notification message in the top of Roam.

Parameters:

  1. Number of seconds the notification is visible

  2. Message to be displayed. Supports Markdown rendering

  3. Position of the notification. By default it shows on top. Valid values are

    • top

    • bottom

    • top left

    • top right

    • bottom left

    • bottom right

Example:

  • <%NOTIFICATION:10,Welcome to my SmartBlocks%>

    • Displays the notification for 10 seconds with the text "Welcome to my SmartBlocks"

  • <%NOTIFICATION:120,Welcome to my **SmartBlocks**%>

    • Displays the notification for 2 minutes (120 seconds) with the text "Welcome to my SmartBlocks"

NOBLOCKOUTPUT

Purpose: Will prevent the block from being output from the workflow, no matter what other commands come after it. This is useful to do operations in the workflow that have no visual rendering (reading clipboard, setting variables)

Parameters: no parameters

Example:

<%NOTIFICATION:5,This block will have no output%>**<%NOBLOCKOUTPUT%>**

SKIPIFEMPTY

Purpose: Will prevent the block from being output from the workflow, if there is no content outputted from the block itself.

Parameters: no parameters

Example:

<%NOTIFICATION:5,This block will have no output%>**<%SKIPIFEMPTY%>**

OPENPAGE

Purpose: Opens a page or block. Creates a page if the reference doesn't exist.

Parameters:

  1. Page name or block UID

  2. Optional effect after navigating. See migration guide for details.

Example:

  • <%OPENPAGE:My Page%>

  • <%OPENPAGE:gk78VGCKW,GOTOBLOCK 1%>

SIDEBARWINDOWOPEN

Purpose: Opens a page or block into the sidebar. Creates a page if the reference doesn't exist.

Parameters:

  1. Accepts a page name or block reference

  2. Optional effect after navigating. See migration guide for details.

Example:

  • <%SIDEBARWINDOWOPEN:My Page%>

  • <%SIDEBARWINDOWOPEN:gk78VGCKW%>

  • <%SIDEBARWINDOWOPEN:gk78VGCKW,GRAPH%>

OPENREFERENCESINSIDEBAR

Purpose: Opens all blocks referencing a page or block into the sidebar. Creates a page if the reference doesn't exist.

Parameters:

  1. Accepts a page name or block reference

Example:

  • <%OPENREFERENCESINSIDEBAR:My Page%>

SIDEBARWINDOWCLOSE

Purpose: Closes a window in the right sidebar or all windows

Parameters:

  1. A number. 0 will close all windows in the right sidebar. Greater than or equal to 1 will close the corresponding sidebar based on its position. Window 1 is at the top and numbers down

Example:

  • <%SIDEBARWINDOWCLOSE:0%>

  • <%SIDEBARWINDOWCLOSE:1%>

SIDEBARSTATE

Purpose: changes the state of either the left or right sidebar

Parameters:

  1. Accepts one parameter, a value of 1 to 4

    • 1 opens the left sidebar

    • 2 closes the left sidebar

    • 3 opens the right sidebar

    • 4 closes the right sidebar

Example:

  • <%SIDEBARSTATE:2%>

  • <%SIDEBARSTATE:3%>

APIGET

Purpose: Fires an API request to the input url and returns the data to the block. If the return is a JSON object, it will be stringified.

Parameters:

  1. URL

  2. Optional Field to return a specific field in the response data. Uses the lodash syntax for nested field values.

Example:

  • <%APIGET:http://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1%>

JavaScript Commands

An escape hatch to run whichever logic not already captured by the default commands above. Warning: do NOT run any smartblock workflow using one of these commands unless you either trust the contents, or trust the source of the contents.

For all the commands below, the command parameter is passed into a Function constructor. This means you need to return the output you'd like to see in the block. The input could be wrapped in either a code block (three backticks) or as an inline code (single backtick). The output could be any of the following types:

  • string - will output the result into one block

  • string[] - will output the results into multiple blocks

  • (Node: {text: string, children: Node[]})[] - will output the results in multiple blocks, allowing children.

Each command below also has access to variables that have been set by the workflow. To access a variable, simply use the name it was given in the function. For example, a command of <%SET:name,5%> will introduce a variable with name that has the value 5 in the workflow.

JAVASCRIPT or J

  • Purpose: Executes Javascript code, and the results are inserted into the block

    • Shorthand for JAVASCRIPT command is J

  • Parameters: a string of javascript code

  • Example:

    • <%JAVASCRIPT: return "5+5 = " + (5+5) %>

    • <%J: return "5+5 = " + (5+5) %>

JAVASCRIPTASYNC or JA

  • Purpose: Executes Javascript code using ASYNC, and the results are inserted into the block. Async is good for web services and functions that deal with call backs

    • Shorthand for JAVASCRIPT command is JA

  • Parameters: a string of javascript code.

  • Example:

    • <%JAVASCRIPTASYNC: return fetch("https://catfact.ninja/fact").then(r => r.json()).then(r => r.fact) %>

    • <%JA: return fetch("https://catfact.ninja/fact").then(r => r.json()).then(r => r.fact) %>

ONBLOCKEXIT

Purpose: This is a helper function for JavaScript developers to work with the DOM or to perform post-processing. It is called after a block has been completely processed and just before the next block from the workflow is processed. The return value is not used.

The code that is called will be handled asynchronously, similar to JAVASCRIPTASYNC

No return values are processed by the SmartBlocks Engine

Parameters: a string of JavaScript code.

Example:

<%ONBLOCKEXIT: console.log('hello!') %>

Workflow Modifiers

Add any of these commands to the workflow name to modify the workflow's entire behavior.

HIDE

Purpose: Excludes this workflow from the SmartBlock Menu

Usage

  • #SmartBlock NameOfSmartBlock <%HIDE%>

NOCURSOR

Purpose: After a SmartBlock has finished running, Roam should be left in a non-edit state, meaning no block currently has editing focus

Usage

  • #SmartBlock NameOfSmartBlock <%NOCURSOR%>

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.