book: add frameworks section

Author: Kijewski

book/src/SUMMARY.md

@@ -7,5 +7,6 @@
 - [Configuration](./configuration.md)
 - [Template syntax](./template_syntax.md)
 - [Filters](./filters.md)
+- [Web-frameworks](./frameworks.md)
 - [Performance](./performance.md)
 - [Upgrading](./upgrading.md)

book/src/frameworks.md

@@ -0,0 +1,224 @@
+# Working with web-frameworks
+
+Rinja's [`Template::render()`] returns <code>Result&lt;String, [rinja::Error]&gt;</code>.
+To make this result work in your preferred web-framework, you'll need to handle both cases:
+converting the `String` to a web-response with the correct `Content-Type`,
+and the `Error` case to a proper error message.
+
+While in many cases it will be enough to simply convert the `Error` to
+
+* `Box<dyn std::error::Error + Send + Sync>` using `err.into_box()` or
+* `std::io::Error` using `err.into_io_error()`
+
+it is **recommended** to use a custom error type.
+This way you can display the error message in your app's layout,
+and you are better prepared for the likely case that your app grows in the future.
+Maybe you'll need to access a database and handle errors?
+Maybe you'll add multiple languages and you want to localize error messages?
+
+The crates [`thiserror`] and [`displaydoc`] can be useful to implement this error type.
+
+[`Template::render()`]: <https://docs.rs/rinja/0.3.5/rinja/trait.Template.html#method.render>
+[rinja::Error]: <https://docs.rs/rinja/0.3.5/rinja/enum.Error.html>
+[`thiserror`]: <https://crates.io/crates/thiserror>
+[`displaydoc`]: <https://crates.io/crates/displaydoc>
+
+## Actix-Web
+
+To convert the `String` to an HTML response, you can use
+[`Html::new(_)`](https://docs.rs/actix-web/4.9.0/actix_web/web/struct.Html.html#method.new).
+
+```rust
+use actix_web::Responder;
+use actix_web::web::Html;
+
+fn handler() -> Result<impl Responder, AppError> {
+    …
+    Ok(Html::new(template.render()?))
+}
+```
+
+To implement your own error type, you can use this boilerplate code:
+
+```rust
+use actix_web::{HttpResponse, Responder};
+use actix_web::error::ResponseError;
+use actix_web::http::StatusCode;
+use actix_web::web::Html;
+use rinja::Template;
+
+#[derive(Debug, displaydoc::Display, thiserror::Error)]
+enum AppError {
+    /// could not render template
+    Render(#[from] rinja::Error),
+}
+
+impl ResponseError for AppError {
+    fn status_code(&self) -> StatusCode {
+        match &self {
+            AppError::Render(_) => StatusCode::INTERNAL_SERVER_ERROR,
+        }
+    }
+}
+
+impl Responder for AppError {
+    type Body = String;
+
+    fn respond_to(self, req: &HttpRequest) -> HttpResponse<Self::Body> {
+        #[derive(Debug, Template)]
+        #[template(path = "error.html")]
+        struct Tmpl { … }
+
+        let tmpl = Tmpl { … };
+        if let Ok(body) = tmpl.render() {
+            (Html::new(body), self.status_code()).respond_to(req)
+        } else {
+            (String::new(), self.status_code()).respond_to(req)
+        }
+    }
+}
+```
+
+## Axum
+
+To convert the `String` to an HTML response, you can use
+[`Html(_)`](https://docs.rs/axum/0.8.1/axum/response/struct.Html.html).
+
+```rust
+use axum::response::{Html, IntoResponse};
+
+async fn handler() -> Result<impl IntoResponse, AppError> {
+    …
+    Ok(Html(template.render()?))
+}
+```
+
+To implement your own error type, you can use this boilerplate code:
+
+```rust
+use axum::response::IntoResponse;
+use rinja::Template;
+
+#[derive(Debug, displaydoc::Display, thiserror::Error)]
+enum AppError {
+    /// could not render template
+    Render(#[from] rinja::Error),
+}
+
+impl IntoResponse for AppError {
+    fn into_response(self) -> Response {
+        #[derive(Debug, Template)]
+        #[template(path = "error.html")]
+        struct Tmpl { … }
+
+        let status = match &self {
+            AppError::Render(_) => StatusCode::INTERNAL_SERVER_ERROR,
+        };
+        let tmpl = Tmpl { … };
+        if let Ok(body) = tmpl.render() {
+            (status, Html(body)).into_response()
+        } else {
+            (status, "Something went wrong").into_response()
+        }
+    }
+}
+```
+
+## Rocket
+
+To convert the `String` to an HTML response, you can use
+[`RawHtml(_)`](https://docs.rs/rocket/latest/rocket/response/content/struct.RawHtml.html).
+
+```rust
+use rocket::get;
+use rocket::response::content::RawHtml;
+use rocket::response::Responder;
+
+#[get(…)]
+fn handler<'r>() -> Result<impl Responder<'r, 'static>, AppError> {
+    …
+    Ok(RawHtml(template.render()?))
+}
+```
+
+To implement your own error type, you can use this boilerplate code:
+
+```rust
+use rinja::Template;
+use rocket::http::Status;
+use rocket::response::content::RawHtml;
+use rocket::response::Responder;
+use rocket::{Request, Response};
+
+#[derive(Debug, displaydoc::Display, thiserror::Error)]
+enum AppError {
+    /// could not render template
+    Render(#[from] rinja::Error),
+}
+
+impl<'r> Responder<'r, 'static> for AppError {
+    fn respond_to(
+        self,
+        request: &'r Request<'_>,
+    ) -> Result<Response<'static>, Status> {
+        #[derive(Debug, Template)]
+        #[template(path = "error.html")]
+        struct Tmpl { … }
+
+        let status = match &self {
+            AppError::Render(_) => Status::InternalServerError,
+        };
+        let template = Tmpl { … };
+        if let Ok(body) = template.render() {
+            (status, RawHtml(body)).respond_to(request)
+        } else {
+            (status, "internal server error").respond_to(request)
+        }
+    }
+}
+```
+
+## Warp
+
+To convert the `String` to an HTML response, you can use
+[`html(_)`](https://docs.rs/warp/0.3.7/warp/reply/fn.html.html).
+
+```rust
+use warp::reply::{Reply, html};
+
+fn handler() -> Result<impl Reply, AppError> {
+    …
+    Ok(html(template.render()?))
+}
+```
+
+To implement your own error type, you can use this boilerplate code:
+
+```rust
+use http::StatusCode;
+use warp::reply::{Reply, Response, html};
+
+#[derive(Debug, displaydoc::Display, thiserror::Error)]
+enum AppError {
+    /// could not render template
+    Render(#[from] rinja::Error),
+}
+
+impl Reply for AppError {
+    fn into_response(self) -> Response {
+        #[derive(Debug, Template)]
+        #[template(path = "error.html")]
+        struct Tmpl { … }
+
+        let status = match &self {
+            AppError::Render(_) => StatusCode::INTERNAL_SERVER_ERROR,
+        };
+        let template = Tmpl { … };
+        if let Ok(body) = template.render() {
+            with_status(html(body), status).into_response()
+        } else {
+            status.into_response()
+        }
+    }
+}
+```