Legacy – Hyperfiddle overview Q2 2018

Quick high level overview

Warning, this page is saved for historical purposes but the information is outdated and none of the demos work.

A simple fiddle

Fiddles have a Datomic query which fetch data from their database. This example query is a Datomic "pull", which fetches a single record. This fiddle's view here is automatic – it is data-driven from Datomic schema, which captures exactly the right information necessary to do this.
  • Try uncommenting :reg/birthdate and re-ordering the attributes.
  • Note the widgets are aware of the Datomic type, which is shown in the label tooltip.
  • Click $ to see the Datomic schema which defines the type. In Datomic, "$" is the default database's name.

Progressive enhancement

The default fiddle view uses markdown, because good software is self-documenting, so inline documentation should be easy.
  • The !field directive is for customizing forms. The argument in brackets, e.g. str, is the value renderer, a ClojureScript function.
  • Try changing str to pr-str on each field, especially :reg/birthdate
  • If you want to clear your changes and start over, clear the staging area – the yellow button in toolbar.

ClojureScript

Fiddles have a :fiddle/renderer, a Reagent expression for the fiddle. The renderer can render the markdown, or ignore it. The markdown is just really convenient.
  • #_ is a structural comment. Try uncommenting lines 5 and 6.
  • All fiddles get a default renderer, and some default markdown.
  • To revert something to the default, clear it.

Queries and Links

  • Fiddles compose recursively
  • Fiddles have links to other fiddles (a graph, like the world wide web)
  • Three types of link: anchor, button, embed (like HTML anchor, form, iframe)
  • Hyperfiddle provides default links for basic CRUD structure. The below links are automatic.
  • Links encode parameters into URLs
  • Hover a link to see any parameters in a tooltip.
  • Middle-click the edit anchor to go there in a new tab.
  • All fiddles are URL addressable, including embeds. To drill into an embed, alt-click the pink box.

Select options

Selects are the third type of link: embeds. We've added a new attribute: :reg/shirt-size, and a link to the options query.
  • :link/rel :options is a semantic hint for the view (like HTML rels). If you were to clear the link/rel (which you can't due to the issue), the select would go away.
  • :link/path "0 :reg/shirt-size" positions the link in the right place
  • Use the !browse directive to render an embed like an iframe: !browse(:options :body 0 :reg/shirt-size).

Next up:

  • Dynamic dependencies
  • Database transactions
  • Users, accounts and security
  • Foreign integrations
  • Fiddle Graph and I/O Runtime

Dynamic dependencies

Warning, this page is under development
See how the shirt-sizes respond to choice of gender.
The position of the fiddle indicates any data dependencies. :reg/shirt-size options depend on the form data, so they are in the data column, instead of the label column. This is a consequence of the Hyperfiddle default renderers, which respect all the semantic hints. Your renderers can do whatever. Your renderers can also be circumvented inside the developer view by toggling to "data" mode, which is especially useful when your renderers have bugs.
:link/formula is a little CLJC expression that indicates the data dependencies, for example (comp :reg/gender deref :hypercrud.browser/data :hypercrud.browser/parent) indicates a dependency on the gender value. This is passed to the link's target fiddle via the URL/route. All fiddles are URL addressable, even the embedded ones (like HTML <iframe>).
Alt-click the below shirt-size fiddle to navigate directly to it, observe the gender parameter in the URL, then toggle the gender by editing the url, then use the back button to come back here.
The link tooltips show the dependencies as well, try hovering "edit". edit, new and remove are "auto-links" – Hyperfiddle provides a sensible default structure for CRUD operations, this is so there is a useful admin dashboard out of the box. You can add and subtract links to sculpt the app into what you need.
Try adding a new shirt-size. You will need to understand the query to do this. Try changing line 5 to [?e :reg/gender :gender/male]

Embed true triage

The options fiddle is embedded because [:link/render-inline? true]. This is a hint to the Hyperfiddle I/O Runtime that it should probably dataload these fiddles together. Note that, like optimizing compilers, this is a hint not a contract: the I/O runtime may do something clever! The fiddle graph captures API inter-dependencies as data, so data sync reduces to a graph partitioning problem and can optimize dynamically in ways that hand-coded I/O cannot. Remember that Datomic is an immutable log and captures information about what changed when, which the optimzer can make use of. So as a simple example, the I/O runtime may load select options separately from the rest of the page, for better cache granularity. The fiddle graph is decoupled from transport, so the I/O runtime can even mix-and-match transport strategies (e.g. websocket for faster stuff, http for cachable stuff). The possibilities are endless. Today, the I/O runtime is simple, so you must set the hints.

Triage

On Wed, Jun 6, 2018 at 6:53 PM Brian Hurlow wrote:
Do the “data components” in hyperfiddle declare their own data dependencies? Does the rendering of nested/composed components merge the data needs of each component into a nested graph? I remember Om next sort of trying this. Ideally each component in our app would declare it’s data needs and render could recursively merge those into pull expression that meets full page requirement.
On Wed, Jun 6, 2018 at 7:20 PM Dustin Getz wrote:
Hi Brian, Yeah, that's right, dynamic data dependencies (queries that depend on queries) is the problem Hyperfiddle set out to solve. Om can't do dynamic dependencies, only static pulls. I dont know how much hyperfiddle you know but I tried to capture this in a screenshot as best as I could. Shirt-size :options query is dependent on gender. The shirt-size :options link is flagged dependent=true, and has a formula, which is a oneliner to slide and dice the query result and plumb the gender as an input to the shirt size query. Normally that would be a client/server round trip, but Hyperfiddle stores this information in the database (including the formula) and it all evaluates on the server inside the datomic peer.
If you whack the rel=:options (semantic renderer) it looks like this (the select options are cosmetic)
The colored bars and the position are meant to visually convey the data dependencies, it's not the most intuitive right now. Gender is in the label column because it doesn't have dependencies. Shirt size is in the value column because it does. It's all yellow because all the data came out of the same database.