From 2956009bdcd36efa86a37f736fb3affa0d189981 Mon Sep 17 00:00:00 2001 From: arctic_hen7 Date: Fri, 21 Jan 2022 17:37:55 +1100 Subject: [PATCH] refactor: renamed `template_with_rx_state` to `template2` In v0.4.0, it will superseded `#[template]` entirely. --- examples/rx_state/src/about.rs | 3 +-- examples/rx_state/src/index.rs | 2 +- packages/perseus-macro/src/lib.rs | 14 +++++++++++++- packages/perseus/src/lib.rs | 2 +- packages/perseus/src/template.rs | 3 +-- 5 files changed, 17 insertions(+), 7 deletions(-) diff --git a/examples/rx_state/src/about.rs b/examples/rx_state/src/about.rs index 0f4b90e67a..b0bb897356 100644 --- a/examples/rx_state/src/about.rs +++ b/examples/rx_state/src/about.rs @@ -3,8 +3,7 @@ use perseus::{get_render_ctx, Html, Template}; use sycamore::prelude::{view, Signal}; use sycamore::view::View; -// This template doesn't have any properties, so there's no point in using the special `template_with_rx_state` macro (but we could) -#[perseus::template_with_rx_state(component = "AboutPage")] +#[perseus::template2(component = "AboutPage")] pub fn about_page() -> View { // Get the page state store manually // The index page is just an empty string diff --git a/examples/rx_state/src/index.rs b/examples/rx_state/src/index.rs index f7397d2c4f..1691bf90f4 100644 --- a/examples/rx_state/src/index.rs +++ b/examples/rx_state/src/index.rs @@ -13,7 +13,7 @@ pub struct IndexProps { // This special macro (normally we'd use `template(IndexProps)`) converts the state we generate elsewhere to a reactive version // We need to tell it the name of the unreactive properties we created to start with (unfortunately the compiler isn't smart enough to figure that out yet) // This will also add our reactive properties to the global state store, and, if they're already there, it'll use the existing one -#[perseus::template_with_rx_state( +#[perseus::template2( component = "IndexPage", unrx_props = "IndexProps", global_state = "AppState" diff --git a/packages/perseus-macro/src/lib.rs b/packages/perseus-macro/src/lib.rs index e5bcfc485b..127870c000 100644 --- a/packages/perseus-macro/src/lib.rs +++ b/packages/perseus-macro/src/lib.rs @@ -79,8 +79,20 @@ pub fn template(args: TokenStream, input: TokenStream) -> TokenStream { /// Additionally, this macro will add the reactive state to the global state store, and will fetch it from there, allowing template state to persists between page changes. Additionally, /// that state can be accessed by other templates if necessary. // TODO Rename this to `template2` and rewrite docs on it with examples +/// The new version of `#[template]` designed for reactive state. This can interface automatically with global state, and will automatically provide Sycamore `#[component]` annotations. To +/// use this, you'll need to provide your component's name (e.g. `IndexPage`) as `#[template2(component_name = )`. +/// +/// The first argument your template function can take is state generated for it (e.g. by the *build state* strategy). If you use this, you'll need to provide the key `unrx_props` as well to this +/// macro. The argument your template function takes should be the reactive version of your state `struct` (generated with `#[make_rx]` usually), and then you can tell us the name of unreactive +/// version with `unrx_props = `. +/// +/// The second argument your template function can take is a global state generated with the `GlobalStateCreator`. If you provide this, with its type being the reactive version, you'll need to +/// provide the key `global_state = ` being the unreactive version. +/// +/// **Warning:** this macro is currently exempt from semantic versioning, and breaking changes may be introduced here at any time! If you want stability, use the `#[template]` macro (but you won't +/// get access to Perseus' reactive state platform). #[proc_macro_attribute] -pub fn template_with_rx_state(args: TokenStream, input: TokenStream) -> TokenStream { +pub fn template2(args: TokenStream, input: TokenStream) -> TokenStream { let parsed = syn::parse_macro_input!(input as template2::TemplateFn); let attr_args = syn::parse_macro_input!(args as syn::AttributeArgs); // Parse macro arguments with `darling` diff --git a/packages/perseus/src/lib.rs b/packages/perseus/src/lib.rs index 855ceeed4d..ce438c6aeb 100644 --- a/packages/perseus/src/lib.rs +++ b/packages/perseus/src/lib.rs @@ -72,7 +72,7 @@ pub use http::Request as HttpRequest; pub use wasm_bindgen_futures::spawn_local; /// All HTTP requests use empty bodies for simplicity of passing them around. They'll never need payloads (value in path requested). pub type Request = HttpRequest<()>; -pub use perseus_macro::{autoserde, head, make_rx, template, template_with_rx_state, test}; +pub use perseus_macro::{autoserde, head, make_rx, template, template2, test}; pub use sycamore::{generic_node::Html, DomNode, HydrateNode, SsrNode}; pub use sycamore_router::{navigate, Route}; diff --git a/packages/perseus/src/template.rs b/packages/perseus/src/template.rs index b84809f919..1f002daad6 100644 --- a/packages/perseus/src/template.rs +++ b/packages/perseus/src/template.rs @@ -19,8 +19,7 @@ use std::sync::Arc; use sycamore::context::{ContextProvider, ContextProviderProps}; use sycamore::prelude::{view, View}; -/// The properties that every page will be initialized with. You shouldn't ever need to interact with this unless you decide not to use `#[perseus::template(...)]` or -/// `#[perseus::template_with_rx_state(...)]`. +/// The properties that every page will be initialized with. You shouldn't ever need to interact with this unless you decide not to use the template macros. #[derive(Clone)] pub struct PageProps { /// The path it's rendering at.