Add axum example by translating the actix-web example

Author: Kijewski

.github/workflows/rust.yml

@@ -26,7 +26,9 @@ jobs:
       - run: |
           set -eu
           for PKG in \
-            examples/actix-web-app fuzzing rinja rinja_derive rinja_derive_standalone rinja_parser testing testing-alloc testing-no-std
+            examples/actix-web-app examples/axum-app \
+            fuzzing rinja rinja_derive rinja_derive_standalone rinja_parser \
+            testing testing-alloc testing-no-std
           do
             cd "$PKG"
             echo "Testing: $PKG"
@@ -154,8 +156,9 @@ jobs:
     strategy:
       matrix:
         package: [
-          examples/actix-web-app, fuzzing, rinja, rinja_derive, rinja_derive_standalone,
-          rinja_parser, testing, testing-alloc, testing-no-std,
+          examples/actix-web-app, examples/axum-app, fuzzing,
+          rinja, rinja_derive, rinja_derive_standalone, rinja_parser,
+          testing, testing-alloc, testing-no-std,
         ]
     runs-on: ubuntu-latest
     steps:

examples/axum-app/.rustfmt.toml

@@ -0,0 +1 @@
+../../.rustfmt.toml

examples/axum-app/Cargo.toml

@@ -0,0 +1,33 @@
+
+[package]
+name = "axum-app"
+version = "0.3.5"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+publish = false
+
+# This is an example application that uses both rinja as template engine,
+# and axum as your web-framework.
+[dependencies]
+axum = "0.8.1"
+rinja = { version = "0.3.5", path = "../../rinja" }
+tokio = { version = "1.43.0", features = ["macros", "rt-multi-thread"] }
+
+# serde and strum are used to parse (deserialize) and generate (serialize) information
+# between web requests, e.g. to share the selected display language.
+serde = { version = "1.0.217", features = ["derive"] }
+strum = { version = "0.26.3", features = ["derive"] }
+
+# These depenendies are simply used for a better user experience, having access logs in the
+# console, and error messages if anything goes wrong, e.g. if the port is already in use.
+displaydoc = "0.2.5"
+pretty-error-debug = "0.3.1"
+thiserror = "2.0.11"
+tower-http = { version = "0.6.2", features = ["trace"] }
+tracing = "0.1.41"
+tracing-subscriber = "0.3.19"
+
+# In a real application you would not need this section. It is only used in here, so that this
+# example can have a more lenient MSRV (minimum supported rust version) than rinja as a whole.
+[workspace]
+members = ["."]

examples/axum-app/LICENSE-APACHE

@@ -0,0 +1 @@
+../../LICENSE-APACHE

examples/axum-app/LICENSE-MIT

@@ -0,0 +1 @@
+../../LICENSE-MIT

examples/axum-app/README.md

