Table of Contents

Overview

Demonstration(s)

How to Use

Customizations

Use Cases

Further Support

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

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.

Example 2: No page name defined, so will move these blocks to top of 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

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"

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.

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:

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.

Slack Invite Here