Skip to main content
Version: 8.3

iFrame widget

Level: beginner
note

This functionality is available for Creatio 8.3.3 and later.

The iFrame widget embeds external web content or custom HTML into a Freedom UI page or dashboard, so users can view and interact with this content without leaving Creatio. Creatio renders the widget as a native HTML <iframe> element. Learn more: iFrame (user documentation), Set up an iFrame component (user documentation).

View an example of a configuration object that sets up an iFrame widget that loads an external URL below.

Example of a configuration object that sets up an iFrame widget that loads an external URL
{
    "operation": "insert",
    "name": "IFrame_o2g941z",
    "values": {
        "type": "crt.IFrame",
        "urlContent": "https://example.com",
        "sandbox": "allow-scripts",
        "allow": "fullscreen",
        "layoutConfig": {
            "column": 1,
            "row": 1,
            "colSpan": 8,
            "rowSpan": 8
        }
    },
    "parentName": "MainContainer",
    "propertyName": "items",
    "index": 0
}

View an example of a configuration object that sets up an iFrame widget that renders custom HTML below.

Example of a configuration object that sets up an iFrame widget that renders custom HTML
{
    "operation": "insert",
    "name": "IFrame_o2g941z",
    "values": {
        "type": "crt.IFrame",
        "htmlContent": "<h1>Hello from IFrame!</h1><p>This is custom HTML content.</p>",
        "sandbox": "",
        "layoutConfig": {
            "column": 1,
            "row": 9,
            "colSpan": 8,
            "rowSpan": 4
        }
    },
    "parentName": "MainContainer",
    "propertyName": "items",
    "index": 1
}
string type

Widget type. "crt.IFrame" for the iFrame widget.

LayoutConfig layoutConfig

Specify the widget position and size.

Parameters

Name

Type

Description

column

number

The column number where the widget starts.

colSpan

number

The number of columns the widget spans.

row

number

The row number where the widget starts.

rowSpan

number

The number of rows the widget spans.

Content properties​

string urlContent

The URL the iframe loads via the src attribute. By default, not set. Takes priority over htmlContent: when both properties are set, htmlContent is ignored.

string htmlContent

The HTML markup the iframe renders via the srcdoc attribute. By default, not set. Creatio parses the markup and injects platform scrollbar styles into it. Creatio uses htmlContent only if urlContent is not set: when both properties are set, Creatio ignores htmlContent. If neither urlContent nor htmlContent is set, the widget displays a placeholder instead of the iframe.

array of objects placeholder

Customizes the placeholder Creatio displays instead of the iframe when there is no content to show. If you do not configure the placeholder, Creatio adds the default placeholder automatically. The default placeholder shows the "Nothing to show yet. No content available in this section" notification.

View an example of a configuration object that customizes the placeholder below.

Example of a configuration object that customizes the placeholder
{
    "operation": "insert",
    "name": "IFrame_o2g941z",
    "values": {
        "type": "crt.IFrame",
        "urlContent": "$ReportUrl",
        "sandbox": "allow-scripts",
        "placeholder": [
            {
                "type": "crt.Placeholder",
                "image": null,
                "title": "No report to show yet",
                "subhead": "Save the record to generate the report"
            }
        ]
    },
    "parentName": "MainContainer",
    "propertyName": "items",
    "index": 0
}
Parameters

Name

Type

Description

type

string

Placeholder type. "crt.Placeholder" for the default placeholder.

image

object

Placeholder illustration: an icon or an animation. When the property is not set, Creatio uses the default animation. When the property is set to null, Creatio uses no illustration.

Parameters

Name

Type

Description

type

string

The illustration type.

Available values

Value

Description

icon

Out-of-the-box Creatio icon.

animation

Out-of-the-box animation.

icon

string

The name of the out-of-the-box Creatio icon. Available for the "icon" type only.

name

string

The name of the out-of-the-box animation, for example, "raccoon." Available for the "animation" type only.

width

string

The illustration width.

height

string

The illustration height.

padding

string

The padding around the icon. Available for the "icon" type only.

color

string

The icon color. Available for the "icon" type only.

tooltip

string

The tooltip text shown on hover. Available for the "icon" type only.

autoplay

boolean

Whether the animation starts playing automatically. Available for the "animation" type only.

loop

boolean

Whether the animation repeats. Available for the "animation" type only.

title

string

The placeholder title. To localize the text, use the #ResourceString(SomeResourceName)# macro that implements resource string instead of hardcoded strings.

subhead

string

The placeholder subhead. To localize the text, use the #ResourceString(SomeResourceName)# macro that implements resource string instead of hardcoded strings.

Content loading behavior​

The iFrame widget probes urlContent with an HTTP HEAD request (in no-cors mode) from the user's browser before assigning the URL to the iframe. If the request fails, the widget displays the "Content Unavailable" placeholder with a link to Creatio Academy instead of the iframe. This behavior cannot be configured via the placeholder property. The widget also displays a loading indicator while the content loads.

