EMAIL: info@ardisialabs.com
Contact envelope

HtmlFrame

Overview

The HtmlFrame component displays a HTML iframe inside a Flex component. Developers can create multiple instances in a single Flex application.

The HtmFrame can display a border and background generated by Flash, and will manage an embedded iframe within the container's boundaries.

Note that this component should be used with care due to the complexity of the interaction between the browser and the Flash VM, the constantly changing nature of web browsers, and the sheer multitude of browsers and browser versions.

AIR

This component will NOT work within the AIR environment. For HTML support in AIR, try the native mx.controls.HTML and flash.html.HTMLLoader classes.

Creating the HtmlFrame Component

The HtmlFrame extends Skinnable Component and can be added to any container that supports IVisualElementContainer.

Using the HtmlFrame Component

There is no property used to set the frame's content. Instead, after creation, call setFrameSourceURL() to load a URL, or set raw HTML via the setFrameRawHTML() method. It is even possible to call any Javascript function via callFrameFunction().

Will not correctly load embedded content from library swcs. All embedded content should be local to the project.

wMode

Note that this component will function correctly without changing the wmode or any setting in the HTML wrapper. Other Flash HTML wrappers require the wmode property of the Flash player to be changed to function correctly, to the detriment of performance. The Ardisia HtmlFrame component works without this limitation.

Browser Zoom

Browsers can be zoomed. This creates problems for Flex applications because the HTML iframe will change size but the underlying Flex app will not.

It is not possible to block a user from zooming the browser. Even if the mouse wheel + ctrl events are swallowed, users can zoom within their browser's menu options.

There is currently no reliable way to detect browser zoom levels across all browsers and browser versions.

Javascript

When creating custom Javascript calls, it is suggested to apply all Javascript listeners inline to avoid cross-browser issues. E.G. Some versions of IE do not support addEventListener (uses attachEvent). Also, when adding event handlers, it is suggested to add them as anonymous inner functions because pointers to declared functions didn't work in all browsers.

var element = getElementById('test');
element.onclick = function(e) {  
	alert('I was clicked!');
}

Layout

Position the component like any visual element. The position of the frame will stay locked because all of the parent containers have MOVE listeners attached.

Styling the iFrame directly

Style the iFrame directly via the setStyleProperty() method.

z-Index

Does not manage visibility or z level automatically. To change the z level of the HTML frame, change the zIndex style property via a function call like this:

htmlFrame.setStyleProperty('zIndex', '1000');

Removing the HtmlFrame

Call dispose() to remove the Flex container and the HTML iframe and listeners. This is the only way to remove the iframe from the browser.

After the frame is removed from the Flash stage, listeners will be removed but the iframe will persist until dispose() is called.

Memory Leaks

To keep the frame's position locked, all parents of the frame up to the systemManager have MOVE listeners attached. This means that none of the parents can be garbage collected until the listeners are removed or the frame is removed and disposed.

Call dispose() to clear all the MOVE listeners and enable garbage collection.

Focus

The iframe can steal focus away when moused and the Flex application does not detect click events on the iframe. Therefore, if you put the frame inside a Pane container, or any container that changes its appearance when it is inactive, you may want to use a skin that has its inactive state removed.

Frame Visibility

Use the "visible" property on the HtmlFrame component to hide the iframe and the Flex wrapper.

Note, most browsers will not display any content in an iframe until the page is fully loaded. In other words, do not expect unstyled content to be displayed.

Printing

Print the HTML iframe via the printFrame() method. Printing will often times be blocked for external URLs due to security limitations.

Security and External URLs and Local Testing

Be conscious of cross domain security issues. For example, printing will often times be blocked for external URLs due to security limitations. Also, to test this control locally, remember to set the Security.allowDomain("*") setting in the top level application document.

Local testing only worked for the Firefox browser. Chrome doesn't appear to work properly until the application is online.

Examples

Load the Flex Apache page

<fx:htmlFrame:HtmlFrame id="frame"
	  width="100%" height="100%"
	  borderColor="0"
	  backgroundColor="0xFFFFFF"
	  borderThickness="2"
	  creationComplete="frame.setFrameSourceURL('http://flex.apache.org/');"/>

Load pdf

<fx:htmlFrame:HtmlFrame id="frame"
	  width="100%" height="100%"
	  borderColor="0"
	  backgroundColor="0xFFFFFF"
	  borderThickness="2"
	  creationComplete="frame.setFrameSourceURL('assets/docs/sample.pdf/');"/>

See the HtmlFrame demo application for more example code.

Custom Events

FRAME_ONLOAD
ardisia.components.htmlFrame.events.HtmlFrameEvent
Dispatched when the "onload" event is dispatched by the HTML frame.

Custom Styles

backgroundColor
default #FFFFFF
The color of the background. Does not apply to the iframe, only Flash regions exposed by padding.

backgroundAlpha
default 1
The alpha of the background.

borderColor
default defaults.css
The color of the border.

borderAlpha
default 1
The alpha of the border.

borderThickness
default 1
The thickness of the border.

Themes & Skinning

Included is a skin for the Spark theme.

Known Issues

  • Most browsers will not display any content in an iframe until all of the page's content is fully loaded. Do not expect lazy loading and unstyled content to be displayed.
  • setFrameRawHTML() calls after the src has been set will always fail (setting src to 'about:blank' did not work).
  • If a frame is set to display: 'none'; it will never dispatch 'load' events.
  • Javascript will not stop executing code on errors. Use Firebug to see the errors.
  • Internet Explorer may not allow relative URLs.

Back To Top