intotheeast-com/docs/working/milestone2-template-refactor-brief.md

Milestone 2: Template Refactor — Session Brief

Use this as the starting point for the brainstorm in a new session. Invoke the brainstorming skill (/brainstorm) and hand it this file as context.

---

What this milestone is about

The asset pipeline (Milestone 1) is done — CDN dependencies eliminated, JS deduplicated into shared bundles. The templates themselves still have structural problems that make them hard to maintain and extend.

Problems to solve

1. trip.html.twig mixes three concerns

Currently ~384 lines after Milestone 1 cleanup. Still mixes:

• Twig data-building loops (collecting map_entries, building entry lists, GPX URL arrays)
• HTML structure (cards, panels, filter bar)
• Inline JS (map init, GPX stats block)

Goal: split into focused, readable sections or partials.

2. map_entries loop is duplicated across 4 templates

Near-identical Twig loop that builds [{lat, lng, title, slug, url, type, ...}] appears in:

• trip.html.twig
• dailies.html.twig
• stories.html.twig
• map.html.twig

Candidate for a Twig macro so a change only needs to happen once.

3. Stats computation is slow Twig loops

Country counting, temperature range, days on road — currently computed in Twig on every uncached page load. At 60–80 entries this is noticeable.

Stronger option: Move to a small PHP Grav plugin that exposes a single {{ trip_stats }} Twig variable. PHP loops are significantly faster than Twig loops. This is also the prerequisite for showing stats on other pages (homepage, story pages) in future.

4. Date range formatting duplicated

Same date formatting logic in both story.html.twig and stories.html.twig.

5. Latent bugs on inactive pages (fix while touching templates)

While refactoring, fix these two issues on pages not yet in active use:

• map.html.twig: inline map init needs DOMContentLoaded wrapper; {% block map_assets %} nested inside {% block content %} (double-registers assets)
• feed-map.html.twig (partial): {% do assets.addCss %} registers after {{ assets.css()|raw }} has rendered; inline map init also needs DOMContentLoaded

---

Key constraint

Mischa wants stats and cycling data (distance, elevation gain/loss, moving time) visible on other pages in future (homepage, story pages). Centralising the computation — whether as Twig macros or a PHP plugin — is the prerequisite for that.

What NOT to do in this milestone

• Don't touch JS or asset pipeline (that's Milestone 1, done)
• Don't redesign the visual layout
• Don't activate dailies.html.twig, stories.html.twig, or map.html.twig as new features — just fix their structural bugs while you're in the templates

Relevant files

• user/themes/intotheeast/templates/trip.html.twig — main template (~384 lines)
• user/themes/intotheeast/templates/partials/base.html.twig — base layout
• user/themes/intotheeast/templates/partials/feed-map.html.twig — mini-map partial
• user/themes/intotheeast/templates/map.html.twig — full-page map (inactive)
• user/themes/intotheeast/templates/dailies.html.twig — journal feed (inactive)
• user/themes/intotheeast/templates/stories.html.twig — stories grid (inactive)
• user/themes/intotheeast/templates/story.html.twig — single story page
• user/plugins/ — where a new stats plugin would live

Open question for the brainstorm

The biggest design decision: PHP plugin vs Twig macro for stats computation.

• Twig macro: simpler, no new plugin, but still slow Twig loops
• PHP plugin: faster, reusable across pages, but adds a plugin to maintain

Mischa's stated preference leans toward the PHP plugin given the future-reuse goal, but hasn't committed yet.