:source-highlighter: coderay :source-language: clojure :imagesdir: docs/images :toc: :toc-placement: preamble :sectlinks: :sectanchors: :sectnums:
= Pathom Viz
Pathom viz is a set of visualization tools to support the development and inspection of Graph API's built with the https://github.com/wilkerlucio/pathom[Pathom] library.
== Standalone App
The standalone app is the easiest way to use Pathom Viz.
=== Download the app
A download of binaries is available at the link:https://github.com/wilkerlucio/pathom-viz/releases[releases page].
Note: On Linux, you may receive the error message libappindicator3-1 but it is not installable when installing Pathom viz. To rectify:
wget http://ftp.us.debian.org/debian/pool/main/libi/libindicator/libindicator3-7_0.5.0-4_amd64.deb
wget http://ftp.us.debian.org/debian/pool/main/liba/libappindicator/libappindicator3-1_0.4.92-7_amd64.deb
sudo apt install ./libindicator3-7_0.5.0-4_amd64.deb
sudo apt install ./libappindicator3-1_0.4.92-7_amd64.deb=== Building the app
If you want to develop the app:
If you want to run locally with prod performance, do the same replacing
./scripts/dev-electron with ./scripts/build-electron.
=== Creating Electron app
To package the app, do the following:
The builds will be available at the dist directory.
== Embed
Pathom Viz Embed is an effortless way to include Pathom components in any web-based interface.
This is similar to what a Youtube or Vimeo embed works. You put an iframe and send some data to it.
The base URL for the embed is https://pathom-viz.wsscode.com/embed.html.
The interface to communicate is a configuration map, here is a configuration example to open the planner explorer:
{:pathom.viz.embed/component-name :pathom.viz.embed.component/planner-explorer
:pathom.viz.embed/component-props {:com.wsscode.pathom3.connect.indexes/index-oir {:a {{} #{a}} :b {{:g {}} #{b}} :c {{} #{c}} :e {{} #{e e1}} :f {{:e {}} #{f}} :g {{:c {} :f {}} #{g}} :h {{:a {} :b {}} #{h}}}
To send this data to the embed, there are two ways.
=== Data via Query Params
You can encode using URL Encoding and send via msg query param, for example:
=== Data via postMessage
The URL data is convenient, but it is also limited in the size of the message. Each browser may have different higher limits. Pathom data can get quite large, and those limits are not enough in many cases.
To provide an alternative without such limitations, Pathom Viz also accepts data using the link:https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage[window messaging].
To use this, you must wait for the frame to load and use window.postMessage using
the following format:
Here is a complete example putting all together:
=== Available Components
At this moment, for public usage, only the Planner Explorer is available. More components will come soon. Keep an eye on the issues to track their development.
== Usage docs
Find usage docs at https://roamresearch.com/#/app/wsscode/page/RG9C93Sip.
== Support
Get support at #pathom channel in Clojurians Slack.