Playground

We have an experimental visual space for interacting with your discourse graph, called the Playground. It's experimental because we aren't quite sure about the core use cases: if you use it and find it useful, we'd love to hear from you!

Basic layout and functions

Here is what the interface looks like (this is what shows up on any page that begins with the word "Playground" (e.g., in this example, we are on a page titled "Playground for data on COVID and children"):

You can toggle whether the playground is fullscreen by clicking on the maximize/minimize icon in the top right portion of the menubar.

You can pan (by click-dragging) and zoom (w/ mouse wheel) the canvas.

You can call up the Roam sidebar or query drawer (works best when playground is maximized). You can insert results into the canvas from the query drawer by ctrl+clicking on individual results or clicking on the "+" (insert results) button in the query drawer to bulk insert all results currently in view. Note: the query drawer keeps track of what's already on the canvas, so only results that aren't already on the canvas are displayed.

Node function modes

Dragging nodes to reposition them works as you might expect on any canvas.

Clicking on an empty space always creates a new node (depending on what node type is selected as active). The node picker allows you to control, in normal mode, what type of node you create when you create a new node.

There are a few additional "node function" modes that you can switch between to modify what's on the playground.

Edit: In this mode, you can edit the text of nodes and edges by clicking on nodes/edges, which will bring up an editing window where you can edit the text.

You can also activate this mode with the hotkey combination CMD+e (Mac) or CTRL+e (windows)

Connect: In this mode, you can draw edges between nodes. When this mode is activated, simply click on the node you want to be the source, then click on the node you want to be the target. You can then click on the label for the edge to select the relation you want.

You can also activate this mode with the hotkey combination CMD+c (Mac) or CTRL+c (windows)

Edit: In this mode, you can edit the text of nodes. Clicking on a node will bring up an editing window where you can edit the text.

You can also activate this mode with the hotkey combination CMD+e (Mac) or CTRL+e (windows)

Delete: In this mode, you can delete nodes by clicking on them. Note: there is a version of undo/redo (with the familiar shortcut of CMD/CTRL+z, but with a slight quirk that you need to multiple undo commands to undo a deletion (due to the Roam AlphaAPI and the way we are storing data).

You can also activate this mode with the hotkey combination CMD+d (Mac) or CTRL+d (windows)

Alias: In this mode, you can create aliases for nodes, handy if you have very long nodes that you want to see by a shorthand in this playground. Clicking on the node calls up the editing window where you can define an alias for a node. Remove an alias by deleting all text in the editing window.

You can also activate this mode with the hotkey combination CMD+a (Mac) or CTRL+a (windows)

Canvas functions

In the top right corner, there are a number of functions you can access for the canvas.

The filter allows you to filter what node or edge types to show on the canvas (they won't be removed when filtered out, just hidden).

The search function allows you to search for and jump to nodes on the canvas by text.

The minimap opens up a minimap on the bottom right that you can use to navigate a large canvas.

The overlay toggles whether nodes on the canvas have the Discourse context overlay on them.

Draw existing edges automatically draws any existing edges between nodes on the canvas.

Generate Roam blocks creates a page that contains the nodes on the canvas, in block formats that instantiate any existing relation patterns between nodes on the canvas. The page name will be of the form Auto generated from <playgroundPageName>

Export calls up an export dialog that you can use to export the nodes and edges currently on the canvas to csv/json/markdown.

Use cases

This is still in experimentation, but some possible use cases include:

• Early stage sensemaking: after creating a set of evidence and claim notes from reading, go to the Playground to make sense of how they relate to each other, by opening up the query drawer to call up these evidence/claim notes and inserting them into the canvas.

• Gathering items for export: use the query drawer to collect subsets of your discourse graph and then export for sharing.