A successful availability check does not guarantee the page renders. The target website can still refuse embedding using the X-Frame-Options header or the frame-ancestors CSP directive. In this case, the iframe stays empty, and the widget cannot detect it. Configure the target website to allow embedding from the Creatio origin.

Security properties​

string sandbox

Sandbox restrictions for the iframe content. Space-separated tokens, for example, "allow-scripts allow-forms." Elements added in the Freedom UI Designer and Dashboard Designer get "" (maximum restrictions) by default, so <script> elements inside htmlContent do not execute. If the property is not set at all, the sandbox attribute is omitted, and the embedded content gets full capabilities.

Available values

Value

Description

allow-downloads

Allow downloading files.

allow-forms

Allow form submission.

allow-modals

Allow opening modal windows.

allow-popups

Allow opening new browser windows.

allow-popups-to-escape-sandbox

Allow new browser windows opened from the content to not inherit the sandbox.

allow-presentation

Allow starting a presentation session.

allow-same-origin

Keep the content origin, i.e., let the content access its own cookies and storage.

allow-scripts

Allow JavaScript execution. Add this token if script execution inside htmlContent is intended.

allow-top-navigation

Allow navigating the top-level page.

allow-top-navigation-by-user-activation

Allow navigating the top-level page, but only on a user gesture.

allow-top-navigation-to-custom-protocols

Allow navigation to non-HTTP protocols.

When configuring the sandbox property, follow these recommendations:

  • Keep the sandbox as restrictive as possible. Start from the maximum restrictions ("") and add only the tokens the embedded content actually requires.
  • Do not combine "allow-scripts" with "allow-same-origin" for external or untrusted content. Together, these tokens let the embedded page remove its own sandbox restrictions, which makes the sandbox ineffective. Use this combination only for fully trusted first-party content.
  • Do not omit sandbox for external URLs. Without the attribute, the embedded content gets full capabilities.
string allow

The permissions policy for the iframe: browser features the embedded content is allowed to use. Values separated by a semicolon, for example, "camera; microphone; fullscreen." By default, not set. Grant browser features sparingly: list only the features the content needs.

Available values

Value

Description

camera

Allow access to the camera.

microphone

Allow access to the microphone.

geolocation

Allow access to the device location.

fullscreen

Allow entering fullscreen mode.

autoplay

Allow automatic media playback.

payment

Allow use of the Payment Request API.

display-capture

Allow screen capture.

picture-in-picture

Allow picture-in-picture video playback.

string referrerPolicy

The referrer policy for iframe requests: how much referrer information is sent to the embedded content. The setup area of Freedom UI Designer and Dashboard Designer does not expose this property. Specify the property in the source code of the Freedom UI page. By default, not set, so the browser default applies, which is "strict-origin-when-cross-origin" in modern browsers. Use HTTPS URLs and set a stricter value (for example, "no-referrer") when the host page URL must not be shared with the embedded content.

Available values

Value

Description

no-referrer

The Referer header is not sent.

no-referrer-when-downgrade

The full URL is sent, except when navigating from HTTPS to HTTP.

origin

Only the origin is sent.

origin-when-cross-origin

The full URL for same-origin requests, only the origin for cross-origin requests.

same-origin

The full URL for same-origin requests, nothing for cross-origin requests.

strict-origin

Only the origin, and nothing when navigating from HTTPS to HTTP.

strict-origin-when-cross-origin

The full URL for same-origin requests, only the origin for cross-origin requests, nothing when navigating from HTTPS to HTTP. This is the default in modern browsers.

unsafe-url

Always the full URL. Not recommended.

iFrame troubleshooting​

The iFrame widget cannot always detect why embedded content fails to load, since the target website restrictions are enforced by the browser, not reported back to Creatio. Use the table below to diagnose common loading issues.

Issue

Description

Solution

The iframe stays empty with no visible error

The target website blocks embedding using the X-Frame-Options header or the frame-ancestors CSP directive. The widget cannot detect this case.

Configure the target website to allow embedding from the Creatio origin.

The widget displays the "Content Unavailable" placeholder

The HTTP HEAD request used to probe urlContent before loading failed.

Verify the URL is reachable from the user's browser. Check the target website or network for outages.

The widget displays the "Content Unavailable" placeholder for a URL that opens correctly in the browser

The Creatio CSP does not list the source domain as a trusted source. The browser blocks the availability check and the embedding.

Add the source domain to the trusted sources list of your CSP. At least, add it to the connect-src and frame-src directives.

Mixed content blocked

urlContent uses HTTP while the Creatio page is served over HTTPS. Modern browsers block this content by default.

Use an HTTPS URL for urlContent. If the target website only supports HTTP, use a secure alternative.

<script> elements inside htmlContent do not execute

The sandbox property is set to "" (maximum restrictions) or omits allow-scripts.

Add allow-scripts to the sandbox value if script execution is intended.

The iframe collapses to zero height

layoutConfig does not specify explicit dimensions (for example, rowSpan).

Set explicit dimensions via layoutConfig.

See also​

Overview of Freedom UI Designer and its elements (user documentation)

Set up an iFrame component (user documentation)