Iframe"

From Documentation
 
(34 intermediate revisions by 9 users not shown)
Line 1: Line 1:
 
{{ZKComponentReferencePageHeader}}
 
{{ZKComponentReferencePageHeader}}
  
= iFrame =
+
= Iframe =
  
*Demonstration: N/A
+
*Demonstration: [http://www.zkoss.org/zkdemo/composite/iframe Iframe]
 
*Java API: <javadoc>org.zkoss.zul.Iframe</javadoc>
 
*Java API: <javadoc>org.zkoss.zul.Iframe</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.utl.Iframe</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.utl.Iframe</javadoc>
 +
*Style Guide: N/A
  
 
= Employment/Purpose =
 
= Employment/Purpose =
  
 +
The <code>iframe </code>component uses the HTML IFRAME tag to delegate a portion of the display to another URL. Though the appearance looks similar to the <code>include </code>component. The concept and meaning of the <code>iframe </code>component is different.
  
 +
The content included by the <code>include </code>component is a fragment of the whole HTML page.
 +
 +
Because the content is part of the HTML page, the content is part of the desktop and you could access any components, if any, inside of the <code>include </code>component. The inclusion is done at the server, and the browser knows nothing about it. It means the URL specified by the <code>src </code>property could be any internal resource.
 +
 +
The content of the <code>iframe </code>component is loaded by the browser as a separate page. Because it is loaded as a separate page, the format of the content could be different from HTML. For example, you could embed an PDF file.
 +
 +
The embedding'' ''is done by the browser, when it interprets the HTML page containing the IFRAME tag. It also implies that the URL must be a resource that you can access from the browser.
 +
 +
Like the <code>image </code>and <code>audio </code>components, you could specify the dynamically generated content. A typical example is you could use JasperReport to generate a PDF report in a binary array or stream, and then pass the report to an <code>iframe </code>component by wrapping the result with the <code>org.zkoss.util.media.AMedia </code>class.
 +
 +
In the following example, we illustrate that you could embed any content by use of <code>iframe</code>, as long as the client supports its format.
  
 
= Example =
 
= Example =
  
 +
[[Image:ZKComRef_Iframe.png]]
 +
 +
<source lang="xml" >
 +
<window id="win" title="This is an Iframe Demo!">
 +
<iframe style="width:99%; height:400px;border:3px inset;" src="iframe-target-url-here" />
 +
</window>
 +
 +
</source>
 +
 +
Live iframe demo is available [https://www.zkoss.org/zkdemo/composite/iframe in the zk demo].
 +
 +
= The onURIChange Event =
 +
When the user navigates the <code>iframe</code> component to another URL (or bookmark), an object of <javadoc>org.zkoss.zk.ui.event.URIEvent</javadoc> is sent to the <code>iframe</code> component. This event is usually used to bookmark the status of the <code>iframe</code> component, such that the right content can be restored later.
 +
 +
== Integrate with Other Technologies ==
 +
The <code>onURIChange</code> event won't be sent if the <code>iframe</code> component contains a non-ZK page. For example, it won't be sent if it contains a PDF page.
  
 +
On the other hand, if you use other technologies to put a ZK page in an iframe, you can monitor the URL by writing a JavaScript method called <javadoc directory="jsdoc" method="onIframeURLChange(_global_.String, _global_.String)">_global_._global_</javadoc> as follows.
  
 +
<source lang="xml">
 +
//Part of your, say, PHP page
 +
<script type="text/script">
 +
function onIframeURLChange(uuid, url) {
 +
    do_whatever_you_need_in_the_technology_you_use(uuid, url);
 +
}
 +
</script>
 +
</source>
 +
 +
where <code>uuid</code> is the ID of the element that you can retrieve by <code>document.getElementById</code>, and <code>url </code>is the new URL that the iframe is navigated to. Notice that <code>url</code> includes the context path, while <javadoc method="getURI()">org.zkoss.zk.ui.event.URIEvent</javadoc> does ''not''.
  
 +
= Retrieving Component inside Iframe =
  
=Supported events=
+
When using <code>iframe</code>, the page is actually loaded into another browser window, aka., another desktop if a ZUML document is included.
  
{| border="1" | width="100%"
+
It is illegal to access components attached to other desktops<ref>For more information please refer to the [[ZK Developer's Reference/UI Composing/Component-based UI|Component-based UI]] section</ref>. If you want to retrieve component, you may use <javadoc>org.zkoss.zul.Include</javadoc> instead of <javadoc>org.zkoss.zul.Iframe</javadoc>. Or, you could use [[ZK Developer's Reference/Event Handling/Event Queues|Event Queues]] with the group scope. Of course, you could handle it manually by deliberately passing the information through session.
 +
 
 +
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
 +
 
 +
=Communication among iFrames without Server Push=
 +
{{versionSince| 5.0.4}}
 +
{{ZK_EE}}
 +
 
 +
If your application contains multiple desktops due to iframes in a portal layout it is now possible to communicate between these instances without the need for server push or timer. It thus minimizes the network traffic.
 +
 
 +
Since ZK 5.0.4, the concept of group has been introduced to enable the use of a group-scope event queue which facilitates easy communication between the instances. The code below demonstrates some examples:
 +
 
 +
<source lang="javascript" highlight="1">
 +
EventQueue que = EventQueues.lookup("groupTest", EventQueues.GROUP, true);
 +
 
 +
que.subscribe(new EventListener() {
 +
  public void onEvent(Event evt) {
 +
      o.setValue(o.getValue() + evt.getData() + "\n");
 +
  }
 +
});
 +
 
 +
void publish() {
 +
  String text = i.getValue();
 +
 
 +
  if (text.length() > 0) {
 +
      i.setValue("");
 +
      que.publish(new Event("onGroupTest", null, text));
 +
  }
 +
}
 +
</source>
 +
 
 +
For more information please take a look at [[ZK Developer's Reference/Event Handling/Event Queues|ZK Developer's Reference: Event Queues]].
 +
 
 +
=onload=
 +
 
 +
If you'd like to do something when iframe's content has been loaded, you could listen to the <code>onload</code> event. However, unlike onChange and others, you could not listen the widget-level event (<javadoc directory="jsdoc">zk.Event</javadoc> and listened by use of [[ZK Client-side Reference/General Control/Event Listening|Client-side Event Listening]]), because the onload event might be fired before the widget has been bound to DOM.
 +
 
 +
Rather, you shall use [[ZUML Reference/ZUML/Namespaces/Client Attribute|the client-attribute namespace]] to register a DOM-level listener as follows.
 +
 
 +
<source lang="xml">
 +
<iframe src="https://www.google.com" width="100%" height="300px"
 +
  xmlns:ca="client/attribute"
 +
  ca:onload="do_whater_you_want()"/>
 +
</source>
 +
 
 +
Notice that the registration of onload with the client-attribute namespace is DOM-level, so the <code>this</code> variable references to the DOM element (rather than the widget).
 +
 
 +
=Supported Events=
 +
 
 +
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
 
|-
 
|-
| None
+
| <center><code>onURIChange</code></center>
| None
+
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.URIEvent</javadoc>
 +
 
 +
Denotes the associated URI (<code>src</code>) has been changed by user.
 +
 
 +
Use <code>getURI()</code> to retrieve the URI being changed to.
 +
 
 
|}
 
|}
 +
*Inherited Supported Events: [[ZK_Component_Reference/Base_Components/HtmlBasedComponent#Supported_Events | HtmlBasedComponent]]
  
 
=Supported Children=
 
=Supported Children=
Line 31: Line 130:
 
  *NONE
 
  *NONE
  
=Use cases=
+
=Use Cases=
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Description !! Example Location
 
! Version !! Description !! Example Location
 
|-
 
|-
| 5.0+
+
| 3.6 or later
| &nbsp;
+
| Print Iframe Content
| &nbsp;
+
| [https://www.zkoss.org/forum/listComment/6599 http://www.zkoss.org/forum/listComment/6599]
 
|}
 
|}
  
 
=Version History=
 
=Version History=
 
+
{{LastUpdated}}
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
| 5.0.1
+
| &nbsp;
| 4/27/2010
+
| &nbsp;
| Initialization
+
| &nbsp;
 
|}
 
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Latest revision as of 09:43, 13 April 2022

Iframe

Employment/Purpose

The iframe component uses the HTML IFRAME tag to delegate a portion of the display to another URL. Though the appearance looks similar to the include component. The concept and meaning of the iframe component is different.

The content included by the include component is a fragment of the whole HTML page.

Because the content is part of the HTML page, the content is part of the desktop and you could access any components, if any, inside of the include component. The inclusion is done at the server, and the browser knows nothing about it. It means the URL specified by the src property could be any internal resource.

The content of the iframe component is loaded by the browser as a separate page. Because it is loaded as a separate page, the format of the content could be different from HTML. For example, you could embed an PDF file.

The embedding is done by the browser, when it interprets the HTML page containing the IFRAME tag. It also implies that the URL must be a resource that you can access from the browser.

Like the image and audio components, you could specify the dynamically generated content. A typical example is you could use JasperReport to generate a PDF report in a binary array or stream, and then pass the report to an iframe component by wrapping the result with the org.zkoss.util.media.AMedia class.

In the following example, we illustrate that you could embed any content by use of iframe, as long as the client supports its format.

Example

ZKComRef Iframe.png

<window id="win" title="This is an Iframe Demo!">
	<iframe style="width:99%; height:400px;border:3px inset;" src="iframe-target-url-here" />
</window>

Live iframe demo is available in the zk demo.

The onURIChange Event

When the user navigates the iframe component to another URL (or bookmark), an object of URIEvent is sent to the iframe component. This event is usually used to bookmark the status of the iframe component, such that the right content can be restored later.

Integrate with Other Technologies

The onURIChange event won't be sent if the iframe component contains a non-ZK page. For example, it won't be sent if it contains a PDF page.

On the other hand, if you use other technologies to put a ZK page in an iframe, you can monitor the URL by writing a JavaScript method called _global_.onIframeURLChange(String, String) as follows.

 //Part of your, say, PHP page
 <script type="text/script">
 function onIframeURLChange(uuid, url) {
     do_whatever_you_need_in_the_technology_you_use(uuid, url);
 }
 </script>

where uuid is the ID of the element that you can retrieve by document.getElementById, and url is the new URL that the iframe is navigated to. Notice that url includes the context path, while URIEvent.getURI() does not.

Retrieving Component inside Iframe

When using iframe, the page is actually loaded into another browser window, aka., another desktop if a ZUML document is included.

It is illegal to access components attached to other desktops[1]. If you want to retrieve component, you may use Include instead of Iframe. Or, you could use Event Queues with the group scope. Of course, you could handle it manually by deliberately passing the information through session.


  1. For more information please refer to the Component-based UI section

Communication among iFrames without Server Push

Since 5.0.4

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

If your application contains multiple desktops due to iframes in a portal layout it is now possible to communicate between these instances without the need for server push or timer. It thus minimizes the network traffic.

Since ZK 5.0.4, the concept of group has been introduced to enable the use of a group-scope event queue which facilitates easy communication between the instances. The code below demonstrates some examples:

EventQueue que = EventQueues.lookup("groupTest", EventQueues.GROUP, true);

que.subscribe(new EventListener() {
   public void onEvent(Event evt) {
      o.setValue(o.getValue() + evt.getData() + "\n");
   }
});

void publish() {
   String text = i.getValue();

   if (text.length() > 0) {
      i.setValue("");
      que.publish(new Event("onGroupTest", null, text));
   }
}

For more information please take a look at ZK Developer's Reference: Event Queues.

onload

If you'd like to do something when iframe's content has been loaded, you could listen to the onload event. However, unlike onChange and others, you could not listen the widget-level event (Event and listened by use of Client-side Event Listening), because the onload event might be fired before the widget has been bound to DOM.

Rather, you shall use the client-attribute namespace to register a DOM-level listener as follows.

<iframe src="https://www.google.com" width="100%" height="300px"
  xmlns:ca="client/attribute"
  ca:onload="do_whater_you_want()"/>

Notice that the registration of onload with the client-attribute namespace is DOM-level, so the this variable references to the DOM element (rather than the widget).

Supported Events

Name
Event Type
onURIChange
Event: URIEvent

Denotes the associated URI (src) has been changed by user.

Use getURI() to retrieve the URI being changed to.

Supported Children

*NONE

Use Cases

Version Description Example Location
3.6 or later Print Iframe Content http://www.zkoss.org/forum/listComment/6599

Version History

Last Update : 2022/04/13


Version Date Content
     



Last Update : 2022/04/13

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.