improving example

[gurugeek]

liquid-rust version: rust version: rustc 1.24.0 OS: Mac OSX

First of all thanks for porting this template engine to rust! I managed to get it working in the web framework I am using but...the example given doesn't tell me a) how to pass variables to the template b) where to store the templates c) doesn't give any example of fetching data from a database and displaying it in the html template

I might be missing something but...for web apps I think that these type of examples are crucial vs just calculations?!

[Txuritan]

The example does show passing over a variable:

let template = liquid::ParserBuilder::with_liquid()
    .build()
    .parse("Liquid! {{num | minus: 2}}").unwrap(); // The variable 'num' - 2

globals.insert("num".to_owned(), liquid::Value::scalar(4f32)); // The variable 'num'

As for template storage have a look at the parse_file.rs in tests. Link for the future

And for database access, thats out of the scope for a templating engine, but in short make a call to whatever database you're conencted to for some data and pass it as variables to liquid.

[epage]

Sorry, I've not been focusing too much on the documentation at this time. Instead most of the work has been driven by what cobalt needs as I focus on getting that into a reasonable state. I'm also not coming at it from your perspective, so I have a blind spot for the needs in documentation and functionality.

In the mean time, feel free to reach out to us on gitter if you have questions. As you figure things out, that'd be a great time to create a PR to improve the documentation! Its much harder with the curse of knowledge to know where documentation is lacking.

Besides improving the docs, some of the ideas in #95 might be useful to you like changing it so globals aren't moved into the renderer but instead are hidden behind a trait and a reference is passed to the renderer. This could make it so you can more lazily load data from a database (see also #118). My main interest is cleaning up the architecture and and speeding up cobalt but that is a lower priority at the moment compared to getting the basic features of cobalt implemented.

[gurugeek]

@Txuritan thanks again for clarifying the example. Still I don't understand...where are the templates stored ? Why not build a simple example like https://crates.io/crates/dtl (too bad this crate is not working) I could certainly help once I figure this out. And why use a numeric operation for a template that is supposed to show content (static or otherwise) ?

[gurugeek]

@epage thanks a lot for your reply. I am thankful for your reply and I appreciate that documentation is not always a priority. This said I would be glad to help out (or sponsor if needed) some straightforward examples meant for web developers! but once again thanks for the reply and considering this improvement.

[epage]

where are the templates stored

If you are referring to top-level templates, that is up to the caller. The caller is expected to load the template and pass it to the parse function.

If you are talking about template snippets you might include, you need to call ParserBuilder::include_source with an implementation of the Include trait. liquid comes with a FilesysteInclude or you can write your own. I'm slowly switching cobalt away from loading snippets directly from the filesystem and instead preloading them into a hash map.