refactor: moved header setting and static content examples into own

directories This makes the basic example much cleaner and the second app tutorial easier to follow.
framesurge · Feb 3, 2022 · 0449fea · 0449fea
1 parent 59525b4
commit 0449fea
Show file tree

Hide file tree

Showing 22 changed files with 196 additions and 20 deletions.
diff --git a/examples/core/basic/README.md b/examples/core/basic/README.md
@@ -1,3 +1,5 @@
 # Basic Example
 
 This is a basic example of Perseus that shows the fundamentals of a slightly more advanced Perseus app. This is considered a core example because it not only contains end-to-end tests for Perseus itself, it's also the site of the development of the default Perseus engine. For that reason, the `.perseus/` directory is checked into Git here, and this is used as the single source of truth for the default engine. The rason for developing it here is to provide the context of an actual usage of Perseus, which makes a number of things easier. Then, some scripts bridge the gap to make the engine integrate into the CLI (you shouldn't have to worry about this when working in the Perseus repo as long as you're using the `bonnie dev example ...` script).
+
+Note that this example used to be more complex, illustrating features such as setting custom headers and hosting static content, though demonstrations of these have since been moved to independent examples.
diff --git a/examples/core/basic/src/lib.rs b/examples/core/basic/src/lib.rs
@@ -8,8 +8,5 @@ define_app! {
         crate::templates::index::get_template::<G>(),
         crate::templates::about::get_template::<G>()
     ],
-    error_pages: crate::error_pages::get_error_pages(),
-    static_aliases: {
-        "/test.txt" => "static/test.txt"
-    }
+    error_pages: crate::error_pages::get_error_pages()
 }
diff --git a/examples/core/basic/src/templates/index.rs b/examples/core/basic/src/templates/index.rs
@@ -1,7 +1,4 @@
-use perseus::{
-    http::header::{HeaderMap, HeaderName},
-    Html, RenderFnResultWithCause, SsrNode, Template,
-};
+use perseus::{Html, RenderFnResultWithCause, SsrNode, Template};
 use sycamore::prelude::{view, View};
 
 #[perseus::make_rx(IndexPageStateRx)]
@@ -22,7 +19,6 @@ pub fn get_template<G: Html>() -> Template<G> {
         .build_state_fn(get_build_state)
         .template(index_page)
         .head(head)
-        .set_headers_fn(set_headers)
 }
 
 #[perseus::head]
@@ -41,13 +37,3 @@ pub async fn get_build_state(
         greeting: "Hello World!".to_string(),
     })
 }
