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 add scrollbars if the embedded page does not fit within the size of the iframe.

Basic functionalities #

Embedding remote web sites #

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 automatically 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 pattern: {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. Note: The url after the # will only be displayed after the page reloads. Links with this syntax will need to somehow force the page to reload.

Authentication #

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 previous 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):

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".

Basic Authentication #

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 Authentication 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 authentication, 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 the Firefox browser that has this feature enabled by default.

An IFrame will hide the main navigation in Internet Explorer #

This is a limitation of the Internet Explorer. The solution is to add another IFrame behind every element of the drop down menu of the navigation. A detailed description of the bug and the solution steps is located on JIRA.