WORKBENCH

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

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 its selected in the list of wB commands, press enter for Roam42 to perform that command.

workBench includes a number of included 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 are 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 exists:
        • 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
  • 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 is how workBench knows its 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. Default is false.

Valid parameters:

false

true

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

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:

  1. workBench Custom Commands
  2. SmartBlocks - defined by you the user
  3. workBench - built-in commands
  4. SmartBlock - bulit-inCommands

Configuring the workBench

These settings should be saved in your graph database in a block. (Remove the ` back tick from front and end of setting). Also a browser refresh is required for them to take effect

  • #42Setting workBenchEnabled on
    • Enables workBench feature in Roam42
    • Values:
      • 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
  • #42Setting workBenchShortcut ctrl ctrl
    • The shortcut that triggers workBench can be set to a custom keyboard shortcut. 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

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:

```css
  :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;
    }```