feat(templates): ✨ added context to templates if they're beeing rendered on the server or client

Closes #26.

Author: arctic-hen7

docs/0.2.x/src/templates/intro.md

@@ -47,3 +47,13 @@ One niche case is defining a route like this: `/<locale>/about`. In this case, t
 It's perfectly possible in Perseus to define one template for `/post` (and its children) and a different one for `/post/new`. In fact, this is exactly what [the showcase example](https://github.com/arctic-hen7/perseus/tree/main/examples/showcase) does, and you can check it out for inspiration. This is based on a simple idea: **more specific templates win** the routing contest.
 
 There is one use-case though that requires a bit more fiddling: having a different template for the root path. A very common use-case for this would be having one template for `/posts`'s children (one URl for each blog post) and a different template for `/posts` itself that lists all available posts. Currently, the only way to do this is to define a property on the `posts` template that will be `true` if you're rendering for that root, and then to conditionally render the list of posts. Otherwise, you would render the given post content. This does require a lot of `Option<T>`s, but they could be safely unwrapped (data passing in Perseus is logical and safe).
+
+## Checking Render Context
+
+It's often necessary to make sure you're only running some logic on the client-side, particularly anything to do with `web_sys`, which will `panic!` if used on the server. Because Perseus renders your templates in both environments, you'll need to explicitly check if you want to do something only on the client (like get an authentication token from a cookie). This can be done trivially with the `is_client!` macro, which does exactly what it says on the tin. Here's an example from [here](https://github.com/arctic-hen7/perseus/blob/main/examples/basic/src/templates/about.rs):
+
+```rust,no_run,no_playground
+{{#include ../../../../examples/basic/src/templates/about.rs}}
+```
+
+This is a very contrived example, but what you should note if you try this is the flash from `server` to `client`, because the page is pre-rendered on the server and then hydrated on the client. This is an important principle of Perseus, and you should be aware of this potential flashing (easily solved by a less contrived example).

docs/next/src/templates/intro.md

@@ -47,3 +47,13 @@ One niche case is defining a route like this: `/<locale>/about`. In this case, t
 It's perfectly possible in Perseus to define one template for `/post` (and its children) and a different one for `/post/new`. In fact, this is exactly what [the showcase example](https://github.com/arctic-hen7/perseus/tree/main/examples/showcase) does, and you can check it out for inspiration. This is based on a simple idea: **more specific templates win** the routing contest.
 
 There is one use-case though that requires a bit more fiddling: having a different template for the root path. A very common use-case for this would be having one template for `/posts`'s children (one URl for each blog post) and a different template for `/posts` itself that lists all available posts. Currently, the only way to do this is to define a property on the `posts` template that will be `true` if you're rendering for that root, and then to conditionally render the list of posts. Otherwise, you would render the given post content. This does require a lot of `Option<T>`s, but they could be safely unwrapped (data passing in Perseus is logical and safe).
+
+## Checking Render Context
+
+It's often necessary to make sure you're only running some logic on the client-side, particularly anything to do with `web_sys`, which will `panic!` if used on the server. Because Perseus renders your templates in both environments, you'll need to explicitly check if you want to do something only on the client (like get an authentication token from a cookie). This can be done trivially with the `is_client!` macro, which does exactly what it says on the tin. Here's an example from [here](https://github.com/arctic-hen7/perseus/blob/main/examples/basic/src/templates/about.rs):
+
+```rust,no_run,no_playground
+{{#include ../../../../examples/basic/src/templates/about.rs}}
+```
+
+This is a very contrived example, but what you should note if you try this is the flash from `server` to `client`, because the page is pre-rendered on the server and then hydrated on the client. This is an important principle of Perseus, and you should be aware of this potential flashing (easily solved by a less contrived example).

examples/basic/src/templates/about.rs

@@ -1,11 +1,23 @@
-use perseus::Template;
+use perseus::{is_client, Template};
 use std::rc::Rc;
 use sycamore::prelude::{component, template, GenericNode, Template as SycamoreTemplate};
 
 #[component(AboutPage<G>)]
 pub fn about_page() -> SycamoreTemplate<G> {
     template! {
         p { "About." }
+        p {
+            (
+                format!(
+                    "This is currently being run on the {}.",
+                    if is_client!() {
+                        "client"
+                    } else {
+                        "server"
+                    }
+                )
+            )
+        }
     }
 }
 

packages/perseus/src/build.rs

@@ -67,7 +67,11 @@ pub async fn build_template(
                 .await?;
             // Prerender the template using that state
             let prerendered = sycamore::render_to_string(|| {
-                template.render_for_template(Some(initial_state.clone()), Rc::clone(&translator))
+                template.render_for_template(
+                    Some(initial_state.clone()),
+                    Rc::clone(&translator),
+                    true,
+                )
             });
             // Write that prerendered HTML to a static file
             config_manager
@@ -104,7 +108,7 @@ pub async fn build_template(
         // It's safe to add a property to the render options here because `.is_basic()` will only return true if path generation is not being used (or anything else)
         if template.is_basic() {
             let prerendered = sycamore::render_to_string(|| {
-                template.render_for_template(None, Rc::clone(&translator))
+                template.render_for_template(None, Rc::clone(&translator), true)
             });
             let head_str = template.render_head_str(None, Rc::clone(&translator));
             // Write that prerendered HTML to a static file

packages/perseus/src/serve.rs

@@ -69,7 +69,7 @@ async fn render_request_state(
     let state = Some(template.get_request_state(path.to_string(), req).await?);
     // Use that to render the static HTML
     let html = sycamore::render_to_string(|| {
-        template.render_for_template(state.clone(), Rc::clone(&translator))
+        template.render_for_template(state.clone(), Rc::clone(&translator), true)
     });
     let head = template.render_head_str(state.clone(), Rc::clone(&translator));
 
@@ -142,7 +142,7 @@ async fn revalidate(
             .await?,
     );
     let html = sycamore::render_to_string(|| {
-        template.render_for_template(state.clone(), Rc::clone(&translator))
+        template.render_for_template(state.clone(), Rc::clone(&translator), true)
     });
     let head = template.render_head_str(state.clone(), Rc::clone(&translator));
     // Handle revalidation, we need to parse any given time strings into datetimes
@@ -254,7 +254,7 @@ pub async fn get_page_for_template(
                     // We need to generate and cache this page for future usage
                     let state = Some(template.get_build_state(path.to_string()).await?);
                     let html_val = sycamore::render_to_string(|| {
-                        template.render_for_template(state.clone(), Rc::clone(&translator))
+                        template.render_for_template(state.clone(), Rc::clone(&translator), true)
                     });
                     let head_val = template.render_head_str(state.clone(), Rc::clone(&translator));
                     // Handle revalidation, we need to parse any given time strings into datetimes

packages/perseus/src/shell.rs

@@ -259,7 +259,7 @@ pub async fn app_shell(
             // BUG (Sycamore): this will double-render if the component is just text (no nodes)
             sycamore::hydrate_to(
                 // This function provides translator context as needed
-                || template.render_for_template(state, Rc::clone(&translator)),
+                || template.render_for_template(state, Rc::clone(&translator), false),
                 &container_rx_elem,
             );
             checkpoint("page_interactive");
@@ -341,6 +341,7 @@ pub async fn app_shell(
                                         template.render_for_template(
                                             page_data.state,
                                             Rc::clone(&translator),
+                                            false,
                                         )
                                     },
                                     &container_rx_elem,

packages/perseus/src/template.rs

@@ -13,6 +13,14 @@ use std::rc::Rc;
 use sycamore::context::{ContextProvider, ContextProviderProps};
 use sycamore::prelude::{template, GenericNode, Template as SycamoreTemplate};
 
+/// Used to encapsulate whether or not a template is running on the client or server. We use a `struct` so as not to interfere with
+/// any user-set context.
+#[derive(Clone, Debug)]
+pub struct RenderCtx {
+    /// Whether or not we're being executed on the server-side.
+    pub is_server: bool,
+}
+
 /// Represents all the different states that can be generated for a single template, allowing amalgamation logic to be run with the knowledge
 /// of what did what (rather than blindly working on a vector).
 #[derive(Default)]
@@ -209,12 +217,22 @@ impl<G: GenericNode> Template<G> {
         &self,
         props: Option<String>,
         translator: Rc<Translator>,
+        is_server: bool,
     ) -> SycamoreTemplate<G> {
         template! {
             // We provide the translator through context, which avoids having to define a separate variable for every translation due to Sycamore's `template!` macro taking ownership with `move` closures
             ContextProvider(ContextProviderProps {
                 value: Rc::clone(&translator),
-                children: || (self.template)(props)
+                children: || template! {
+                    // We then provide whether this is being rendered on the client or the server as a context element
+                    // This allows easy specification of client-side-only logic without having to worry about `web_sys` panicking
+                    ContextProvider(ContextProviderProps {
+                        value: RenderCtx {
+                            is_server
+                        },
+                        children: || (self.template)(props)
+                    })
+                }
             })
         }
     }
@@ -473,5 +491,14 @@ macro_rules! get_templates_map {
     };
 }
 
+/// Checks in a template if the code is being run on client-side or the server-side. This uses Sycamore context, and so will only work
+/// in a reactive scope.
+#[macro_export]
+macro_rules! is_client {
+    () => {
+        !::sycamore::context::use_context::<::perseus::template::RenderCtx>().is_server;
+    };
+}
+
 /// A type alias for a `HashMap` of `Template`s.
 pub type TemplateMap<G> = HashMap<String, Template<G>>;