HTML Templates with HtmlTemplatePage

Oorian is a pure-Java web framework — you build pages by constructing element trees in Java. But sometimes you already have an HTML file: a designer hand-off, a Bootstrap template, or a legacy page you want to bring under Oorian's event model without rewriting it from scratch. That's what HtmlTemplatePage is for.

What HtmlTemplatePage Does

HtmlTemplatePage extends HtmlPage. When a request comes in, it reads an HTML file from your servlet context, parses it with Oorian's built-in HtmlParser, and replaces the page's <head> and <body> with the parsed elements. Attributes on the root <html> element (like lang) are applied to the page automatically.

After parsing, Oorian calls createHead() and createBody() — the same lifecycle hooks you use in pure-Java pages. At that point the head and body already contain everything from the template, so your overrides are additive: find elements, modify them, attach listeners, inject components.

A Minimal Example

Start with a standard HTML file. Add id attributes to elements you want to manipulate from Java:

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Dashboard</title>
    <link rel="stylesheet" href="/css/dashboard.css">
</head>
<body>
    <div class="layout">
        <header>
            <h1 id="page-title">Placeholder</h1>
        </header>
        <main id="content">
            <!-- Oorian components go here -->
        </main>
        <footer>Copyright 2026</footer>
    </div>
</body>
</html>

Then create a Java class that extends HtmlTemplatePage. Pass the template path to the constructor — the path is relative to your servlet context root:

@Page("/dashboard")
public class DashboardPage extends HtmlTemplatePage
{
    public DashboardPage()
    {
        super("/templates/dashboard.html");
    }

    @Override
    protected void createBody(Body body)
    {
        Element title = getElementById("page-title");
        title.setText("User Dashboard");

        Element content = getElementById("content");
        content.addElement(createStatsPanel());
        content.addElement(createRecentActivity());
    }
}

That's it. The template's HTML structure, CSS links, and static content are preserved. Your Java code adds dynamic behavior on top.

Finding Elements

Every element in the parsed template is a real Oorian Element object. You can find them using the same methods available on any Oorian page:

getElementById(String id) — find a single element by its id attribute
getElementsByTagName(String tag, boolean recursive) — find all elements matching a tag name

@Override
protected void createBody(Body body)
{
    // Find by ID
    Element sidebar = getElementById("sidebar");
    sidebar.addElement(createNavMenu());

    // Find all buttons and attach click listeners
    Elements buttons = body.getElementsByTagName("button", true);

    for (Element button : buttons)
    {
        button.registerListener(this, MouseClickedEvent.class);
    }
}

Once you have an element reference, the full Oorian API is available: setText(), addElement(), registerListener(), addClass(), addAttribute(), and sendUpdate() for pushing live changes.

Modifying the Head

Override createHead() to add resources to the template's existing head content. Everything from the template is already there — your additions are layered on top:

@Override
protected void createHead(Head head)
{
    head.addCssLink("/css/extra-styles.css");
    head.addElement(new JavaScript("/js/analytics.js"));
}

Character Encoding

HtmlTemplatePage reads template files as UTF-8 by default. If your template uses a different encoding, call setCharset() before the page initializes:

public DashboardPage()
{
    super("/templates/dashboard.html");
    setCharset("ISO-8859-1");
}

Full Oorian Features

Template pages are full Oorian pages. Everything that works in a pure-Java page works here:

Events — register MouseClickedEvent, FormEvent, InputChangeEvent, and all other client events on template elements
Communication modes — configure AJAX, SSE, or WebSocket per page
Worker threads — use OorianWorkerThread.create() for background processing with live UI updates
Session events — coordinate between pages using OorianSession listeners
Live updates — call sendUpdate() to push changes to the browser

When to Use Templates

HtmlTemplatePage is the right choice when:

A designer delivers HTML/CSS that you want to serve as-is with Java interactivity
You're migrating existing HTML pages to Oorian incrementally
The page is mostly static with a few dynamic areas
SEO requires a specific HTML structure that's easier to express in markup

For highly dynamic pages, pages with heavy component reuse, or pages where the entire structure is determined at runtime, pure Java pages are usually a better fit. The two approaches can coexist freely in the same application — choose per page based on what makes sense.

Under the Hood

When a template page is requested, the lifecycle works like this:

initializePage() reads the HTML file via OorianSession.get().getResourceAsStream()
The file contents are parsed by HtmlParser into an Oorian element tree
Attributes from the <html> root element are applied to the page
The parsed <head> and <body> replace the page's defaults via setHead() and setBody()
Oorian's normal page lifecycle continues — createHead() and createBody() are called for your modifications
If the file isn't found or can't be parsed, an HttpFileException is thrown

The parser handles HTML5 constructs including void elements, optional end tags, and complex nesting. Your template doesn't need to be XHTML-strict — standard HTML5 works fine.

Try It

Check out the interactive demo on our demos page to see HtmlTemplatePage in action — a full Bootstrap template served through Oorian with live element modification from Java.