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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
//! Breadcrumb engine — walks the page tree once and returns an
//! ordered list of `(title, url, is_current)` crumbs.
//!
//! Powers both public templates (via [`to_context_value`]) and
//! the admin chrome (admin handlers can call [`resolve_breadcrumbs`]
//! directly and stuff the result into Tera context). The shared
//! `_breadcrumbs.html` macro in [`crate::admin::register_templates`]
//! renders the standard `<nav aria-label="Breadcrumb">` shape plus a
//! parallel JSON-LD `BreadcrumbList` block for SEO.
//!
//! ## Public-side example
//!
//! ```text
//! {# In a Tera template: #}
//! {% set crumbs = breadcrumbs(page_id=page.id) %}
//! {% import "_breadcrumbs.html" as bc %}
//! {{ bc::render(crumbs=crumbs) | safe }}
//! ```
//!
//! ## Options
//!
//! - `include_root` — keep the tenant root crumb (defaults `true`).
//! - `include_current` — keep the leaf crumb (defaults `true`;
//! public templates usually want this off when the breadcrumb sits
//! right above the page's `<h1>`).
//! - `max_depth` — cap the walk to N ancestors; oversized trees
//! degrade gracefully.
use rustango::core::Column as _;
use crate::page::Page;
/// One link in the breadcrumb trail.
#[derive(Debug, Clone, serde::Serialize)]
pub struct Crumb {
pub title: String,
/// Tenant-absolute, like `url_path`. On a hostname-mapped site, pass it
/// through [`crate::site::to_public_path`] with the site's prefix.
pub url: String,
pub is_current: bool,
pub page_id: Option<i64>,
}
/// Options controlling [`resolve_breadcrumbs`].
#[derive(Debug, Clone, Copy)]
pub struct BreadcrumbsOptions {
/// Keep the root-most ancestor in the trail. Defaults `true`.
pub include_root: bool,
/// Keep the leaf (the page passed to `resolve_breadcrumbs`).
/// Defaults `true`; flip off when the breadcrumb is rendered
/// next to the page's `<h1>` to avoid duplication.
pub include_current: bool,
/// Hard cap on ancestor walks. Defaults 32 — guards against
/// pathological tree depths.
pub max_depth: usize,
}
impl Default for BreadcrumbsOptions {
fn default() -> Self {
Self {
include_root: true,
include_current: true,
max_depth: 32,
}
}
}
/// Walk the page's ancestor chain and return an ordered crumb list
/// from root to leaf.
///
/// # Errors
/// Propagates driver / query failures from the page lookups.
pub async fn resolve_breadcrumbs(
pool: &rustango::sql::Pool,
page_id: i64,
options: BreadcrumbsOptions,
) -> Result<Vec<Crumb>, rustango::sql::ExecError> {
let target = Page::objects()
.where_(Page::id.eq(page_id))
.first(pool)
.await?;
let Some(leaf) = target else {
return Ok(Vec::new());
};
// Every ancestor in one query from the materialized path (#747) — the
// walk it replaces cost one round trip per level. Root first; keep the
// `max_depth` nearest the leaf.
let paths = crate::tree::MaterializedPath::ancestors_of(&leaf.path);
let mut chain: Vec<Page> = if paths.is_empty() {
Vec::new()
} else {
use rustango::sql::FetcherPool as _;
Page::objects()
.where_(Page::path.is_in(paths))
.order_by(&[("path", false)])
.fetch(pool)
.await?
};
// Byte order, not the collation's: a path's prefixes sort first then.
chain.sort_by(|a, b| a.path.cmp(&b.path));
let excess = chain.len().saturating_sub(options.max_depth);
chain.drain(..excess);
chain.push(leaf);
if !options.include_root && !chain.is_empty() {
chain.remove(0);
}
if !options.include_current && !chain.is_empty() {
chain.pop();
}
let last_index = chain.len().saturating_sub(1);
Ok(chain
.into_iter()
.enumerate()
.map(|(i, page)| Crumb {
title: page.title.clone(),
url: if page.url_path.is_empty() {
"/".to_owned()
} else {
page.url_path.clone()
},
is_current: i == last_index,
page_id: page.id.get().copied(),
})
.collect())
}
/// Convenience: render the breadcrumb crumb list as a JSON value
/// suitable for stuffing into a Tera context. Use this in admin or
/// public-render handlers right before calling `tera.render(...)`:
///
/// ```ignore
/// let crumbs = breadcrumbs::resolve_breadcrumbs(pool, page_id, opts).await?;
/// ctx.insert("breadcrumbs", &breadcrumbs::to_context_value(&crumbs));
/// ```
///
/// Tera's sync function signature can't host the async DB walk
/// directly without a tokio runtime handle, so we keep the API on
/// the handler side — every chrome'd handler already has the pool
/// in scope, so pre-fetching is free.
#[must_use]
pub fn to_context_value(crumbs: &[Crumb]) -> serde_json::Value {
serde_json::to_value(crumbs).unwrap_or(serde_json::Value::Array(Vec::new()))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn options_defaults() {
let o = BreadcrumbsOptions::default();
assert!(o.include_root);
assert!(o.include_current);
assert_eq!(o.max_depth, 32);
}
}