WORKBENCH
Table of Contents
Overview
Customizations
Overview of workBench (wB)
workBench (wB for short) is a work bench for the Roam "handyman" or "hacker". Although originally designed for serious users looking to push Roam to new places by quickly navigating, manipulating and hacking the Roam environment. Roam is the blocks, workBench is your chisel.
Please note: this tool is designed for experienced Roam users who are comfortable working with keyboard application navigation.
The workBench value proposition:
Context shifting leads to mental drift. wB keeps you working on your priority tasks without losing focus. It does this by allowing you to manipulate your current document or work environment without a lot of effort.
Video Demonstration
How to Use
workBench (wB) is activated with the keyboard shortcut ctrl+;
. This will open wB and you can type in your request. The wB prompt will list a few features that you can select to run. Otherwise, start typing the name of the command you want to use and once it's selected in the list of wB commands, press enter for Roam42 to perform that command.
workBench includes a number of Commands, in addition to access to all SmartBlocks.
When a list of commands is presented in workBench, you can use the up and down arrow keys to select the command that interest you, then press enter to activate it.
workBench is context aware, it is aware of the context of how it was started, whether a single block was selected, or multiple blocks, or no blocks selected. The list of available commands is based on the context of when it is opened.
Commands
Working with Blocks
Move Blocks
Moves the currently selected block or blocks to another location in your graph
Many combinations of moves exist:
Move to top or bottom of page.
Move to page, but then open it in sidebar or main window.
Move it and leave behind a block reference
Pull Blocks
Pull a block from another location in your graph into the current location
Jump to block
Jumps to another block in your graph. This opens the whole page but scrolls the block in view.
Daily Notes Page
Move a block to a Daily Notes Page using Natural Language Processing for dates
Working with the Right Sidebar
Swap main document with sidebar
Swaps the document from the main window to the sidebar, and the sidebar window moved to main window
Right Sidebar - close windows
Closes all windows panes in the right sidebar
Working with Pages
Open Page
Opens a block zoomed in the main window or in the sidebar
Delete Page
Delete the current page or page specified in the path navigator
To remove the confirmation modal, you could configure
#42Setting workBenchDcpConfirm off
SmartBlocks
Your SmartBlocks can be invoked as well from the workBench
workBench Custom Actions
Inbox
Define commonly used destination points for moving items to other locations in the graph. The idea is similar to an inbox. You can have multiple named inboxes as destinations in your graph. These inboxes show up as first options when opening of the workBench for quick moves of blocks to other locations in graph. However, they also serve as reference points for other commands available in workBench.
Structure of Inbox action
#42workBench Inbox
Name:
Page:
Text:
Location:
Blockref:
Users:
The parent block starts with #42workBench inbox
this is how workBench knows it's an inbox command
The child blocks are parameters, each starting with the name of a parameter followed by its value
Blocks that don't contain these parameters are ignored (So feel free to add extra blocks with info as way to document your inbox, since they are ignored by wB)
Child block parameters
Name:
inbox name that will appear in wB
Page:
(OPTIONAL) Page name for this inbox. Default is today's DNP
Text:
(OPTIONAL) finds block with Text on the page, and blocks are set to the children of this block. The first block to match the text will be used for this
Location:
(OPTIONAL) Defines if new blocks should be put at the top or bottom. Top is the default.
Valid parameters:
top
bottom
Blockref:
(OPTIONAL) leave a block ref when moving the selected blocks to the Inbox if true. Leave the block and send a block reference if reverse. Default is false.
Valid parameters:
false
true
reverse
Users:
(OPTIONAL) comma separated list of email address. This is the email address of the user for roam. If their email is in this list, they will see this Inbox action, otherwise note.
If the not used, then this inbox action is visible to all users
Examples:
Example 1: moves selected blocks to a page called "Project X" and moves blocks as children to the block that contains the text "Task List:" in the block on that page.
#42workBench Inbox
Name: Project X
Page: Project X
Text: Task List:
Location:
Example 2: No page name defined, so will move these blocks to top of DNP.
#42workBench Inbox
Name: Today's DNP
Example 3: No page name defined, so will move these blocks to DNP for today, as children of the block called "Inbox" and will place them at the bottom of the inbox
#42workBench Inbox
Name: Today's DNP
Text: Inbox
Location: bottom
Example 4: The same as example 3, but in a multiplayer graph will only work for users defined in the space delimited list of "users"
#42workBench Inbox
Name: Today's DNP
Text: Inbox
Location: bottom
workBench and SmartBlocks
SmartBlocks also appear in the workBench menu as an alternative way to run SmartBlocks. Additionally, if you add <%GLOBAL%> to a #42SmartBlock definition, it will appear in the workBench even if a block is not being edited. This is useful for running SmartBlocks that configure the work environment, but don't actually insert anything into the document.
Example use of <%GLOBAL%>
This SmartBlock opens the page "Project X Documentation" into the main document area. It closes all sidebar windows and opens in the sidebar two pages. Finally, it closes the left sidebar in the case it is open.
#42SmartBlock Project X workspace <%GLOBAL%>
<%OPENPAGE:Project X Documentation%>
<%SIDEBARWINDOWCLOSE:0%>
<%SIDEBARWINDOWOPEN:Project X Task List%>
<%SIDEBARWINDOWOPEN:Project X Project Timelines%>
<%SIDEBARSTATE:2%>
It is possible for the SmartBlock to write into the page using <%GOTOBLOCK%>. However, <%GOTOBLOCK%> may require an extra block or two after it, in order for it to insert properly into the page. So the following is similar to the previous example but will insert text at the bottom of the opened page:
#42SmartBlock Project X workspace <%GLOBAL%>
<%SIDEBARWINDOWCLOSE:0%>
<%SIDEBARWINDOWOPEN:Project X Task List%>
<%SIDEBARWINDOWOPEN:Project X Project Timelines%>
<%SIDEBARSTATE:2%>
<%OPENPAGE:Project X Documentation%><%GOTOBLOCK:-1%>
-- leave this block blank --
Insert this block at the bottom of the page
the next block after that
Search precedence
workBench is basically a search tool for accessing tools that are useful in Roam. As a user, you can create workBench commands and SmartBlocks, which will also appear in the workBench search. Your customizations are given priority in the search order. So results that match your search are returned in this order, using this precedence:
workBench Custom Commands
SmartBlocks defined by you the user
workBench built-in commands
SmartBlock built-in commands
Customizations
Some features in Roam42 can be configured by adding settings to your local graph database.
To use one of these settings, simply add them to a block in your graph, on any page. Then refresh your browser.
Customizing WorkBench
To enable/disables workBench Feature in Roam42
on: workBench is enabled (Default). Even if enabled, it needs to be turned on to be activated from the Roam42 Menu.
off: workBench is disabled
To customize the keyboard shortcut that triggers workBench.
See keyboard combinations at: Mousetrap - Keyboard shortcuts in Javascript (craig.is). You will need to experiment with a combination that works and doesn't conflict with other Roam or web browser features.
Examples keyboard shortcuts:
ctrl ctrl
ctrl+shift+p
CSS modification for workBench
The following CSS can be added to your roam/css page to override the theme used by workBench
Use this CSS to force LIGHT mode:
:root {
--wb-container-background: white;
--wb-container-tt-menu-background-color: white;
--wb-container-tt-highlight-background-color: WhiteSmoke;
--wb-container-tt-cursor-background-color: Gainsboro;
}
#roam42-wB-container .tt-input:focus,
#roam42-wB-path-container .tt-input:focus {
border-color: white !important;
background-color: white !important;
}
Use this CSS to force DARK mode:
:root {
--wb-container-background: #8899A6;
--wb-container-tt-menu-background-color: #8899A6;
--wb-container-tt-highlight-background-color: #B3B3B3;
--wb-container-tt-cursor-background-color: #E4E6EB;
}
.roam42-wb-path-image {
filter: invert(100%);
}
#roam42-wB-container .tt-input:focus,
#roam42-wB-path-container .tt-input:focus {
border-color: #E4E6EB !important;
background-color: #E4E6EB !important;
color: black !important;
}
Use Cases
Below are use cases and examples provided by RoamJS users (if any). They are provided to spark your creativity. These are not maintained nor tested by RoamJS.
We encourage you to join the Roam Slack Group Invite Link and ask you to share your use cases and example in the Roam42 channel.
==> Inboxes can be used instead of todo's or in addition to todo. Move or copy the task to the appropriate inbox for a complete list of all your todo's without any noise on the page. Some leave the block reference on the page in which it originated, other prefer not to - personal choice.
==> Inboxes can be set up however you like: as one inbox, separate boxes for each project, separate boxes for each priority (high, med, low, and someday -- for example).
==> If you move/copy the task to the appropriate inbox, then during your daily or weekly routine - you can choose which one to make TODO
with a Cmd + Return
for the next day, or any date you like.
Support
There is an active community at roamresearch.slack.com channels #roam42
and #roam-js
. Stop by if you need help or want to share your ideas.