(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

IFrame

Overview

• The IFrame component embeds external web content inside your application.
• It keeps the embedded content separate from the main application for security.
• It supports HTML documents, websites, and full web applications.
• It is useful for integrating third-party tools, dashboards, or documentation.

Specs

Tokens

Structure

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel. For example, "Payment Gateway IFrame" allows for easy identification of the component's purpose in the application structure, making it easier for developers to locate and work with this specific IFrame.

(Configured in Visual Properties)

• src – Specifies the URL or path of the content to be displayed in the IFrame. This property supports template expressions to make the source dynamic based on context data. For example, "https://example.com/reports" will embed the reports page, while "${context.reportUrl}" would use a URL from the current context. This property is crucial as it determines what content will be displayed in the IFrame.

(Configured in Visibility Properties)

• displayConditions – Defines conditions for displaying the component. This allows showing or hiding the IFrame based on complex rules involving form values, user roles, or application state. For example, the IFrame might only be shown if a specific feature is enabled in the system or if the user has completed certain actions.

Styling

(Configured in Visual Properties)

• width – Sets the width of the IFrame in pixels or percentages. For example, "800px" creates a fixed-width IFrame, while "100%" makes the IFrame expand to fill the width of its container. Setting the appropriate width ensures the embedded content is displayed correctly within your layout.
• height – Sets the height of the IFrame in pixels or percentages. For example, "600px" creates a fixed-height IFrame, while "100%" makes the IFrame expand to fill the height of its container. Setting a proper height prevents unnecessary scrolling and ensures the embedded content is fully visible.
• paddingClass – Configures spacing around the IFrame using CSS classes. For example, "p-4" adds medium padding on all sides of the component, improving its visual integration within its container.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to.
• ON_PAGE_LOAD – Triggered when the content within the IFrame has finished loading. This event can be used to perform actions once the embedded content is ready, such as updating related components or recording analytics about content availability.
• ON_INIT – Triggered when the IFrame component is initialized. Can be used to perform setup operations or to initialize related components.
• ON_DESTROY – Triggered when the IFrame component is removed from the DOM. Useful for cleanup operations and releasing resources to prevent memory leaks.

Authorization

(Configured in Authorization)

• visibilityPolicySetId – Determines the visibility of the component based on specified policy sets. For example, setting to "secureContentPolicy" restricts the IFrame visibility to users with permissions to view potentially sensitive external content. This ensures that embedded content is only shown to authorized users.

Tests

(Configured in Testing Hooks)

• id – Specifies a unique identifier for the component used for programmatic access. For example, "paymentGatewayFrame" enables targeted manipulation of this specific IFrame component through scripts or automated tests.
• dataTestId – Sets the testing hook ID for automated testing. For example, setting it to "payment-gateway-iframe" allows test scripts to reliably locate this component during automated testing.
• enableAsHotspot – Enables the component as a guided tour hotspot. When enabled, the IFrame can be highlighted during onboarding or tutorial flows to draw user attention to important embedded content.
• guidedTourHotSpotTitle – Sets the title for the guided tour hotspot, supporting translations. For example, {"en-US": "Payment Gateway", "de-DE": "Zahlungs-Gateway"} provides clear identification during guided tours.
• guidedTourHotSpotDescription – Sets the description for the guided tour hotspot, supporting translations. For example, {"en-US": "This area displays our secure payment processing system", "de-DE": "Dieser Bereich zeigt unser sicheres Zahlungsabwicklungssystem"} provides detailed instructions during guided tours.

Guidelines

Usage

• Embed third-party pages or apps by setting src to a trusted, task-relevant URL or a template expression (e.g., "${context.reportUrl}").
• Show the IFrame only when prerequisites are satisfied (e.g., a selection exists) so users don’t see empty frames (displayConditions).
• Restrict visibility of sensitive or licensed content to authorized audiences (visibilityPolicySetId).
• Name the instance clearly for authors/QA so it’s easy to find in complex screens (displayName).

Sizing & Layout

• Size the frame to the embedded content’s expected viewport; use percentages for flexible layouts and pixels for fixed designs (width, height).
• Add breathing room so the frame doesn’t butt up against adjacent UI (paddingClass).
• For content that should fill the available area, set width: "100%" and an appropriate height to avoid double scrollbars.

Visibility & Authorization

• Hide the IFrame entirely for unauthorized users (visibilityPolicySetId).
• Combine authorization with runtime prerequisites to prevent blank or misleading frames (visibilityPolicySetId, displayConditions).

Content & Localization

• Localize any user-facing tour copy associated with the frame (guidedTourHotSpotTitle, guidedTourHotSpotDescription).
• Use displayName for authoring clarity only; it does not surface to end users.

Dos & Don’ts

Accessibility

• Hide entire frames that users must not access to reduce confusion and accidental focus (visibilityPolicySetId).
• Prevent “blank frame” experiences by rendering only when content is available (displayConditions).
• Provide stable hooks for automated accessibility checks (dataTestId, id).
• Offer localized guidance during tours (guidedTourHotSpotTitle, guidedTourHotSpotDescription, enableAsHotspot).
• Use paddingClass to avoid crowding touch targets adjacent to the frame.