Integration with templating libraries

[AlterionX]

I was wondering if Percy is looking into integration and/or contribution to alternative templating libraries (such as maud).

[chinedufn]

One of Percy's main goals is to be compatible with other libraries - so absolutely!

Do you have anything specific in mind here - or are you just asking generally?

Cheers!

[AlterionX]

I'm still digging around for a frontend to use. I'm looking at percy, seed, and yew right now, but I haven't decided anything yet.

I already decided to write the static portions of my website with maud, since I liked the syntax more than Askama and horrowshow. Admittedly, I haven't looked into the inner workings of percy, so I wouldn't be able to suggest any major changes. I just figured that it would be nice if I could write the components with maud's macro and hook it into Percy's system somehow.

Once again, it might just be a pipe dream since I haven't looked too far into percy yet. CSS is sapping my life right now 🤣

[AlterionX]

One more note: I took a look at the full Readme instead of the book at this time, and everything makes a lot more sense now. Maybe I should change the issue title to "Please include the readme in the Percy book". Since, to me, it feels like the book's going over tangential (but important) things.

[chinedufn]

One way to combine them would be to use Maud to generate static HTML and then use that static HTML as the inner_html for an element that was created via Percy's html! macro

https://chinedufn.github.io/percy/html-macro/setting-inner-html/index.html

But yeah there might be other ways for them to play nicely together - would just depend on what you were trying to do

---

Ah yeah the book and the README both need some work.

If you don't mind - what about the README helped things click a bit better? I can try to copy those parts into the book!

Cheers!

[AlterionX]

Just replying to the second comment for now:

IMO, the quickstart section should be in the introduction (or the chapter immediately behind it) of the Percy book since it shows how you're supposed to use it and how the systems work together at a high level.

The Percy book itself feels more like a "html! and route macros with contribution guidelines" book rather than a "This is how you use Percy" book. While the html! macro needs introduction, I think it skews the viewpoint to only "how do I render with Percy" making it seem like it's just another templating library (but with behavior attached...somehow? This is also unclear.) It does state that there's not a fixed way to do things, which is fine, but I'm expecting an overview of the modules on one page that states their purpose from the start. *This last part is technically in the docs linked in the readme and the names are self-obvious, but it would have been nice to have an additional one-sentence summary of what each part is.

So basically, I would have a preferred an explanation of "how does Percy benefit me in the rest of my application" or "what are the parts of Percy" followed by "how do I use Percy's different parts". The first sentence: Percy is a modular toolkit for building isomorphic web apps with Rust + WebAssembly. is a very good statement of purpose, but we don't get more than that.

It would help if you either linked the Percy book after the initial example so that we would read the Readme, or made the introduction cover how to update the dom. The virtual-dom-rs is briefly mentioned (one or two sentences) but how to use it/a link to the docs is never made. Then the book rapidly makes its way away from the topic without explicitly stating how to make things work nicely.

That was an unexpected essay. 😓 Also sorry if it sounds abrasive. I love the work you guys are doing! I just find it a little frustrating to get into. Also I haven't done any actual development with Percy, so all my opinions should probably be taken with a grain of salt. 😄

[chinedufn]

This is AMAZING and very much appreciated since a good first experience is very important. I'm sorry that it was frustrating - but I'm glad that it led to such a thorough breakdown of what to improve next.

I'll spend some time on the docs and maybe ping you on a PR or 2!