-
-#[perseus::autoserde(set_headers)]
-pub fn set_headers(props: Option<IndexPageState>) -> HeaderMap {
-    let mut map = HeaderMap::new();
-    map.insert(
-        HeaderName::from_lowercase(b"x-greeting").unwrap(),
-        props.unwrap().greeting.parse().unwrap(),
-    );
-    map
-}
diff --git a/examples/core/basic/static/test.txt b/examples/core/basic/static/test.txt
diff --git a/examples/core/set_headers/.gitignore b/examples/core/set_headers/.gitignore
@@ -0,0 +1 @@
+.perseus/
diff --git a/examples/core/set_headers/Cargo.toml b/examples/core/set_headers/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+name = "perseus-example-set-headers"
+version = "0.3.2"
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
+sycamore = "0.7"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
diff --git a/examples/core/set_headers/README.md b/examples/core/set_headers/README.md
@@ -0,0 +1,3 @@
+# Header Setting Example
+
+This examples shows how to set headers in Perseus based on your pages' states. This was originally part of the `basic` example, but it was refactored to be separate for clarity. Note that you'll need to use `perseus serve` to see the effects of custom headers.
diff --git a/examples/core/set_headers/index.html b/examples/core/set_headers/index.html
@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    </head>
+    <body>
+        <div id="root"></div>
+    </body>
+</html>
diff --git a/examples/core/set_headers/src/error_pages.rs b/examples/core/set_headers/src/error_pages.rs
@@ -0,0 +1,17 @@
+use perseus::{ErrorPages, Html};
+use sycamore::view;
+
+pub fn get_error_pages<G: Html>() -> ErrorPages<G> {
+    let mut error_pages = ErrorPages::new(|url, status, err, _| {
+        view! {
+            p { (format!("An error with HTTP code {} occurred at '{}': '{}'.", status, url, err)) }
+        }
+    });
+    error_pages.add_page(404, |_, _, _, _| {
+        view! {
+            p { "Page not found." }
+        }
+    });
+
+    error_pages
+}
diff --git a/examples/core/set_headers/src/lib.rs b/examples/core/set_headers/src/lib.rs
@@ -0,0 +1,10 @@
+mod error_pages;
+mod templates;
+
+use perseus::define_app;
+define_app! {
+    templates: [
+        crate::templates::index::get_template::<G>()
+    ],
+    error_pages: crate::error_pages::get_error_pages()
+}
diff --git a/examples/core/set_headers/src/templates/index.rs b/examples/core/set_headers/src/templates/index.rs
@@ -0,0 +1,51 @@
+use perseus::{
+    http::header::{HeaderMap, HeaderName},
+    Html, RenderFnResultWithCause, Template,
+};
+use sycamore::prelude::{view, SsrNode, View};
+
+#[perseus::make_rx(PageStateRx)]
+struct PageState {
+    greeting: String,
+}
+
+#[perseus::template_rx(IndexPage)]
+pub fn index_page(state: PageStateRx) -> View<G> {
+    view! {
+        p { (state.greeting.get()) }
+    }
+}
+
+#[perseus::head]
+pub fn head() -> View<SsrNode> {
+    view! {
+        title { "Index Page" }
+    }
+}
+
+pub fn get_template<G: Html>() -> Template<G> {
+    Template::new("index")
+        .template(index_page)
+        .head(head)
+        .build_state_fn(get_build_state)
+        .set_headers_fn(set_headers)
+}
+
+#[perseus::autoserde(build_state)]
+pub async fn get_build_state(_path: String, _locale: String) -> RenderFnResultWithCause<PageState> {
+    Ok(PageState {
+        greeting: "Hello World!".to_string(),
+    })
+}
+
+// For legacy reasons, this takes an `Option<T>`, but, if you're generating state, it will always be here
+// In v0.4.0, this will be updated to take just your page's state (if it has any)
+#[perseus::autoserde(set_headers)]
+pub fn set_headers(state: Option<PageState>) -> HeaderMap {
+    let mut map = HeaderMap::new();
+    map.insert(
+        HeaderName::from_lowercase(b"x-greeting").unwrap(),
+        state.unwrap().greeting.parse().unwrap(),
+    );
+    map
+}
diff --git a/examples/core/set_headers/src/templates/mod.rs b/examples/core/set_headers/src/templates/mod.rs
@@ -0,0 +1 @@
+pub mod index;
diff --git a/examples/core/static_content/.gitignore b/examples/core/static_content/.gitignore
@@ -0,0 +1 @@
+.perseus/
diff --git a/examples/core/static_content/Cargo.toml b/examples/core/static_content/Cargo.toml
@@ -0,0 +1,12 @@
+[package]
+name = "perseus-example-static-content"
+version = "0.3.2"
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+perseus = { path = "../../../packages/perseus", features = [ "hydrate" ] }
+sycamore = "0.7"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
diff --git a/examples/core/static_content/README.md b/examples/core/static_content/README.md
@@ -0,0 +1,3 @@
+# Static Content Example
+
+This example doesn't introduce any new code, it just shows how to host arbitrary static content with Perseus. By default, any content in the `static/` directory at the root of your project will be hosted at the URL `/.perseus/static/`, though you can also add aliases to content inside your project's root directory to be hsoted at any URL in your app. This example shows both methods, and you'll be able to find a file at `/test` and at `/.perseus/static/style.css` (named so as to indicate that you would typically put stylesheets in the `static/` directory).
diff --git a/examples/core/static_content/index.html b/examples/core/static_content/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <!-- This just includes the hosted stylesheet and uses it -->
+        <link rel="stylesheet" href=".perseus/static/style.css" />
+    </head>
+    <body>
+        <div id="root"></div>
+    </body>
+</html>
diff --git a/examples/core/static_content/src/error_pages.rs b/examples/core/static_content/src/error_pages.rs
@@ -0,0 +1,17 @@
+use perseus::{ErrorPages, Html};
+use sycamore::view;
+
+pub fn get_error_pages<G: Html>() -> ErrorPages<G> {
+    let mut error_pages = ErrorPages::new(|url, status, err, _| {
+        view! {
+            p { (format!("An error with HTTP code {} occurred at '{}': '{}'.", status, url, err)) }
+        }
+    });
+    error_pages.add_page(404, |_, _, _, _| {
+        view! {
+            p { "Page not found." }
+        }
+    });
+
+    error_pages
+}
diff --git a/examples/core/static_content/src/lib.rs b/examples/core/static_content/src/lib.rs
@@ -0,0 +1,17 @@
+mod error_pages;
+mod templates;
+
+use perseus::define_app;
+define_app! {
+    templates: [
+        crate::templates::index::get_template::<G>()
+    ],
+    error_pages: crate::error_pages::get_error_pages(),
+    // This sets up a map of URLs in your app to files in your project's directory
+    // For security reasons, you can't add files outside the current directory (though this *could* be circumvented, it should be avoided in general)
+    //
+    // Note that this is only needed for serving content at custom URLs in your app, anything in the `static/` filesystem directory will be served at the `/.perseus/static/` URL
+    static_aliases: {
+        "/test" => "test.txt"
+    }
+}
diff --git a/examples/core/static_content/src/templates/index.rs b/examples/core/static_content/src/templates/index.rs
@@ -0,0 +1,20 @@
+use perseus::{Html, Template};
+use sycamore::prelude::{view, SsrNode, View};
+
+#[perseus::template_rx(IndexPage)]
+pub fn index_page() -> View<G> {
+    view! {
+        p { "Hello World!" }
+    }
+}
+
+#[perseus::head]
+pub fn head() -> View<SsrNode> {
+    view! {
+        title { "Index Page" }
+    }
+}
+
+pub fn get_template<G: Html>() -> Template<G> {
+    Template::new("index").template(index_page).head(head)
+}
diff --git a/examples/core/static_content/src/templates/mod.rs b/examples/core/static_content/src/templates/mod.rs
@@ -0,0 +1 @@
+pub mod index;
diff --git a/examples/core/static_content/static/style.css b/examples/core/static_content/static/style.css
@@ -0,0 +1,3 @@
+* {
+    background-color: red;
+}
diff --git a/examples/core/static_content/test.txt b/examples/core/static_content/test.txt
@@ -0,0 +1 @@
+This is a test file!
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Header Setting Example

		This examples shows how to set headers in Perseus based on your pages' states. This was originally part of the `basic` example, but it was refactored to be separate for clarity. Note that you'll need to use `perseus serve` to see the effects of custom headers.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Static Content Example

		This example doesn't introduce any new code, it just shows how to host arbitrary static content with Perseus. By default, any content in the `static/` directory at the root of your project will be hosted at the URL `/.perseus/static/`, though you can also add aliases to content inside your project's root directory to be hsoted at any URL in your app. This example shows both methods, and you'll be able to find a file at `/test` and at `/.perseus/static/style.css` (named so as to indicate that you would typically put stylesheets in the `static/` directory).