Templates¶
A template is the set of files that turn a hub's content into pages. It owns the document shell, the module positions, the stylesheets and the scripts. It is not the site: the template supplies the frame, and components, modules and plugins supply what goes inside it.
These chapters are for developers writing a template against the Hubzero framework. They assume you are comfortable with HTML, CSS and PHP.
When you want one¶
Reach for a template when the thing you are changing is the page around everything else — the masthead, the navigation, the colours, the footer, where the sidebar sits. A template applies to every page on the hub at once, and switching it changes the look of components you did not write.
Reach for something narrower when the change is narrower:
| You want | Build |
|---|---|
| The whole hub to look like an institution's site | a template |
| One component's markup changed, everything else left alone | an output override inside your template |
| A block of content in a sidebar | a module |
| A screen with records behind it | a component |
An override lives inside a template, so the two are not really alternatives: you get a template first, then put overrides in it.
The example these chapters build¶
One template runs through this section: northgate, the site template for
Northgate University, a partner institution on a hub whose main application is
com_bookings — the component that books a lab's
instruments.
It is deliberately not built from nothing. northgate is a copy of the shipped
kimera template with Northgate's colours, masthead and footer, plus a handful
of output overrides that restyle com_bookings to match. That is what almost
every real hub template is, and it is the route these chapters take:
- Copy a shipped template into
app/templates/northgate. - Register it with a migration, or the CMS cannot see it.
- Rename its language file and rewrite its strings.
- Rework the layout and the stylesheets.
- Add output overrides for the components that need them.
Where a chapter shows kimera, lucent, welcome, kameleon or system,
that is code you can open in this repository. Where it shows northgate, that
is what you write.
Where templates live¶
Templates are found in two places:
core/templates/— the templates that ship with the CMS. They are replaced on upgrade, so do not edit them in place.app/templates/— the templates belonging to this hub. Put your own work here. Nothing underapp/is part of the distribution; it is the hub's own directory and it is not in this repository.
Hubzero\Template\Loader
resolves a style to a directory, checking app/templates/{name} first and
falling back to core/templates/{name}, so a template in app/ of the same
name overrides a shipped one entirely. If neither has an index.php, the
loader falls back to core/templates/system.
Warning
That fallback is silent. A template whose index.php is missing,
misspelled or unreadable does not error — the hub simply renders in the bare
system template, which looks like a stylesheet failing to load. If a hub
suddenly goes unstyled, check that index.php exists at the resolved path
before you look at anything else.
What ships¶
| Template | Client | Notes |
|---|---|---|
kimera |
Site | The reference site template. LESS sources, a colour and background theme in its parameters, and a large set of output overrides in html/. Copy this one. |
lucent |
Site | A newer site template. Leaner, with layered LESS. Registered but not made the home style by its migration, and its manifest is in the older form. |
welcome |
Site | A single-page splash template. It is the home style on a fresh hub — see below. |
system |
Site | The fallback. Also holds the default email.php, group.php, help.php, login.php and offline.php layouts that other templates inherit. |
kameleon |
Administrator | The administration template, with a set of colour themes. |
Those five are the whole set; nothing else lives under core/templates.
Note
kimera and lucent are the two worth reading before you start.
kimera shows the override-heavy approach and is what northgate is copied
from; lucent shows a leaner one.
A fresh hub renders nothing¶
This surprises everybody, so it is worth knowing before you write a line of markup.
The install data makes welcome the home style for the site client:
welcome/index.php contains no
jdoc:include tags at all — not for modules, not for messages, and not for the
component. It prints its own splash page and nothing else, whatever the request
asked for. So on a fresh hub no module renders and no component output reaches
the page, and neither is a fault.
The splash page's ready link is ?getstarted=1. That branch of the layout
sets home = 1 on the style named by the template's own template parameter —
seeded as kimera — and redirects. Until someone clicks it or an administrator
changes the default style, the hub is the splash page.
The second half of the surprise is waiting on the other side. The install data
publishes the site's Main Menu module (and a Login Form) to a position
named position-7, and no shipped site template includes that position. So the
main menu still does not render after the switch. Page
layouts has the full account and
the check to run.
Where to start¶
Copy a shipped template into app/templates and work from there:
That copies the directory and rewrites the template name inside the copied files. Then write a migration so the CMS knows the template exists.
Warning
The copy is shallower than it looks.
Scaffolding::make()
rewrites the template name inside the files at the top level of the copied
directory — index.php, component.php, error.php, templateDetails.xml —
and does not descend into subdirectories. less/, css/, language/,
migrations/ and html/ arrive verbatim. No file is renamed either. After
the copy you must, by hand:
-
rename
language/en-GB/en-GB.tpl_kimera.initoen-GB.tpl_northgate.iniand rewrite itsTPL_KIMERA_*keys, or none of its strings load; -
rename
migrations/Migration20170831000000TplKimera.phpand its class, or the migration runner skips the file and — if the shippedkimerais still installed — PHP fatals on the duplicate class name; - fix anything in a subdirectory that names the source template. In
kimerathat is@pathTemplate: "/core/templates/kimera"inless/_variables.less— currently unused, and wrong the moment you use it.
The @import "../../../../core/assets/less/…" paths do survive the move:
app/templates/northgate/less/ is the same depth below the repository root as
core/templates/kimera/less/.
The chapters¶
- Migrations — registering the template with the CMS.
- Languages — translatable strings.
- Structure — the files and directories a template holds.
- Designing — planning the design before you write markup.
- Page layout —
index.php,error.phpand the rest. - Cascading style sheets — the stylesheets a template loads.
- JavaScript — jQuery, template scripts and extension assets.
- Output overrides — replacing an extension's markup.
- Packaging — the manifests and how a template is installed.
- Socicons and Fontcons — the icon fonts.
- Elements and typography — the shared grid, buttons and notification styles.
- Accessibility — what the shipped templates and the HTML helpers emit, and where the gaps are.
Rewritten and checked against 2.4-main @ 91d03d0a23 on 2026-09-10.