---
title: "Embedded UI Template Reference"
slug: "embedded-ui-template-reference"
tags: ["embedded-ui", "reference-guides"]
status: "update"
updated: 2026-10-13T18:19:15Z
published: 2026-10-13T18:19:15Z
canonical: "docs.unqork.io/embedded-ui-template-reference"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

| Template Key | Content | Purpose |
| --- | --- | --- |
| `unqorkio.html` | `<unqorkio></unqorkio>` | The core template that tells Angular where to render the Unqork module on the page. |
| `views/home.html` | Empty string | A placeholder for the home state. This state is not used in embedded mode, so the template is intentionally blank. |
| `views/form/display.html` | `<display-form-main ng-controller="displayForm">` | The container that wraps the module's form content for display. |
| `views/commonDisplay.html` | Empty string | A placeholder for shared display elements. These elements are not needed in embedded mode. |
| `views/workflow.html` | `<workflow></workflow>` | The template that tells Angular where to render an embedded workflow. |
| `views/header.html` | Empty string | The page header template, set to blank so the Unqork header does not display inside the host page. |
| `views/footer.html` | Empty string | The page footer template, set to blank so the Unqork footer does not display inside the host page. |
| `views/previewBar.html` | Empty string | The Creator preview bar template, set to blank so it does not display during embedded sessions. |

## 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.

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-04-21 | Initial publication. |
| 2026-06-15 | Updated subheading separators to em dash; expanded Workflow Templates explanation with HTTP interceptor rationale. |
| 2026-06-11 | Editorial pass: removed HR dividers, added description paragraphs to all H2/H3 sections, expanded EMBED_TEMPLATES table descriptions for non-expert readers, added plain-language explanations for Angular-specific terms, updated internal links. |

The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.

Rendering is the process of loading components and displaying the final result on the front-end screen.

AngularJS is a JavaScript framework added to an HTML page with a <script> tag. AngularJS extends HTML attributes and binds data to HTML using expressions.

HTML (Hyper Text Markup Language) is the standard markup language for for achieving font, color, graphic, and hyperlink effects when creating web pages.

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

Fetching is the process of retrieving data from a database, making it available to the application and the end-user.

A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases.

A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.

Elements are are what you use to build Unqork applications. Elements include modules, workflows, Data Collections, Data Schema, and Record Collections.

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.

A definition

A JavaScript property is a member of an object that associates a key with a value. A JavaScript object is a data structure that stores a collection of properties.