Tutorial: 5-minute blog (2018 November)
Time commitment: about 2 mins per slide, times 30 slides.
This tutorial covers 80% of what there is to know about Hyperfiddle. The rest can be figured out as you go. @dustingetz in Slack with questions! Does this tutorial suck? @dustingetz with suggestions of how to make it good!
The simplest full app you can make in Hyperfiddle is a blog, which takes about 300 seconds. Half of that time is writing two Datomic queries with some minor schema modeling. The rest is fiddling around with Reagent renderers. Here is the final result. The equivalent as a proper Clojure project boilerplate involves git, compilers, build tools, setup Datomic, http web service, browser entrypoint, routing, client/server data sync, asynchronous http requests, node server rendering, deploy, etc. All stuff you simply don't have to think about anymore.
Below, we explode the hyperfiddle creation process, one thought at a time. Once you understand how the primitives compose together, you will be able to zip through this process in real-time.
Go to http://tank.hyperfiddle.net and make your first fiddle
Please namespace your fiddles with your username since the tank is a shared environment.
Click stage to redirect to new fiddle
Set :fiddle/type to :query
Pause to read the tooltip on :fiddle/type and :fiddle/query.
Change the :fiddle/query: add
:dustingetz.post/title to the where clause.
By convention, all schema attributes should be namespaced to the responsible maintainer.
This tutorial is coded against :dustingetz.post ontology (a related set of attributes), instead of making your own new attributes, because data is more interoperable if there are fewer ontologies shared by many datasets. The :dustingetz.post ontology has a reasonable amount of thought put into it and will have more investment over time.
Forms and tables are automatically driven by your query and Datomic schema
Specify the pull columns, these drive the table
Tip: To restore the default renderer, you can delete your :fiddle/renderer and then blur the field.
Tip: Auto-indent a codemirror with
Switch to EDN view to see the result directly, and then change the :fiddle/query to simplify the result shape
Tip: Auto-indent a codemirror with
Changing the result shape broke the custom :fiddle/renderer!
Switch to data view to ignore the :fiddle/renderer
Repair the renderer
:fiddle/cljs-ns lets us defn
Data view comes with builtin admin links (hypermedia controls)
Links in Hyperfiddle accomplish the same things that links on the web do. Like HTML, Hyperfiddle has three categories of links:
:hf/self link will take you to an admin UI for the entity named in the tooltip
To edit or link to an entity, you need to pull :db/id or :db/ident
Customise :hf/self at the :fiddle/links editor
Make it valid by affixing a new fiddle to the link
This anchor takes us to the new fiddle now
Here is the new fiddle, change :fiddle/type to :pull
The URL is wrong now because d/pull requires an argument
Go back to index with browser
Navigate again now that the link is fixed (fixme)
Set an explicit pull (in the empty entity case, this is used to render a blank form)
Toggle back to :view and render the post markdown
Press back button to go back to the blog index and wire up the links in the :fiddle/renderer
New blog post – the data view auto-links are sufficient here, don't need a custom view
Customize the new-blog-post form by overriding the link :hf/new
The link is backed by your new fiddle now, we need to drill down and specify the form
Alt-click any pink-box to drill down (navigate deeper in a new tab)
Specify the pull
Close the tab to go back, and try :hf/new again
Automatically add today's date to all new blog posts:
2. Name the txfn in a :link/txfn
Try it, make sure it works!
Transact the stage – all of our work is still in localstorage, nobody can see it until you transact
Production – edit your URL "hyperfiddle.net" to "hyperfiddle.com"
Prod is a progressive web app with server side rendering and a built-in CDN. All fiddles are URL addressable and compatible with server-side rendering to any initial state. Once React.js attaches to the page, Hyperfiddle will navigate client-side, render client-side and hydrate data like a single-page app. All client/server data-sync has a time-basis on the request and is served Cache-Control: Immutable. Server rendered page HTML responses do not have a time-basis so they are served Cache-Control: max-age=1, s-maxage=300. We set s-maxage to hack around thundering herds for now. There is more work to be done here. Further reading: reddit comment