The Iframe portlet makes it possible to embed another HTML page inside the current page. Furthermore the user can navigate through the embedded page without loosing the context of the portal page.
The Iframe portlet uses the HTML iframe tag that is part of HTML 4 and is supported in all major browsers. The iframe portlet will adjust to the size of the HTML page if that page is hosted in the same server. The browser will take care of making the adding scrollbars if the embedded page does not fit within the size of the iframe.
[size=x-large]Basic functionalities[/size]
[size=large]Embedding remote web sites[/size]
To show the basic functionality add an iframe portlet to any page of the portal that you can administer. Then click the configure button.
You'll see a form with a handful of options, for now just look at the Source URL field and write in it:
Go back to the full page and you'll be able to see the google search box inside your portlet. You can even do a search and have the search displayed within your portlet.
Embedding portal pages
Controlling the attributes of the iframe window
You can control the size, look and other attributes of the iframe using the HTML attributes field. This field is formed by a text area that can contain one attribute value per line of the form:
The supported attributes are:
* border
* bordercolor
* frameborder
* heightMaximized
* heightNormal
* hspace
* scrolling
* vspace
* width
Note: The size of the iframe portlet will automaticalle adjust to the size of the HTML page displayed if this page is in the same server. However, if you set the attributes width or height it won't automatically resize.
Add parameters dynamically
Any parameter can be passed to the iframe page from the URL of the page in which you have placed the iframe portlet. These parameters will follow the patter: {portlet namespace}iframe_{parameter name}={parameter value}. It is also mandatory to include the p_p_id parameter to make this work.
For example, this would be a valid url with a parameter called "example1", with the value "value1":
[http://localhost:8080/web/guest/home?p_p_id=48_INSTANCE_1Kv8&_48_INSTANCE_1Kv8_iframe_example1=value1]
Change the URL dynamically
The Page the iframe is displaying can be also changed from the URL using the anchor element. For example, if we have an iframe in the home page, this URL would use the iframe to display Google: [http://localhost:8585/web/guest/home#http://www.google.com]
Note: This url will be displayed in all the iframes we have in a page.
[size=large]Authentication[/size]
If the embedded web page requires authentication the iframe portlet can be configured to provide authentication information. This section describes the different options offered to the user.
Basic vs form based authentication
There are several way to provide the authentication information to the embedded page. The iframe portlet supports two of them:
* Basic authentication: This method is described in the HTTP specification. The user name and passwords are usually provided as HTTP headers but it's also possible to embed them in the URL with the syntax http://username:password@www.myurl.com This method is simple but it's not supported in many websites.
* Form authentication: Is the name given to websites that authenticate the user by making him fill in a form with his user name and password. It's the one used in most web sites. There are two variants of this: GET and POST. The first one sets the username and password in the URL and the second one in the body of the request. Usually they make little difference and both will probably work with any website.
Security note: Be aware that none of these methods are secure unless they are sent through an HTTPS connection. If you want to make sure that the user and password information cannot be seen by third parties only use authentication with sites that support HTTPS and use only URLs in the iframe that start with https:// Also if you use Basic authentication you'll have to use HTTPS to communicate with the Liferay portal because the user name and passwords will be included in the HTML of the page served to the user.
Automatic vs configured user name and password
Liferay provides two ways to retrieve the user name and passwords that will be used to authenticate against the embedded web page:
* Automatic: The user name and password of the current user that is viewing the page with the iframe portlet will be used. It's only supported by the 'basic authentication' method described in the previoues section.
* Configured: The administrator will configure a user name and password and they will be used for all users.
To use the automatic way just leave the 'user name' and 'passwords' fields blank. Otherwise fill them with the values that will be used for authentication
Note that the value of those fields is different depending on the type of authentication used:
* Basic: just write the username and passwords as they are
* Form: prefix the user name and password with the names of the fields for them in the form. For example:
User name: userName=myusername Password: userPass=mypassword
Hidden variables
When using form based authentication, the iframe portlet allows the administrator to configure a set of additional parameters that will be sent with the form. This parameters must be set in the 'Hidden Variables field and its format must be:
xxxx=blah;abc=formSubmit1
See an example below (By Ryan):
[img]http://dl.iteye.com/upload/picture/pic/43313/3241dc64-b3dd-3603-a904-3dda138ad34a.jpg[/img]
How to manually find out the authentication type supported by the web page to be embedded
Sometimes we don't know what type of authentication is supported by the application that will go inside the iframe. If we don't want to, or cannot afford to try out different configurations through the portal we can find out following this process.
Preparation
To follow the following example create an account here, if you don't have one already:
http://www.rsscalendar.com/rss/login.asp
For this example, I'm going to use username "liferay" and the password "test".
[size=large]Basic Authentication
[/size]
First we'll try form based auth.
1) Open a browser and write the following URL with valid user and passwords:
[http://myuser:mypassword@www.rsscalendar.com/rss/login.asp]
2) Now that you know this works, use the same information in the IFrame portlet. Source URL: http://www.rsscalendar.com/rss/login.asp Authentication Type: Basic Form Method: User Name: liferay Password: test
Form based Authentication
1) Create a file called form-auth.html on your desktop.
2) Input the following code into form-auth.html:
I got "UserName" and "UserPassword" from viewing source on http://www.rsscalendar.com/rss/login.asp. I also found out that the form was using method "post" and input type "submit" by viewing source.
3) Open up logintest.html, type in your new usename and password you just created. Hit Submit. You should now be logged in to rsscalendar.
4) Now that you know this works, use the same information in the IFrame portlet. Source URL: http://www.rsscalendar.com/rss/login.asp Authentication Type: Form Form Method: Post User Name: UserName=liferay Password: UserPassword=test
Notice that I put UserName=liferay instead of just 'liferay'. The reason for this is so the Iframe portlet knows what input names to use when it creates the form to submit.
How does it work?
When form based authentication is not used, the iframe portlet works in a very simple way. It just takes the configured URL and adds the authentication parameters if they were set.
When form based authentication is used, what the IFrame authentication does is make a first (hidden) request to a portal page that recreates a form and then submits it to the configured URL. To learn the details of this form take a look at the following file from Liferay's sources:
Troubleshooting
The web site takes the whole browser window instead of just the iframe
Some web sites have a security measure to avoid being inserted in frames or iframes. The use JavaScript to detect that they are in that situation and reload the page to use the whole browser window.
If that's your case you should not use that web site in an iframe unless you've got authorization from them. Once you get it, ask them for a URL that does work inside an iframe
Authentication does not work
Try authenticating manually using the process described in a previous section. Use the same user and password that the iframe portlet is using.
To find out which user and password the iframe portlet is using check:
* Basic authentication: look at the HTML source code of the page with the portlet and check the SRC attribute of the IFRAME tag.
* Form authentication: Switch the configuration to basic auth and follow the above procedure. Then set the configuration back to Form authentication.
Basic Authenticacion in iexplorer does not work
Corné|Corné 12:27, 13 May 2008 (PDT) Since IE 7 this is default behaviour; http://support.microsoft.com/kb/834489 Setting the header with Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== would be a better solution something like;
Maybe is your navigator who does not permit basic autentication, to find out if it does, look at windows registry for
HKEY_LOCALMACHINE\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_HTTP_USERNAME_PASSWORD_DISABLE\iexplore.exe HKEY_LOCALMACHINE\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_HTTP_USERNAME_PASSWORD_DISABLE\explore.exe
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_HTTP_USERNAME_PASSWORD_DISABLE\iexplore.exe HKEY_CURRENT_USER\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_HTTP_USERNAME_PASSWORD_DISABLE\explore.exe
they should exist and have a REG_DWORD value of 0x00000000(0), if not, create or change their values to permit links in the form of http://user:password@www.domain.com
you can also try first with firefox navigator that has this feature enabled by default.
The Iframe portlet uses the HTML iframe tag that is part of HTML 4 and is supported in all major browsers. The iframe portlet will adjust to the size of the HTML page if that page is hosted in the same server. The browser will take care of making the adding scrollbars if the embedded page does not fit within the size of the iframe.
[size=x-large]Basic functionalities[/size]
[size=large]Embedding remote web sites[/size]
To show the basic functionality add an iframe portlet to any page of the portal that you can administer. Then click the configure button.
You'll see a form with a handful of options, for now just look at the Source URL field and write in it:
[http://www.google.com]
Go back to the full page and you'll be able to see the google search box inside your portlet. You can even do a search and have the search displayed within your portlet.
Embedding portal pages
Controlling the attributes of the iframe window
You can control the size, look and other attributes of the iframe using the HTML attributes field. This field is formed by a text area that can contain one attribute value per line of the form:
attribute-name=attribute-value
The supported attributes are:
* border
* bordercolor
* frameborder
* heightMaximized
* heightNormal
* hspace
* scrolling
* vspace
* width
Note: The size of the iframe portlet will automaticalle adjust to the size of the HTML page displayed if this page is in the same server. However, if you set the attributes width or height it won't automatically resize.
Add parameters dynamically
Any parameter can be passed to the iframe page from the URL of the page in which you have placed the iframe portlet. These parameters will follow the patter: {portlet namespace}iframe_{parameter name}={parameter value}. It is also mandatory to include the p_p_id parameter to make this work.
For example, this would be a valid url with a parameter called "example1", with the value "value1":
[http://localhost:8080/web/guest/home?p_p_id=48_INSTANCE_1Kv8&_48_INSTANCE_1Kv8_iframe_example1=value1]
Change the URL dynamically
The Page the iframe is displaying can be also changed from the URL using the anchor element. For example, if we have an iframe in the home page, this URL would use the iframe to display Google: [http://localhost:8585/web/guest/home#http://www.google.com]
Note: This url will be displayed in all the iframes we have in a page.
[size=large]Authentication[/size]
If the embedded web page requires authentication the iframe portlet can be configured to provide authentication information. This section describes the different options offered to the user.
Basic vs form based authentication
There are several way to provide the authentication information to the embedded page. The iframe portlet supports two of them:
* Basic authentication: This method is described in the HTTP specification. The user name and passwords are usually provided as HTTP headers but it's also possible to embed them in the URL with the syntax http://username:password@www.myurl.com This method is simple but it's not supported in many websites.
* Form authentication: Is the name given to websites that authenticate the user by making him fill in a form with his user name and password. It's the one used in most web sites. There are two variants of this: GET and POST. The first one sets the username and password in the URL and the second one in the body of the request. Usually they make little difference and both will probably work with any website.
Security note: Be aware that none of these methods are secure unless they are sent through an HTTPS connection. If you want to make sure that the user and password information cannot be seen by third parties only use authentication with sites that support HTTPS and use only URLs in the iframe that start with https:// Also if you use Basic authentication you'll have to use HTTPS to communicate with the Liferay portal because the user name and passwords will be included in the HTML of the page served to the user.
Automatic vs configured user name and password
Liferay provides two ways to retrieve the user name and passwords that will be used to authenticate against the embedded web page:
* Automatic: The user name and password of the current user that is viewing the page with the iframe portlet will be used. It's only supported by the 'basic authentication' method described in the previoues section.
* Configured: The administrator will configure a user name and password and they will be used for all users.
To use the automatic way just leave the 'user name' and 'passwords' fields blank. Otherwise fill them with the values that will be used for authentication
Note that the value of those fields is different depending on the type of authentication used:
* Basic: just write the username and passwords as they are
* Form: prefix the user name and password with the names of the fields for them in the form. For example:
User name: userName=myusername Password: userPass=mypassword
Hidden variables
When using form based authentication, the iframe portlet allows the administrator to configure a set of additional parameters that will be sent with the form. This parameters must be set in the 'Hidden Variables field and its format must be:
xxxx=blah;abc=formSubmit1
See an example below (By Ryan):
[img]http://dl.iteye.com/upload/picture/pic/43313/3241dc64-b3dd-3603-a904-3dda138ad34a.jpg[/img]
How to manually find out the authentication type supported by the web page to be embedded
Sometimes we don't know what type of authentication is supported by the application that will go inside the iframe. If we don't want to, or cannot afford to try out different configurations through the portal we can find out following this process.
Preparation
To follow the following example create an account here, if you don't have one already:
http://www.rsscalendar.com/rss/login.asp
For this example, I'm going to use username "liferay" and the password "test".
[size=large]Basic Authentication
[/size]
First we'll try form based auth.
1) Open a browser and write the following URL with valid user and passwords:
[http://myuser:mypassword@www.rsscalendar.com/rss/login.asp]
2) Now that you know this works, use the same information in the IFrame portlet. Source URL: http://www.rsscalendar.com/rss/login.asp Authentication Type: Basic Form Method: User Name: liferay Password: test
Form based Authentication
1) Create a file called form-auth.html on your desktop.
2) Input the following code into form-auth.html:
<form action="[http://www.rsscalendar.com/rss/login.asp"] method="post">
User name:
<input name="UserName" type="text" value="">
Password:
<input name="UserPassword" type="text" value="">
<input type="submit">
</form>
I got "UserName" and "UserPassword" from viewing source on http://www.rsscalendar.com/rss/login.asp. I also found out that the form was using method "post" and input type "submit" by viewing source.
3) Open up logintest.html, type in your new usename and password you just created. Hit Submit. You should now be logged in to rsscalendar.
4) Now that you know this works, use the same information in the IFrame portlet. Source URL: http://www.rsscalendar.com/rss/login.asp Authentication Type: Form Form Method: Post User Name: UserName=liferay Password: UserPassword=test
Notice that I put UserName=liferay instead of just 'liferay'. The reason for this is so the Iframe portlet knows what input names to use when it creates the form to submit.
How does it work?
When form based authentication is not used, the iframe portlet works in a very simple way. It just takes the configured URL and adds the authentication parameters if they were set.
When form based authentication is used, what the IFrame authentication does is make a first (hidden) request to a portal page that recreates a form and then submits it to the configured URL. To learn the details of this form take a look at the following file from Liferay's sources:
portal-web/docroot//html/portlet/iframe/proxy.jsp
Troubleshooting
The web site takes the whole browser window instead of just the iframe
Some web sites have a security measure to avoid being inserted in frames or iframes. The use JavaScript to detect that they are in that situation and reload the page to use the whole browser window.
If that's your case you should not use that web site in an iframe unless you've got authorization from them. Once you get it, ask them for a URL that does work inside an iframe
Authentication does not work
Try authenticating manually using the process described in a previous section. Use the same user and password that the iframe portlet is using.
To find out which user and password the iframe portlet is using check:
* Basic authentication: look at the HTML source code of the page with the portlet and check the SRC attribute of the IFRAME tag.
* Form authentication: Switch the configuration to basic auth and follow the above procedure. Then set the configuration back to Form authentication.
Basic Authenticacion in iexplorer does not work
Corné|Corné 12:27, 13 May 2008 (PDT) Since IE 7 this is default behaviour; http://support.microsoft.com/kb/834489 Setting the header with Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== would be a better solution something like;
<%
String userName = StringPool.BLANK;
String passWord = StringPool.BLANK;
for (int i = 0; i < hiddenVariablesArray.length; i++) {
String hiddenValue = StringPool.BLANK;
int pos = hiddenVariablesArray[i].indexOf(StringPool.EQUAL);
if (pos != -1) {
hiddenValue = hiddenVariablesArray[i].substring(pos + 1, hiddenVariablesArray[i].length());
if(i==0)
userName = hiddenValue;
if(i==1)
passWord = hiddenValue;
}
}
response.setHeader("Authorization", "Basic "+com.liferay.portal.kernel.util.Base64.encode( new String(userName+":"+passWord).getBytes()));
response.sendRedirect(src);
response.flushBuffer();
%>
Maybe is your navigator who does not permit basic autentication, to find out if it does, look at windows registry for
HKEY_LOCALMACHINE\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_HTTP_USERNAME_PASSWORD_DISABLE\iexplore.exe HKEY_LOCALMACHINE\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_HTTP_USERNAME_PASSWORD_DISABLE\explore.exe
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_HTTP_USERNAME_PASSWORD_DISABLE\iexplore.exe HKEY_CURRENT_USER\SOFTWARE\Microsoft\Internet Explorer\Main\FeatureControl\FEATURE_HTTP_USERNAME_PASSWORD_DISABLE\explore.exe
they should exist and have a REG_DWORD value of 0x00000000(0), if not, create or change their values to permit links in the form of http://user:password@www.domain.com
you can also try first with firefox navigator that has this feature enabled by default.