README.adoc

: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:

[source]

./scripts/dev-electron cd shells/electron npm install npx electron .

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:

[source]

./script/build-electron cd shells/electron npm run pack

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:

[source,clojure]

{: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}}}

:edn-query-language.core/query [: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:

[source,html]

and try it].

=== 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:

[source,clojure]

(.postMessage window #js {:event "pathom-viz-embed" :payload (pr-str message)} "*")

Here is a complete example putting all together:

[source,html]

----

=== 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.