Skip to content

Embedded Templates and Layouts

Jump to bottom
Mike Christensen edited this page Aug 28, 2026 · 1 revision

Embedded templates and layouts

Imp templates are well-formed XML files embedded in the page assembly. The compiler turns them into static and dynamic chunks on first use and caches the result by page type.

Project configuration

<ItemGroup>
  <EmbeddedResource Include="PageTemplates/*.htm" />
  <EmbeddedResource Include="Templates/*.htm" />
</ItemGroup>

Set the reusable-template namespace:

.PageAssembly(typeof(Program).Assembly)
.RootTemplateNamespace("MySite.Templates")

Embedded resource names normally combine the project root namespace, folders, and filename. Inspect assembly.GetManifestResourceNames() when a resource cannot be found.

Page template

The root element must be <PageTemplate>:

<PageTemplate>
  <html lang="en">
    <head><title>Hello</title></head>
    <body><h1><Dynamic.Greeting /></h1></body>
  </html>
</PageTemplate>

Associate the exact manifest resource name with a class:

[PageTemplate("MySite.PageTemplates.Hello.htm")]
public sealed class Hello : BasePage
{
   public Task Greeting(TextWriter output, DynamicContentArgs args) =>
      output.WriteAsync("Hello from Imp");
}

Reusable layout

A reusable resource begins with <Template> and declares placeholders:

<Template>
  <html lang="en">
    <head><title><Placeholder.Title /></title></head>
    <body>
      <header>My site</header>
      <main><Placeholder.Body /></main>
    </body>
  </html>
</Template>

If it is embedded as MySite.Templates.Site.htm, use it as Template.Site:

<PageTemplate>
  <Template.Site>
    <Content.Title>About</Content.Title>
    <Content.Body>
      <h1>About this site</h1>
    </Content.Body>
  </Template.Site>
</PageTemplate>

Content.Name supplies Placeholder.Name. Missing content produces no output. Layouts may contain static markup, dynamic commands, loops, and CDN-aware attributes.

XML requirements

  • Use one root element.
  • Close every element, including HTML elements XML might otherwise treat differently.
  • Escape & as &amp; and quote attribute values.
  • Element/attribute names must be valid XML.
  • Template commands use a dot in the element name, such as Dynamic.Title.
  • Command prefixes and member names are case-sensitive; use Dynamic, Const, Loop, Template, Placeholder, and Content exactly as documented.

The compiler emits HTML but parses XML. Validate templates during tests or a smoke startup rather than discovering malformed markup on the first production request.

Cache behavior

Templates are embedded at build time and compiled at first request. Editing an .htm file on disk does not hot-reload a running application. Rebuild and restart to update the assembly and clear the process cache.

Imp is MIT licensed. See the source and Todo sample on GitHub.

Imp

Templates

Application integration

Help and reference

Clone this wiki locally