Converting our MyFaces 1.1.x + Tomcat 6 JSP webapps to ICEFaces + MyFaces 1.1.x + Facelets + Tomcat 6 webapps

<dependency>
	<groupId>org.icefaces</groupId>
	<artifactId>icefaces</artifactId>
	<version>1.6.1</version>
</dependency>

<dependency>
	<groupId>org.icefaces</groupId>
	<artifactId>icefaces-comps</artifactId>
	<version>1.6.1</version>
</dependency>

<dependency>
	<groupId>org.icefaces</groupId>
	<artifactId>icefaces-facelets</artifactId>
	<version>1.6.1</version>
</dependency>

<servlet>
	<servlet-name>Persistent Faces Servlet</servlet-name>
	<servlet-class>com.icesoft.faces.webapp.xmlhttp.PersistentFacesServlet</servlet-class>
	<load-on-startup> 1 </load-on-startup>
</servlet>

<servlet>
	<servlet-name>Blocking Servlet</servlet-name>
	<servlet-class>com.icesoft.faces.webapp.xmlhttp.BlockingServlet</servlet-class>
	<load-on-startup> 1 </load-on-startup>
</servlet>

<!-- Faces Servlet Mapping -->
<servlet-mapping>
	<servlet-name>Faces Servlet</servlet-name>
	<url-pattern>*.faces</url-pattern>
</servlet-mapping>

<!-- Persistent Faces Servlet Mapping -->

<servlet-mapping>
	<servlet-name>Persistent Faces Servlet</servlet-name>
	<url-pattern>*.iface</url-pattern>
</servlet-mapping>

