N
Naveenr.dev
Chapter 24
15 min read•2026-09-02
📖 Edge Delivery Services SeriesChapter 24 · 27 chapters

Header, Footer, and Theming — EDS vs AEM

How header/footer and theming actually work in AEM Edge Delivery Services compared to classic AEM. Covers global nav/footer documents vs Experience Fragments, the metadata-driven theme mechanism vs AEM Style System, and a clear feasible-vs-not-feasible comparison for teams learning EDS.

Content Objective

This chapter documents two things that trip up every team moving from classic AEM to Edge Delivery Services (EDS):

  • Header and footer — how they are authored and reused across pages.
  • Theming — why AEM's Style System / theme concept does not carry over, and what EDS gives you instead.

For each topic it states plainly: what is possible in EDS, what is not, and how it differs from AEM, so it can be used to explain the model to the team and set correct expectations before a project starts.

This is written from a real POC (naveenrapelly34/eds-poc) where these exact questions came up.

Part 1 — Header and Footer

The one-line mental model

In EDS, the header and footer are global documents authored once, not components you place on every page.

Every page in an EDS site automatically loads the same header and footer. You do not re-author them per page, and you do not "enable" them through a template or page policy the way you do in AEM.

How it works in this project

The boilerplate wires header and footer loading in scripts.js (loadHeader / loadFooter). The blocks fetch a plain-HTML fragment:

  • Header block fetches /{nav-path}.plain.html — path comes from the nav metadata, defaulting to /nav.
  • Footer block fetches /{footer-path}.plain.html — path comes from the footer metadata, defaulting to /footer.

On every page, the header block requests /nav.plain.html and the footer block requests /footer.plain.html, so the whole site renders one shared header and one shared footer.

So the workflow is:

  1. Create a page named nav and a page named footer at the site root.
  2. Author the header on nav (in this project using the adc-header-* blocks: logo, mega-menu, search, language, links).
  3. Author the footer on footer.
  4. Publish both.
  5. Every other page renders that shared header/footer automatically — forever. Edit nav once and the whole site updates.

Changing the path (optional): if the nav/footer live somewhere other than /nav and /footer, set the nav and footer metadata (page properties, or a site-wide metadata sheet). Set it once site-wide so all pages agree.

EDS vs AEM — header/footer

ConcernClassic AEMEDS
Reuse mechanismExperience Fragment referenced by the template/nav and /footer documents fetched by header.js / footer.js
How it's enabled on a pageTemplate structure / page policyAutomatic — wired in scripts.js for every page
Where authoredXF console (/content/experience-fragments/...)Two normal pages (nav, footer)
Per-page overrideNew template / policyPoint nav / footer metadata at a different path
DeliveryAEM renders server-sideStatic HTML fragment fetched client-side

Key takeaway to explain to the team: the concept is the same as an Experience Fragment (author once, reuse everywhere), but the mechanism is a plain document fetched by JavaScript — there is no template, no policy, and no "enable in page properties" step.

Feasible vs not — header/footer

Possible in EDS

  • One global header/footer shared across all pages. ✅
  • Different header/footer per section by overriding the nav / footer metadata per path (e.g., a microsite with its own nav). ✅
  • Fully custom header markup, mega-menus, search, language switch — all as blocks authored on the nav document. ✅

Not the same as AEM

  • No Experience Fragment console, no XF variations/localization UI. ✅ (use separate nav documents per locale instead)
  • No template-driven inclusion or editable-template structure locking. ✅
  • No server-side personalization of the header at render time (EDS is static; personalization is client-side or edge-side). ⚠️

Part 2 — Theming

The one-line mental model

AEM's Style System, template policies, and theme concepts do not exist at EDS delivery time. Theming in EDS is plain CSS that you build yourself.

EDS serves static HTML plus your CSS/JS. There is no AEM rendering at delivery, so there is nothing for an AEM "theme" or "policy" to hook into.

How theming works in this project

The project implements a custom theme mechanism (not an AEM feature):

  1. A theme page-metadata dropdown lets the author pick a value (e.g. theme1, theme2) — defined in component-models.json.
  2. loadTheme() in scripts.js reads the theme metadata, adds a theme-<value> class to <body>, and loads /styles/themes/<value>.css.
  3. That CSS file sets the design tokens (CSS custom properties) for the theme.