@@ -0,0 +1,17 @@
+# rinja + axum example web app
+
+This is a simple web application that uses rinja as template engine, and
+[axum](https://crates.io/crates/axum) as web framework.
+It lets the user of the web page select a display language, and asks for their name.
+The example shows the interaction between both projects, and serves as an example to use
+basic rinja features such as base templates to a unified layout skeleton for your page,
+and less boilerplate in your template code.
+
+To run the example execute `cargo run` in this folder.
+Once the project is running, open <http://127.0.0.1:8080/> in your browser.
+To gracefully shut does the server, type ctrl+C in your terminal.
+
+The files of the project contain comments for you to read.
+The recommended reading order is "templates/_layout.html", "templates/index.html",
+"Cargo.toml", "src/main.rs". Also please have a look at our [book](https://rinja.readthedocs.io/),
+which explains rinja's features in greater detail.

examples/axum-app/_typos.toml

@@ -0,0 +1 @@
+../../_typos.toml

examples/axum-app/deny.toml

@@ -0,0 +1 @@
+../../deny.toml

examples/axum-app/src/main.rs

@@ -0,0 +1,173 @@
+use axum::extract::{Path, Query};
+use axum::http::StatusCode;
+use axum::response::{Html, IntoResponse, Redirect, Response};
+use axum::routing::get;
+use axum::{Router, serve};
+use rinja::Template;
+use serde::Deserialize;
+use tower_http::trace::TraceLayer;
+use tracing::{Level, info};
+
+#[tokio::main]
+async fn main() -> Result<(), Error> {
+    tracing_subscriber::fmt()
+        .with_max_level(Level::DEBUG)
+        .init();
+
+    let app = Router::new()
+        .route("/", get(start_handler))
+        .route("/{lang}/index.html", get(index_handler))
+        .route("/{lang}/greet-me.html", get(greeting_handler))
+        .fallback(|| async { AppError::NotFound })
+        .layer(TraceLayer::new_for_http());
+
+    // In a real application you would most likely read the configuration from a config file.
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:8000")
+        .await
+        .map_err(Error::Bind)?;
+
+    if let Ok(addr) = listener.local_addr() {
+        info!("Listening on http://{addr}/");
+    }
+    serve(listener, app).await.map_err(Error::Run)
+}
+
+#[derive(displaydoc::Display, pretty_error_debug::Debug, thiserror::Error)]
+enum Error {
+    /// could not bind socket
+    Bind(#[source] std::io::Error),
+    /// could not run server
+    Run(#[source] std::io::Error),
+}
+
+/// Using this type your user can select the display language of your page.
+///
+/// The same type is used by axum as part of the URL, and in rinja to select what content to show,
+/// and also as an HTML attribute in `<html lang=`. To make it possible to use the same type for
+/// three different use cases, we use a few derive macros:
+///
+///  * `Default` to have a default/fallback language.
+///  * `Debug` is not strictly needed, but it might aid debugging.
+///  * `Clone` + `Copy` so that we can pass the language by value.
+///  * `PartialEq` so that we can use the type in comparisons with `==` or `!=`.
+///  * `serde::Deserialize` so that axum can parse the type in incoming URLs.
+///  * `strum::Display` so that rinja can write the value in templates.
+#[derive(Default, Debug, Clone, Copy, PartialEq, Deserialize, strum::Display)]
+#[allow(non_camel_case_types)]
+enum Lang {
+    #[default]
+    en,
+    de,
+    fr,
+}
+
+/// This enum contains any error that could occur while handling an incoming request.
+///
+/// In a real application you would most likely have multiple error sources, e.g. database errors,
+#[derive(Debug, displaydoc::Display, thiserror::Error)]
+enum AppError {
+    /// not found
+    NotFound,
+    /// could not render template
+    Render(#[from] rinja::Error),
+}
+
+/// This is your error handler
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        // It uses a rinja template to display its content.
+        // The member `lang` is used by "_layout.html" which "error.html" extends. Even though it
+        // is always the fallback language English in here, "_layout.html" expects to be able to
+        // access this field, so you have to provide it.
+        #[derive(Debug, Template)]
+        #[template(path = "error.html")]
+        struct Tmpl {
+            lang: Lang,
+            err: AppError,
+        }
+
+        let status = match &self {
+            AppError::NotFound => StatusCode::NOT_FOUND,
+            AppError::Render(_) => StatusCode::INTERNAL_SERVER_ERROR,
+        };
+        let tmpl = Tmpl {
+            lang: Lang::default(),
+            err: self,
+        };
+        if let Ok(body) = tmpl.render() {
+            (status, Html(body)).into_response()
+        } else {
+            (status, "Something went wrong").into_response()
+        }
+    }
+}
+
+/// The is first page your user hits does not contain language information, so we redirect them
+/// to a URL that does contain the default language.
+async fn start_handler() -> Redirect {
+    Redirect::temporary("/en/index.html")
+}
+
+/// This type collects the query parameter `?name=` (if present)
+#[derive(Debug, Deserialize)]
+struct IndexHandlerQuery {
+    #[serde(default)]
+    name: String,
+}
+
+/// This is the first localized page your user sees.
+///
+/// It has arguments in the path that need to be parsable using `serde::Deserialize`; see `Lang`
+/// for an explanation. And also query parameters (anything after `?` in the incoming URL).
+async fn index_handler(
+    Path((lang,)): Path<(Lang,)>,
+    Query(query): Query<IndexHandlerQuery>,
+) -> Result<Response, AppError> {
+    // In the template we both use `{% match lang %}` and `{% if lang !=`, the former to select the
+    // text of a specific language, e.g. in the `<title>`; and the latter to display references to
+    // all other available languages except the currently selected one.
+    // The field `name` will contain the value of the query parameter of the same name.
+    // In `IndexHandlerQuery` we annotated the field with `#[serde(default)]`, so if the value is
+    // absent, an empty string is selected by default, which is visible to the user an empty
+    // `<input type="text" />` element.
+    #[derive(Debug, Template)]
+    #[template(path = "index.html")]
+    struct Tmpl {
+        lang: Lang,
+        name: String,
+    }
+
+    let template = Tmpl {
+        lang,
+        name: query.name,
+    };
+    Ok(Html(template.render()?).into_response())
+}
+
+#[derive(Debug, Deserialize)]
+struct GreetingHandlerQuery {
+    name: String,
+}
+
+/// This is the final page of this example application.
+///
+/// Like `index_handler` it contains a language in the URL, and a query parameter to read the user's
+/// provided name. In here, the query argument `name` has no default value, so axum will show
+/// an error message if absent.
+async fn greeting_handler(
+    Path((lang,)): Path<(Lang,)>,
+    Query(query): Query<GreetingHandlerQuery>,
+) -> Result<Response, AppError> {
+    #[derive(Debug, Template)]
+    #[template(path = "greet.html")]
+    struct Tmpl {
+        lang: Lang,
+        name: String,
+    }
+
+    let template = Tmpl {
+        lang,
+        name: query.name,
+    };
+    Ok(Html(template.render()?).into_response())
+}

examples/axum-app/templates/_layout.css

@@ -0,0 +1,56 @@
+{#-
+    This file is included by "_layout.html".
+    You can still use template syntax (such as this comment) in here.
+-#}
+
+html {
+    background-color: #eee;
+    color: #111;
+    font-size: 62.5%;
+    min-height: 100vh;
+    color-scheme: light;
+}
+* {
+    line-height: 1.2em;
+}
+body {
+    background-color: #fff;
+    font-size: 1.8rem;
+    max-width: 40em;
+    margin: 1em auto;
+    padding: 2em;
+}
+h1 { font-size: 2.4rem; }
+h2 { font-size: 2.2rem; }
+h3 { font-size: 2.0rem; }
+a:link, a:visited {
+    color: #36c;
+    text-decoration: none;
+}
+a:active, a:hover, a:focus {
+    text-decoration: underline;
+    text-underline-offset: 0.3em;
+}
+#lang-select {
+    font-size: 80%;
+    width: max-content;
+    margin: 2em 0 0 auto;
+    display: flex;
+    flex-direction: row;
+    flex-wrap: wrap;
+}
+#lang-select li {
+    flex-grow: 1;
+    flex-basis: auto;
+    margin: .25em 0 0 0;
+    padding: 0 1em;
+    text-align: center;
+    list-style-type: none;
+    border-left: 0.1rem solid currentColor;
+}
+#lang-select li:first-of-type {
+    border-left: 0 none transparent;
+}
+#lang-select li:last-of-type {
+    padding-right: 0;
+}

