Building iFrame Modals

The mx-build-iframe attribute in Trongate MX allows you to dynamically create modal dialogs that contain embedded iframes. Unlike a conventional modal — where HTML is appended directly into the current page — an iframe modal loads the target page inside its own browsing context. This brings three important benefits: CSS isolation, JavaScript isolation, and an independent page lifecycle.

Why Use an iFrame Modal?

When you build a modal with mx-build-modal, the server returns a fragment of HTML that Trongate MX injects into the current document. This works well for simple content, but it can introduce problems in more complex scenarios:

• Existing JavaScript may need to be re-initialised after the content appears.
• Event handlers may be attached multiple times if the modal is opened repeatedly.
• Components may require manual cleanup when the modal closes.
• Third-party widgets may not behave correctly when dynamically inserted.
• CSS from the embedded content can leak into the parent page — and vice versa.

An iframe modal sidesteps all of these problems because the embedded page runs in its own browsing context with its own window, document, global variables, event listeners, timers and application state. The page loads naturally from top to bottom, executes its JavaScript exactly as if it had been opened in a new browser tab, and cleans itself up automatically when the iframe is removed.

Demonstration

Click the button below to see a demonstration. The page loaded inside the iframe has its own CSS and JavaScript and runs entirely independently of this documentation page.

Syntax

The mx-get attribute (or any core MX method attribute like mx-post) provides the URL that will be loaded into the iframe. The iframeOptions is a JSON object that configures the modal and the iframe itself.

Basic Usage

Here is an example of using mx-build-iframe to display a page from your own site inside a modal:

Here is a pure HTML representation of the solution:

Key details about this example:

• A modal with the ID "terms-modal" is dynamically created upon clicking the button.
• The mx-get value ("legal/terms") becomes the iframe's src attribute.
• The modal itself has a max-width of 700px while the iframe fills the full width.
• A modal heading labelled "Terms & Conditions" appears above the iframe.
• No HTTP request is fired by Trongate MX — the browser loads the iframe content directly.

CSS and JavaScript Isolation

CSS Isolation

Because an iframe creates a separate browsing context, stylesheets loaded inside the embedded page cannot affect the parent document — and the parent's styles cannot leak into the iframe. This eliminates the risk of style collisions between the modal content and the rest of your application.

JavaScript Isolation

JavaScript running within the embedded page remains isolated from JavaScript running on the parent page. Global variables, event listeners, timers and application state are kept separate, reducing the likelihood of naming collisions, unintended side effects or lifecycle conflicts between independent interfaces.

Independent Page Lifecycle

Another significant benefit of iframe modals is that the embedded page retains its own JavaScript lifecycle. Scripts execute as they would during a normal page load, without requiring special initialisation logic after content injection. This can simplify development and reduce the risk of event-handler conflicts, duplicated initialisation code and other issues commonly associated with dynamically appended modal content.

For large applications — particularly those where different screens may use different JavaScript frameworks or library versions — this isolation is invaluable.

How iFrame Modals Differ from Regular Modals

Unlike regular modals created with mx-build-modal, iframe modals built with mx-build-iframe have some important technical differences:

• No HTTP request is fired. The URL from your mx-get (or mx-post etc.) is assigned directly as the iframe's src attribute. The browser loads the content without Trongate MX making any AJAX call.
• Any core MX method attribute works. While mx-get is the most natural choice, you can equally use mx-post, mx-put, mx-patch, or mx-delete — the attribute's value is always treated as the iframe URL.
• mx-target and mx-select are not applicable. Since no server response is being swapped into the DOM, content-swapping attributes like mx-target and mx-select are ignored.
• Styles and scripts are isolated. The iframe's content cannot interfere with the parent page — and vice versa.

iFrame Options Reference

When using mx-build-iframe with a JSON object, the following options are available:

Modal Options

These options control the modal window itself:

• id (required): The modal's unique ID in the DOM.
• width (optional): Max-width of the modal window (e.g., "800px", "90vw").
• marginTop / margin-top (optional): Distance from the top of the viewport. Defaults to "12vh" if unspecified.
• modalHeading (optional): HTML content for the modal heading displayed above the iframe.
• modalFooter (optional): HTML content for the modal footer displayed below the iframe.
• renderCloseIcon (optional): Controls whether a close icon appears when using modalHeading. Defaults to true.

iFrame Options

These options control the iframe element:

• height (optional): CSS height of the iframe. Defaults to "400px".
• iframeAllow (optional): Value for the iframe's allow attribute (e.g., "autoplay; encrypted-media").
• iframeSandbox (optional): Value for the iframe's sandbox attribute (e.g., "allow-same-origin allow-scripts").
• iframeAllowFullscreen (optional): Set to false to disable fullscreen. Defaults to true.

Practical Examples

Loading an Existing Internal Page

The most common use case: take a page that already works standalone and display it inside a modal — no modifications required:

Internal Page with Sandboxing

Load a page from your own site and apply sandbox restrictions for additional security:

With a Modal Footer

Add buttons below the iframe using the modalFooter option:

Maximum Width with No Heading

For a near-full-screen experience without a heading or close icon:

Embedding Third-Party Content

While the primary use case for mx-build-iframe is loading pages from your own application, it also works well for embedding trusted third-party content such as YouTube videos or Google Maps. These examples are included here for completeness.

YouTube Video

Google Map

Modal Headers and the Close Icon

When using mx-build-iframe with a modalHeading property, Trongate MX automatically adds a close icon (×) to the top-right corner of your modal window. The system detects whether Font Awesome is available in your project. If it is, Trongate MX will use the fa-times icon. If Font Awesome is not available, the system automatically generates a similar-looking SVG close icon instead.

If you do not want the close icon to appear automatically when using a modalHeading, you can prevent this by setting the renderCloseIcon property to false in your modal options. This will create a modal header without any close button.

Loading State

While the iframe content is loading, Trongate MX displays a CSS spinner inside the modal body. Once the iframe has finished loading its content, the spinner is automatically removed. No additional configuration is required.

Additional Notes

• Modal styling is governed by your application's CSS — customise as needed.
• The iframe's src is always derived from the value of your core MX method attribute (mx-get, mx-post, etc.).
• No AJAX request is fired when using mx-build-iframe — the browser loads the iframe content directly.
• Both marginTop and margin-top are valid property names for the modal's top margin setting.
• For security, consider using the iframeSandbox option when loading external content.
• The iframe's own page lifecycle — including any JavaScript initialisation — runs automatically as it would in a normal browser tab.

By using mx-build-iframe, you can embed internal pages, dashboards, forms and reports into your Trongate application with full CSS and JavaScript isolation — all with a single, declarative attribute.