SMARTBLOCKS STORE

Table of Contents


Overview

The SmartBlocks Store is a place where users could publish and install SmartBlocks workflow to and from the rest of the Roam community directly from within Roam! To access the store, hit CMD+P on mac or CTRL+P on windows to open to Roam Command Palette, and search for "Open SmartBlocks Store". Click on the result and the store should appear on the left!

The store will list all the SmartBlocks that are available. Click on one to head to the smart block's details page. From the details page, you could install the SmartBlock directly to your graph and will be taken to the bullet where it is stored. Any SmartBlock in the store that is already installed in your graph will be disabled from visiting or installing again.

Publishing

You could share SmartBlock workflows with the rest of the Roam Community by publishing to the store!

To publish a given workflow, you will first need to generate a publishing token. This token prevents others from publishing workflows with your graph name and prevents others from updating workflows you publish. You could generate a token from within the publish tab in the roam/js/smartblocks page.

Once you have a token generated, you can now publish any workflow from your graph. To begin, click on the SmartBlock icon that appears next to the #SmartBlock tag and click "Publish Workflow".

Once the workflow has published successfully, it will add a block reference to it to the roam/js/smartblocks page.

To edit the metadata of your workflow, copy the block reference to the workflow and paste it anywhere in your graph. Nested under the block reference, create a block for each field you want to configure. Add the value(s) of that field as a child block of the field.

The following metadata fields are supported:

  • Description - The description of the workflow, shown in the store after a user clicks on it

  • Image - The thumbnail shown to users associated with your workflow

  • Tags - Any tags you would like to add to your workflow to make it more easily searchable

  • Price - The price you want to sell your workflow to the community, defaulted at 0

If you publish a workflow with custom JavaScript, the workflow will be flagged as under review. The RoamJS team will review workflows with custom JavaScript as these could be dangerous for users to install in their graphs. Once approved, the workflow will be live in the store.

If you specify a price for your SmartBlock workflow, the extension will first verify whether you've connected your graph to Stripe. You will need to do so before selling SmartBlocks in the store so that we know where to send the sales to. Connect your graph to Stripe on the roam/js/smartblocks page:

Once connected, you will be able to sell SmartBlocks simply by publishing your workflow. The fee breakdown is as follows:

  • $0.30 + 3% go to Stripe

  • 5% go to RoamJS

So, for a single $10 SmartBlock workflow purchase:

  • $0.60 will go to Stripe

  • $0.50 will go to RoamJS

  • $8.90 will go to the SmartBlock Publisher

Connecting to Stripe will also allow you to accept donations on free workflows you publish. No extra step necessary - simply publish your workflow to the store and it will appear with an input for users to input donation amounts.

To update the workflow itself or any of its metadata, simply click the SmartBlock icon again to publish. If you decide to change the name of the workflow, note that when your users install the workflow it will create a second instance of the workflow since it will be under a new name. Be sure to notify your users of a name change if you choose to do so.

Installing

The SmartBlocks Store lists three tabs:

  • Marketplace - This is where you could browse all of the available SmartBlock workflows

  • Installed - These are the Smart Block workflows that you have installed from the store to your graph

  • Published - These are the Smart Block workflows that you have published to the store

Click on a workflow to be taken to its specific page. From there you could install the workflow to your graph. If the workflow is free, it will be installed immediately. If it's a paid workflow, you will need to enter your card information first before the workflow is installed into your graph. Once successfully installed, you will be taken straight to page in your graph where your SmartBlock was installed, which should be under the workflows subtree in the roam/js/smartblocks page.

If you navigate to a SmartBlock page that you have already installed, there may be an update available. Clicking on the Update button will update your SmartBlock workflow, overwriting what exists. If you'd like to save the old version elsewhere, store it as a new name before updating. If you update a SmartBlock workflow and the author changed its name, it will download as a second copy on your graph. Be sure to delete the old version if you no longer want the old copy.

Important Note: Versioning was implemented on August 26th, 2021. This means that if you installed a SmartBlock before this date, it will be available for install and purchase again. DO NOT BUY THE SAME SMARTBLOCK TWICE. Once you buy a SmartBlock workflow, you have access to all future updates. If you bought or installed a SmartBlock workflow before this date and are not seeing in the installed tab of the store, please reach out to support@roamjs.com and we could manually insert the record for you with proof of purchase.

Demo

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.