1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// SPDX-FileCopyrightText: 2026 Slatian <baschdel@disroot.org>
//
// SPDX-License-Identifier: AGPL-3.0-or-later
//! # Migrating to lib-humus 0.6
//!
//! This guide assumes you are coming from version 0.5.
//!
//! Big changes:
//! * Which formats are available are no longer a decision of the application but a configuration of the templates themselves.
//! * Instead of all response formats the application now only specified the API format(s).
//! * Addition of the [LanguageEngine][crate::language::LanguageEngine].
//! * Migration from tera v1 to tera v2
//!
//! How to migrate:
//!
//! * If you used any crate features: delete them from the `Cargo.toml`, all feature flags have been removed. (getting the cookie header back is its own section below)
//! * Renaming:
//! * `TemplateEngineLoader` is now [`HumusEngineLoader`][crate::HumusEngineLoader]
//! * If you called your variables `templating_engine` and they now hold a humus engine you should rename them to say `humus_engine` instead to avoid confusion.i
//! * The humus engine now only needs one type argument called `ApiFormat`, you can use [templating::JsonOnlyApiFormat][crate::templating::JsonOnlyApiFormat] if you don't want to implement your own.
//! * Clean up old template settings:
//! * If you have used `initalize_template_context` [move it to the HumusView][crate::HumusView::initalize_template_context]
//! * You can delete your implementations of `HumusQuerySettings` and `HumusFormat` (the default implementation was `HtmlTextJsonFormat`), they are no longer needed.
//! * In case you want to keep your custom implementation: [HumusQuerySettings][crate::HumusQuerySettings] no longer takes a type argument.
//! * Changes to the [HumusView][crate::HumusView]:
//! * The second type argument now expects a [HumusApiFormat][crate::templating::HumusApiFormat] instead of a response format.
//! * `get_api_response` has been renamed to `into_api_response`.
//! * `update_response` now gets ownership of the response.
//! * `get_cookie_header` has been removed, see below.
//! * Update the templates directory:
//! * Add a [`templates.toml` templates manifest][crate::doc::templates_manifest] file to your templates directory and describe all template formats you support.
//! * Create a `tera2` directory inside your templates directory and move all existing templates there.
//! * Replace any use of the `mimetype` variable in your templates with `media_type`
//! * You can replace any custom middleware you've written for template settings with a [`TemplateSettingsLayer`][crate::middleware::TemplateSettingsLayer], make sure to update your settings extension queries to extract the [TemplateSetting][crate::middleware::TemplateSetting] type instead.
//! * In case you want to keep your own middleware still have a look at the [middlware module][crate::middleware] as it also exposes the helpers that are used to write the [TemplateSettingsLayer][crate::middleware::TemplateSettingsLayer].
//! * Migrate your templates to tera v2:
//! * Custom filters, functions and tests need to be registred **before** loading the templates: You can pass a prepopulated tera instance to the [HumusEngineLoader::new][crate::HumusEngineLoader::new] function. Use `Tera::new()` if you don't need any customizations.
//! * The templating got split up to one templating engine per format, files with the same extension as specified for the format get loaded automatically for that format, other files need to use the `additional_templates` key in the `templates.toml` template manifest.
//! * [Official Tera migration guide](https://github.com/Keats/tera/blob/master/MIGRATION.md)
//! * Main change is replacing macros with components. Watch out, because components don't have access to global variables, unlike macros!
//!
//! Changes to the barebones example you may also want to apply:
//! * The default listen address is now `[::1]:1234`, note the switch to IPv6!
//! * The `Arc` state was cloned at the start of every handler, this was unneccessary and has been removed.
//! * The `static_location` command line argument wasn't applied, this has now been fixed
//!
//! ## Cookie Header setting
//!
//! There is no dedicated call for setting cookie headers anymore, please set your cookie header in [HumusView::update_response][crate::HumusView::update_response] like you wouldd set any other header using [Response::headers_mut][axum::response::Response::headers_mut] with the `Set-Cookie` header name.
//!
//! This will introduce a fallible conversion from the cookie header string into a header value, this was there previously and would have resulted in the `Set-Cookie` header being silently dropped. For new code using `expect("cookie builder alwas builds valid Set-Cookie header values")` is recommended.
//!
//! ## Fixing the Error about a missing language engine
//!
//! This error should encourage building localizable web applications without any "but"s. Start with one language and expand as needed.
//!
//! At some point someone will be happy that most of the localization infrastructure is already in place and that they only have to write a `.flt` file to get another language working.
//!
//! Start with a [langauge manifest][crate::doc::language_manifest] and a matching empty `languages/{language_code}.flt` file and then replace the text in your templates with the [text functions][crate::doc::writing_templates#the-text-function] that reference entries in the language file.
//!