Implicit documentation for the new API

[svilupp]

trafficstars

First of all, thank you for the awesome package.

I've spent a bunch of time debugging some of the Stipple.jl demos. I've read through the recent PRs and issues and through that I've learned a lot about the new API and how to debug it (a bit). I thought the references might be helpful for others. There are also a few questions that I had because I still don't have a good mental model for how Stipple works (at the bottom of my post).

Helpful References:

• On the new Reactive API
• On updating model values, isready handler/init procedure, @recur
• On customizing object to @recur over with Stipple.render, eg, DataFrames.jl
• When the client side seems not to be updating
• When the client side seems blank/empty or sliders keep disappearing
• On variable scopes when inside of @handlers/@app and errors when using @out/@in outside of @handlers blocks

Some of my observations:

• Be careful whether you use @app begin or @app XYZModel begin to define your model! The former initializes on its own (esp. handlers) and you can set up your app with a simple @page("/", "ui.jl"), however, the latter seems to require being more explicit in your model initialization, eg, route("/") do; model = XYZModel |> init |> handlers; ... end
• A quick&dirty way to debug if you set up your app properly: Check the following constants if they are initialized (ie, your model is fully reflected in REACTIVE_STORAGE, your handler is prepared in HANDLERS, etc):

Stipple.ReactiveTools.REACTIVE_STORAGE[Main]
Stipple.ReactiveTools.HANDLERS[Main] # if elements are not loaded up/sliders disappear, this is likely empty!
Stipple.ReactiveTools.TYPES[Main]
# Change Main for the name of the module in which your Stipple App runs

You can wipe these variables with @clear (when playing with different versions and requiring a clean start. First, shut your current server down with down()!)

My questions:

• Is there a good mental model for what Stipple.jl does? Eg, through the lens of initialization (and client vs server), what are the sub-steps of the initialization routine? (I've also read your ebook but I still feel like a good mental model escapes me)
• What are REACTIVE_STORAGE vs TYPES? Why does @page macro require a model and context? Etc.
• model=@init does not always generate handlers (eg, following the first example in here, but changing to @app Inverter begin instead of @appname Inverter meant that model=@init did not work for me... It worked fine when I did it manually: model = Inverter |> init |> handlers)
• It's not clear to me WHY / WHEN I would use @vars or @appname, or, in general, an explicit model? Are there some specific use cases where I need the name reference (and @app would be insufficient)?
• Is there a difference to Genie.isrunning(:webserver) || up() vs Server.isrunning() || Server.up() ?

[essenciary]

@svilupp thanks for these - quite a few good questions. We'll work to document the API in the next few weeks and we'll keep an eye on the issues you raised. Let's keep this open and review after the new docs release.