Snap: compiled splices code example

Question

I think I did asked a similar question some time ago but it was not answered due to unstable API. So I was waiting for the 0.13 to pass by. I am not sure if it is correct to bring up a similar question...?

What is the alternative to interpreted runChildrenWith(Text) and mapSplices in the compiled splices world? (this combination seems to be the most common) I would really appreciate some code examples if possible.

If I understand correctly, we get together all the application splices and then add them to the heistInit. Can anyone show how to do it please?

Does the splice binding tag has to be unique across the whole application?

Is there a completed snap project utilising new APIs and compiled splices so that I could read and see learn?

Thank you.

-- UPDATE --

Great answer below. But some parts (the ones with lenses) got me even more confused, unfortunately. If I understand correctly this is the simple way to splice a string:

mySplice = "testSplice" ## testSplice
  where testSplice = return $ C.yieldRuntimeText $ do
          return "text to be spliced"

If i need to run the spliced string several times, say in 5 table raws i would do it like this:

mySplices = C.manyWithSplices C.runChildren mySplice

Is this correct?

I get bunch of errors trying to add the splices in heist config.

addConfig h $ mempty
 {
   hcCompiledSplices = "mySplice" ## mySplice -- or mySplices
 }

Where am I going wrong? Sorry for being slow.

All I need really ( just for now so I can understand) is to splice and display a simple string that I receive from database.

-- UPDATE 2 --