Concretely: picking theme2 writes <meta name="theme" content="theme2"> into the page; loadTheme() reads that, adds class="theme-theme2" to <body>, and requests /styles/themes/theme2.css.

The classic gotcha — "the page goes white when I pick another theme"

This happens when the selected theme's CSS file does not exist. If the dropdown offers theme2 but there is no styles/themes/theme2.css, the browser gets a 404, <body> gets the theme-theme2 class with no backing CSS, and any base styles that depend on theme tokens render unstyled (white).

Fix: every theme option in the dropdown must have a matching styles/themes/<value>.css file. Add options and CSS files together, never one without the other.

EDS vs AEM — theming

ConcernClassic AEMEDS
Theme sourceStyle System, policies, client libs, template configPlain CSS files + CSS custom properties you author
How a theme is selectedPage policy / template / Style System UIA custom theme metadata field → body class → CSS file
Who builds itPartly provided by AEM framework100% built by the project (nothing out of the box)
ScopeComponent-level style policiesWhole-page tokens via <body> class + variables
RuntimeServer-side, AEM-managedStatic CSS, project-managed

Feasible vs not — theming

Possible in EDS

  • Multiple named themes via CSS files + a metadata dropdown. ✅
  • Per-page theme selection (author picks in page properties). ✅
  • Site-wide default theme via metadata. ✅
  • Design tokens / dark mode / brand variants using CSS custom properties. ✅
  • Section-level or block-level variants using block option classes. ✅

Not possible / not the same as AEM

  • ❌ AEM Style System does not exist — no component style policies UI.
  • ❌ Editable template policies do not drive styling.
  • ❌ No server-side theme resolution — it's all static CSS + a body class.
  • ❌ No client-library category system — CSS/JS are loaded by the boilerplate loader (loadCSS), not by cq:ClientLibraryFolder.
  • ⚠️ Every theme must be hand-authored as CSS; there is no policy UI that generates it for you.

Bottom line to explain to the team: Theming is fully possible in EDS, but it is a CSS discipline, not an AEM feature. You get more control and better performance, but nothing is provided automatically — you build each theme as a CSS file and wire it through metadata.

Quick Comparison Cheat-Sheet

CapabilityAEMEDSNotes
Global header/footerExperience Fragment + template/nav + /footer documentsAuthor once, auto-loaded
Per-page header overrideNew template/policynav / footer metadataSimpler in EDS
"Enable header in page properties"Template/policy stepNot needed — always onWired in scripts.js
Style System / component policies✅❌Replaced by CSS + block options
Editable template theme config✅❌Replaced by metadata + CSS files
Named themesPolicies/clientlibsCustom metadata + styles/themes/*.cssYou build it
Dark mode / brand tokensClientlibsCSS custom propertiesCleaner in EDS
Server-side theme/personalization✅❌EDS is static; do it client/edge-side

How to Explain This to the Team (Talking Points)

  1. Header/footer are documents, not per-page components. Author nav and footer once; every page loads them automatically. It replaces the Experience Fragment + template pattern.
  2. There is no "enable header/footer in page properties." It's wired in code for the whole site. Overrides happen through nav / footer metadata, not templates.
  3. AEM theming does not transfer. No Style System, no policies, no client libraries at delivery. EDS is static HTML + CSS.
  4. Theming is still fully possible — as CSS. A metadata dropdown picks a theme; a matching styles/themes/<name>.css provides the tokens. Add the option and the CSS file together, or the page renders white.
  5. The trade-off is control vs. convenience. EDS gives you performance and full CSS control, but you build theming yourself instead of getting an AEM framework feature.

Related Chapters

Enjoyed this chapter?

Get an email when I publish the next chapter. No spam — just new technical deep-dives.

← PreviousAEMCoder in Practice — Results from the EDS POCNext →Theming and Theme Inheritance in EDS

Comments

Share feedback or questions about this blog post.

No comments yet. Be the first to share your thoughts.