freemarker

Instruction file imported from CarmineTesta/ia-foundaments (.github/instructions/freemarker.instructions.md). Copyright stays with the author.

FreeMarker conventions

applyTo covers .ftl files (Keycloak login/email/account templates, other template-based rendering).

Build & preview

• No build tool required for the template themselves (Keycloak reads them at runtime). Preview is manual-visual-review as declared in tech_stacks.<module>.test_runner of project-profile.yaml.
• Modifications require restarting Keycloak (or triggering the theme cache invalidation) to see the effect.

Structure & discipline

• Respect the layout of the module already present (login/, email/, account/ sub-folders for Keycloak themes). Read the existing template before adding a new one (\u00a76.3 AGENTS.md).
• Reuse Keycloak-provided macros (layout.ftl, template.ftl, <@layout.registrationLayout />, ...) instead of duplicating their HTML.
• Localization strings go in messages_<locale>.properties alongside the template. Never hard-code user-visible strings in FTL.
• Assets (CSS, JS, images) go under <theme>/resources/; reference them with ${url.resourcesPath}/..., never with hard-coded paths.

General discipline

• No inline styling if the module already uses Bootstrap Italia or an existing design system. Extend the design system, don't bypass it.
• XSS: FreeMarker auto-escapes only if the module's <#ftl output_format="HTML"> is set at the top of the template. Verify; if unset, escape explicitly (${var?html}) on any user-controlled value.
• Never log or expose FTL debug output (<#assign _debug=true>, <#stop "...">) in files that ship to production.
• Redact per AGENTS.md \u00a77.3 any variable whose name matches secret|token|key|password|pwd|authorization|cookie \u2014 never render in the template body, never in error pages.

Testing

• Manual visual review on the target Keycloak version (pinned in the module's Dockerfile or Helm values).
• Cross-browser check on flows that ship to end users (login, forgot-password, register).
• If a theme change is user-facing on an authentication flow, it triggers E2E on that flow per testing-strategy (rimando \u00a74 AGENTS.md).

Do NOT

• Do not introduce a new template engine (Thymeleaf, Handlebars, ...) \u2014 use FreeMarker as-is.
• Do not fork upstream Keycloak base templates into the theme unless strictly necessary; prefer overriding the specific macro.
• Do not remove locale files for a supported language without ADR.
• Do not commit locally-rendered previews (.html output) into the repo.