Embedded UI Template Reference

This reference covers the Embedded UI template system. It describes how templates are pre-loaded and intercepted so that modules render correctly when embedded in an external host page.

Angular normally fetches HTML templates using HTTP requests. In embedded mode, template fetching breaks in three ways:

1. Relative URLs resolve against the host page's domain instead of the Unqork server.
2. The HTTP interceptor prefixes URLs with hostUrl, which breaks template cache key matching.
3. Some templates, like the page header, footer, and preview bar, should not display when a module is embedded in an external page.

EMBED_TEMPLATES Map

The EMBED_TEMPLATES map is a set of templates the Embedded UI loads in advance, before Angular needs them. By loading these templates up front, the system prevents Angular from making HTTP requests for them. Those requests would fail in an embedded context.

The table below lists each pre-loaded template, what it contains, and why it is in the map.

Two-Layer Interception

The template system uses two layers of protection to ensure every template request is handled locally, without an HTTP call. The first layer pre-loads known templates at startup. The second layer acts as a fallback to catch any request the first layer missed.

Layer 1 — $templateCache Pre-Population

When the Angular module begins (during module.run()), every entry in the EMBED_TEMPLATES map is written into Angular's $templateCache. The $templateCache is Angular's built-in template storage. Once a template is in the cache, Angular uses that stored version instead of making an HTTP request. Writing to the cache at startup is the earliest possible point to intercept template loading.

Layer 2 — $templateRequest Decorator

As a fallback, the Embedded UI wraps Angular's $templateRequest service. The $templateRequest service is what Angular calls when it needs a template. When the decorator intercepts a request, it checks whether the requested template key exists in EMBED_TEMPLATES. If it does, the decorator returns the template immediately as a resolved promise with no network request. If the template is not in the map, the decorator passes the request through to Angular's original handler.

When a template fails to load, the error is reported to the host page through surfaceError().

Workflow Templates

Workflow states do not use templateUrl references. Instead, they define their templates inline using the template property in the UI-Router state configuration. UI-Router is Angular's routing library; a "state" is a named step in the application's navigation. Using inline templates bypasses the HTTP interceptor entirely—critical because the interceptor would prefix any templateUrl with hostUrl, creating a cache-key mismatch.