Action-Oriented Modal Links Integration Guide

Introduction

In modern web design, keeping users engaged without forcing them to navigate away from the current page is paramount. PolyCMS features a highly optimized, dynamic Modal Link block that allows authors to embed interactive modal overlays (popups) directly within articles or landing pages.

Whether you want to show a quick signup form, display an terms-of-service document, or embed a responsive external site inside an iframe, the Modal Link component provides a frictionless solution.

Interactive Features & Configuration

The Modal Link block is highly configurable via the Block Editor, offering granular control over styling, sizing, and content:

1. Trigger Display Modes

You can present the modal trigger in two visual styles:

• Link Mode (link): Renders as a lightweight inline link (.poly-modal-trigger-link) with dotted underline, perfect for terms and conditions or small side notes in a paragraph.
• Button Mode (button): Renders as a highly stylized pill-shaped action button (.poly-modal-trigger-button) featuring smooth hover translate micro-animations (translateY(-2px)) and distinct blue drop-shadows.

2. Sizing Presets

The overlay adapts responsively to three standard container widths:

• Small (sm): Max-width limited to 500px — ideal for simple notification alerts, login prompts, or compact confirmation dialogs.
• Large (lg): Max-width capped at 800px — perfect for custom HTML articles, forms, or multimedia contents.
• Full Screen (full): Expands to 95% of the viewport width and 85vh height — optimized for complex dashboards or heavy document readers.

3. Flexible Content Types

• HTML Layouts (html): Renders raw styled block HTML markup directly inside the card with a comfortable 24px buffer padding.
• IFrame Embeds (iframe): Integrates external web targets with absolute safety, resetting card paddings to 0px to guarantee seamless edge-to-edge rendering of the frame canvas.

Underlying Rendering Architecture

The rendering pipeline in the core ContentRenderer.php utilizes a sophisticated two-phase collector pattern to ensure the generated page HTML is clean, valid, and highly performant:

Phase 1: Phrasing Tag Trigger

The block generates an inline phrasing element (<a> or <button>) with a unique ml-* ID. Because it is rendered as an inline-level element without nested block-level markup, it maintains perfect semantic compatibility and can be safely placed inside standard text paragraphs.

Phase 2: Overlay Deferral

Instead of injecting the heavy overlay markup directly into the paragraph flow (which would break semantic guidelines and nesting rules), the renderer pushes the modal card and script segments to a global array ($this->modalOverlays). At the end of the rendering lifecycle, the system aggregates all collected modal containers and appends them at the very bottom of the document flow, immediately followed by their initialization scripts.

Event Listeners and Accessibility

PolyCMS modals are fully equipped with native, responsive interactions out of the box:

• Outside Click Closure: Clicking on the dark backdrop overlay safely closes the active modal card.
• Escape Key Listener: Pressing the Escape key immediately closes any open dialog, returning layout focus.
• Responsive Dark Mode: Features self-contained @media (prefers-color-scheme: dark) styling rules to automatically transform modal cards into sleek, low-glare slate layouts when dark mode is enabled on the client device.

Real-World Example: Embedded Interactive Dashboard

Below is a live, real-world example demonstrating both the direct full-width iframe dashboard embedding and an action-oriented modal link trigger.

Live Direct Embed (Full-Width Dashboard Mockup)

You can embed interactive reports directly into your articles using a responsive, full-width iframe container:

Interactive Full-Screen Modal Trigger

You can also package this identical report into an action-oriented modal link, allowing readers to open it in a beautiful full-screen overlay with a single click.

Here is the live modal trigger button in action:

Inline Paragraph Anchor Text Trigger

In addition to prominent action buttons, you can trigger modal overlays seamlessly from within a standard text paragraph. This inline approach is highly effective for referencing terms of service, auxiliary research data, or interactive widgets without disrupting the reader's momentum.

Here is a live paragraph demonstrating an inline modal trigger via anchor text:

We are continuously monitoring our business health to optimize operational costs. For instance, you can review our detailed monthly financial report

directly inside this window without navigating away, allowing stakeholders to make fast, data-driven decisions on the fly.

How to Embed via Markdown / HTML

To replicate this full-width iframe embed on your site, add the following markup inside your Markdown article:

<iframe src="https://databuilder.polyxgo.com/embed/report/monthly-expense-vs-payment?chart=1&table=1&type=bar&chart_hidden=1" style="width: 100%; height: 500px; border: none; border-radius: 12px;" allowfullscreen></iframe>