examples/axum-app/templates/_layout.html

@@ -0,0 +1,67 @@
+{#-
+    This is the basic layout of our example application.
+    It is the core skeleton shared between all pages.
+    It expects the struct of any template that `{% extends %}` this layout to contain
+    (at least) a field `lang: Lang`, so it can be used in the `<html lang=` attribute.
+-#}
+
+<!DOCTYPE html>
+<html lang="{{lang}}">
+    <head>
+        <meta charset="UTF-8" />
+        {#-
+            A base template can contain `blocks`, which my be overridden templates that use
+            this base template. A block may contain a default content, if the extending
+            template does want to / need to override the content of a block.
+
+            E.g. maybe you would like to have "Rinja example application" as default title for
+            your pages, then simply add this text (without quotation marks) in the block!
+
+            The default content can be as complex as you need it to be.
+            E.g. it may contain any nodes like `{% if … %}`, and even other blocks.
+        ~#}
+        <title>{% block title %}{% endblock %}</title>
+
+        <meta http-equiv="expires" content="Sat, 01 Dec 2001 00:00:00 GMT" />
+        <meta http-equiv="cache-control" content="no-cache, no-store, must-revalidate" />
+        <meta http-equiv="pragma" content="no-cache" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="robots" content="noindex, nofollow" />
+
+        {#-
+            In a real application you most likely would want to link style sheets,
+            any JavaScripts etc. using e.g. `actix-files`, instead of embedding the content
+            in your generated HTML.
+
+            As you can see, this comment starts with `-`, which will tells the comment
+            to strip all white spaces before it, until it finds the first non-white space
+            character, a `>`.
+
+            The comment is also terminated with `~`. This also strips white spaces, but
+            will leave one space, or a newline character, if the stripped content contained
+            a newline.
+        ~#}
+        <style>
+        /*<![CDATA[*/
+            {%~ include "_layout.css" ~%}
+        /*]]>*/
+        </style>
+    </head>
+    <body>
+        {%~ block content %}{% endblock ~%}
+    </body>
+</html>
+
+{%- macro lang_select(page, query="") -%}
+    <ul id="lang-select">
+        {%- if lang != Lang::en -%}
+            <li><a href="/en/{{ page }}.html{{ query }}">This page in English</a></li>
+        {%- endif -%}
+        {%- if lang != Lang::de -%}
+            <li><a href="/de/{{ page }}.html{{ query }}">Diese Seite auf deutsch.</a></li>
+        {%- endif -%}
+        {%- if lang != Lang::fr -%}
+            <li><a href="/fr/{{ page }}.html{{ query }}">Cette page est en français.</a></li>
+        {%- endif -%}
+    </ul>
+{%- endmacro lang_select -%}