Going from interpreted to compiled heist

Question

I don't seem to be able to grasp the compiled heist concept. There are no examples on the net whatsoever. How would I go about changing simple code snippets from interpreted to compiled.

For instance:

listUsersH :: AppHandler ()
listUsersH = do
  users <- liftIO $ getColList "users"
  let userListS = mapSplices userLinkS users
  heistLocal (bindSplice "users" userListS) $ render "list-users"
  where
    userLinkS d = runChildrenWithText [("user",T.pack $ at "uname" d)]

How would I do the simple combination of "runChildren", "mapSplices", "bindSplice" and "render" with compiled heist?

I understand that the concept is different and there is no "heistLocal" .. But I need to go back now and re-learn how to do the basic things like displaying a bunch of records in a "for each" loop manner. Can someone clarify this and show a simple example like the one above but with compiled heist?

At the moment I dont even know how to do simple variable substitution with compiled heist. For instance, this:

simpleString = "Insert me..."
insertString = heistLocal (bindSplices spl) $ render "tst"
where
  spl = [("var", textSplice simpleString)]

Please, someone help me with the basics or point me to a location with some minimal examples. I did read the snap web site docs.

Answer 1

Compiled splices are definitely more difficult to work with. For one, all splices must be statically bound up front. This requires a pretty significant shift in mindset. Before, using heistLocal you could view splices as things with a limited scope that could be bound whenever needed. You could make decisions in handlers using the information in the request and then bind splices accordingly. You can still do similar things with compiled splices, but it requires an inversion of control. Now you have to do that kind of dynamic request-based decision making inside the splice (which is a monad transformer around your handler monad, so you still have access to handler functions).

I recommend thinking of compiled splices as global resources that you are making available to your web designers that they can use on any page however they see fit. Viewing splices in this way has a couple advantages. First, it makes them more orthogonal and composable than with specialized splices bound with heistLocal. Second, it makes debugging easier, because you never have to worry about whether the splice has been bound or not.

But the biggest difficulty of compiled splices is caused by the split between load time and runtime and what that means for splice functions. We talk about this a little in the last section of our wiki page about migrating to Heist 0.10. We also have a longer discussion of the "why" behind this.

We're also still working on improving the API for compiled Heist. We're very close to finishing Heist 0.13 which significantly simplifies the API and should help to make things more understandable. The code currently in the new-api branch on github is pretty close to being ready for release.