<servlet-mapping>
	<servlet-name>Persistent Faces Servlet</servlet-name>
	<url-pattern>/xmlhttp/*</url-pattern>
</servlet-mapping>

<servlet-mapping>
	<servlet-name>Blocking Servlet</servlet-name>
	<url-pattern>/block/*</url-pattern>
</servlet-mapping>

<context-param>
	<param-name>javax.faces.DEFAULT_SUFFIX</param-name>
	<param-value>.xhtml</param-value>
</context-param>

<application>
	<view-handler>com.icesoft.faces.facelets.D2DFaceletViewHandler</view-handler>
</application>

This is a simple search and replace. All attributes of the tags are the same

5.2 Replace <n:exitDialog>

The exitDialog does not work with Icefaces. In order to replace this component, we have to do several things: stop including the behaviour.js javascript, replace the exitDialog with a ice:panelPopup + a separate exit button that triggers the dialog if necessary, and update the backing beans to be able to toggle the dialog.

Here is an example from the RCT:

<ice:menuItem
	value="Exit"
	action="#{catPage.exit}"
	styleClass="menuBarButton"
/>

...

<ice:panelPopup
	visible="#{catPage.showExitDialog}"
	rendered="#{catPage.showExitDialog}"
	styleClass="exitDialog"
>
	<f:facet name="header">
		You may have unsaved data!
	</f:facet>

	<f:facet name="body">
		<ice:panelGroup>
			<ice:commandButton
				value="Discard Changes & Exit"
				action="#{catPage.forceExit}"
				styleClass="warningDialogConfirm"
			/>

			<ice:commandButton
				value="Save Changes & Exit"
				action="#{catPage.saveAndExit}"
				styleClass="warningDialogConfirm"
			/>

			<ice:commandButton
				value="Cancel"
				action="#{catPage.closeExitDialog}"
				styleClass="warningDialogCancel"
			/>
		</ice:panelGroup>
	</f:facet>
</ice:panelPopup>

Pay special attention to the Bold Italicized text. The exit method checks to see if there are unsaved catalogs. If so, it doesn't exit, but instead toggles the showExitDialog property. Please review edu.nrao.sss.tools.resrccat.pagestate.CatalogsPage for the details of the backing bean methods. Of Primary interest is the ability for the saveAndExit and forceExit methods to redirect the user's browser to a new page after completing their actions.

It is also important to note that the visible and rendered attributes of the <ice:panelPopup> tag must both be set in order for the popup to operate as expectd!

5.3 Replace <n:floatingDialog>

In general, a very similar process can be used to replace the floatingDialog tags. Replace the dialog content itself with a panelPopup and create a new button or link that toggles a (newly made) backing bean property to display the dialog. Any cancel button in that dialog can just re-toggle the same property.

5.4 Update dialog CSS

The previous dialog tags rendered a wrapper div that contained a link and another div (that contained the content of the popup dialog). The wrapper div had this css styling: position: relative so that the position of the popup could be: position:absolute;top:0;left:0 and the dialog would popup on top of the link that opened it as expected.

When using a regular ice:commandLink and ice:panelPopup to acheive the same effect, we lack the wrapper div that had relative positioning. To compensate, you can wrap the link and popup tags in a div or span yourself and style the wrapper with relative positioning. There are examples of this in the RCT.

5.5 Replace <n:selectEnumItems>

The n:selectEnumItems tag no longer works (because of facelets). This is a fairly simple thing to fix.

NOTE: The following example is out dated. There is a better way to do this now. See the Errata secion and/or talk to Brian!

An example backing bean method from the RCT:

import edu.nrao.sss.util.EnumerationUtility;
import edu.nrao.sss.webapp.SelectItemCollectionFactory;
import javax.faces.model.SelectItem;

...

private static Collection<SelectItem> telescopeTypes = null;
public Collection<SelectItem> getAvailableTelescopeTypes()
{
	if (this.telescopeTypes == null)
	{
		this.telescopeTypes = SelectItemCollectionFactory.createFrom(
			EnumerationUtility.getSharedInstance().getSelectableSetFor(TelescopeType.class)
		);
	}

	return this.telescopeTypes;
}

And the associated XHTML:

<ice:selectOneMenu
	value="#{ma.telescope}"
	valueChangeListener="#{catPage.currentCatalogAction.catalogChanged}"
	partialSubmit="true"
>
	<f:selectItems value="#{ma.availableTelescopeTypes}"/>
</ice:selectOneMenu>

5.6 Replace Tomahawk tags

Tomahawk tags begin with t:. The 2 tomahawk tags that we use are t:div and t:fileUpload. Please review the Icefaces website for documentation on how to use their fileUpload tag. To replace t:div, simply remove the t:. We can use plain div tags now!

There are, unfortunately, some caveats to that. If the div contains a styleClass attribute, change it to class. If it has a rendered attribute, you must remove that attribute and wrap the div in a n:if tag to acheive the same effect. Depending on the context, other solutions may be available.

5.7 Replace Ajax4JSF tags

This can be more complicated. I'll cover a few common examples. You can replace a4j:commandXYZ with ice:commandXYZ as long as you remember to remove any oncomplete and reRender attributes of the tag. Please note any component that has an oncomplete attribute as these will require extra handling. Talk to Brian about them. You can replace most a4j:support tags by removing the tag entirely, changing its parent tag to the equivalent icefaces tag, and adding the partialSubmit="true" attribute to it. a4j:outputPanel, a4j:page, and a4j:status tags can just be removed.

Errata

• Don't forget to Remove the MyFacesExtensions filter and Ajax4jsf Filter from web.xml!
• you can replace <a4j:include viewId=...> with <ui:include src=...>
• If you are including a page, the page you include must also have all the xml namespaces defined. This may mean you need to add a wrapper div around the entire contents of the included file so that you can have a tag to stick the namespace definitions in.
• use and expand on the new edu.nrao.sss.webapp.SelectItemCollectionFactory when dealing with select menus of enumerations. If the enumeration you are dealing with is not present, add it.
• A quick note on Java Bean properties: icefaces does not like getters and setters that start with 2 capital letters. For instance, if you have a method getXYAndZ() and you access it in the xhtml via: #{bean.xYAndZ} icefaces may fail to resolve the property! To avoid this, follow the first letter in a bean property with a lower case letter. I.E. change the above to "getXyAndZ()" and it should work.