Thanks to the extremle helpfull Daniel`s answer I can finally get something working.

So far I get both variants of code working.

The first one, thanks to Daniel

stringSplice :: Monad n => C.Splice n
stringSplice = C.manyWithSplices C.runChildren splicefuncs (return ["aa","bb","cc"])
  where
    splicefuncs = "string" ## (C.pureSplice . C.textSplice $ id)

And the secod

testSplice :: C.Splice (Handler App App)
testSplice = return $ C.yieldRuntimeText $ return "text to be spliced"

Where

(C.pureSplice . C.textSplice $ id)

produces similar results to

return $ C.yieldRuntimeText $ return "text to be spliced"

Is there difference between the above? Any cases that one would prefer one to another? They seem to produce the same results.

There is a "deferMany" function in the compiled splices lib that, according to the docs, produces similar results to the mapSplices in interpreted lib. Can we use it instead of "C.manyWithSplices C.runChildren" combination??

@r Compiled splices are unintuitive at first, because they require an inversion of control: you must tell the splice how to find the required runtime data. I took me a while to get the hang of them. I think they have become somewhat easier to use in the latest versions of heist. — danidiaz, Oct 24 '13 at 19:06
@r I think `C.yieldRuntimeText` and `C.deferMany` are enough when you don't care about the contents of the tag you want to splice: you just want to completely replace the tag with a generated string. `withSplices` and `manyWithSplices` can be used when you want to render (one,many) complex structures that have fields, and you do care about the contents of the spliced tag because they define the "view" for the structure. `withSplices` and `manyWithSplices` let you establish a correspondence between the top-level splice and the subsplices that render individual fields. — danidiaz, Oct 25 '13 at 13:04
@r And that's why `C.withSplices` and `C.manyWithSplices` are so often used in conjuction with `C.runWithChildren`. It's basically like saying "use the contents of the tag as the view for the structure we want to render". — danidiaz, Oct 25 '13 at 13:07
@Daniel Thanks once again. I'll try to figure out the rest and open another question if get stuck. — r.sendecky, Oct 25 '13 at 13:41

danidiaz · Accepted Answer · 2013-10-24T19:00:47.387

Let's say you want to display information about a list of persons using compiled splices (assume that we start from the scaffolding generated by snap init.)

A very simple _persons.tpl template with dummy values would be something like

<body>
    <person>
        <div>
            <h1><name>dummy name</name></h1>
            <p><age>77</age></p> 
            <p><location>jauja</location></p> 
        </div>
    </person>
</body>

Where person, name, age, and location are the tags to be spliced.

We define a trivial Snaplet that holds the info

data Foo = Foo
    {
        _persons :: [Person]
    }

makeLenses ''Foo

data Person = Person
    {
        _name :: Text
    ,   _age :: Int
    ,   _location :: Text
    }   

makeLenses ''Person

and we add it to the App record:

data App = App
    { _heist :: Snaplet (Heist App)
    , _sess :: Snaplet SessionManager
    , _auth :: Snaplet (AuthManager App)
    , _foo :: Snaplet Foo
    }

we add the following to the app initializer

f <- nestSnaplet "foo" foo $ makeSnaplet "foo" "Foo Snaplet" Nothing $ return $ Foo $ 
        [ Person "Ricardo" 33 "Los Cantones" 
        , Person "Luis" 38 "Montealto" 
        ]

...

return $ App h s a f

This function constructs a Handler that returns the list of persons (using view from Control.Lens):

personH :: SnapletLens b Foo -> Handler b b [Person] 
personH l = withTop l $ view persons <$> get

This function constructs the appropiate compiled splice from a RuntimeSplice that produces a list of Persons. RuntimeSplices represent information that can only be known at run time, as opposed to load time:

personSplice :: Monad n => RuntimeSplice n [Person] -> C.Splice n
personSplice = C.manyWithSplices C.runChildren splicefuncs 
    where
    splicefuncs = mconcat  
        [ "name" ## (C.pureSplice . C.textSplice $ view name)
        , "age" ## (C.pureSplice . C.textSplice $ T.pack . show . view age)
        , "location" ## (C.pureSplice . C.textSplice $ view location)
        ]

And this function can be used to register the splice in the global Heist configuration. Notice that we lift the Handler into a RuntimeSplice:

addPersonSplices :: HasHeist b => Snaplet (Heist b) -> 
                                  SnapletLens b Foo -> 
                                  Initializer b v ()
addPersonSplices h l = addConfig h $ mempty 
   {
      hcCompiledSplices = "person" ## (personSplice . lift $ personH l) 
   }

Be sure to add this line to the app initializer:

addPersonSplices h foo

And to add the following pair to the app's routes:

("/persons",  cRender "_persons")

If you now run the server, navigating to http://127.0.0.1:8000/persons should show the list.

UPDATE

For the simpler case (no complex records, no lenses) in which you only want to show a list of strings.

The template could be something like:

<body>
    <strings>
        <p><string>dummy value</string></p>
    </strings>
</body>

The top-level splice would be:

stringSplice :: Monad n => C.Splice n
stringSplice = C.manyWithSplices C.runChildren splicefuncs (return ["aa","bb","cc"])
    where
    splicefuncs = "string" ## (C.pureSplice . C.textSplice $ id)

This means "when we encounter the tag associated to this splice, perform an action that produces a list of strings, and for each string, render the contents of the tag, substituting the current string for the string tag".

Notice that the signature of manyWithSplices forces the stuff to the right of the (##) to have type RuntimeSplice n Text -> Splice n. Here id has type Text -> Text. C.TextSplice transforms it into something of type Text -> Builder, and C.pureSplice performs the final transformation into a RuntimeSplice n Text -> Splice n.

In place of (return ["aa","bb","cc"]) you could provide a more complex action that connected a database and extracted the strings form there.

A function to register this splice would be:

addStringSplices :: HasHeist b => Snaplet (Heist b) -> Initializer b v ()
addStringSplices h = addConfig h $ mempty 
    {
          hcCompiledSplices = "strings" ## stringSplice
    }

Thanks Daniel for the updated answer. This finally starting to make sense. I can build up more complex exersizes on top of the simple ones you provided in your update. I have a coupl of more follow up questions above. Sorry about the long line of questioning ) but you seem to be my only source of knowledge on this and I want to get as much while I can. Thanks. — r.sendecky, Oct 25 '13 at 06:54
Great answer. My only comment would be that the snaplet stuff is not related to the question about compiled Heist. As your example shows, it *can* but, but it doesn't have to be. You don't have to understand snaplets to understand compiled Heist. Your update helps make that clear, but I just thought I would emphasize the point. — mightybyte, Oct 26 '13 at 15:28

Snap: compiled splices code example

1 Answers1

Linked