Migrating ADF Faces app to use Facelets

[Frank Felix Debatin]

Hi, 

finally I managed to migrate our ADF Faces app to use facelets. Ton of work,
but it went smoothly and really pays off, making the page writing much more
clean and powerful. 

What a wonderful combination!!!

Here is a small migration guide for those who intend to do the same (note:
I'm a Facelets beginner so there might be alternatives or better solutions):

1. Get the ADF Facelets contribution on the Facelets website and precisely
follow the instructions provided there. I ended with the following entries
in web.xml:

  <context-param>
 <param-name>oracle.adf.view.faces.ALTERNATE_VIEW_HANDLER
</param-name>
 <param-value>com.sun.facelets.FaceletViewHandler
</param-value>
  </context-param>
        
  <context-param>
    <param-name>facelets.DEVELOPMENT</param-name>
    <param-value>true</param-value>
  </context-param>

  <context-param>
    <param-name>facelets.VIEW_MAPPINGS</param-name>
    <param-value>*.xhtml</param-value>
  </context-param>

  ...

  <servlet-mapping>
        <servlet-name>faces</servlet-name>
        <url-pattern>/faces/*</url-pattern>
  </servlet-mapping> 

2. Include the XML name spaces in your pages as follows (and don't forget to
change the extension .xhtml if you have the recommended web.xml
configuration)

<af:document
   xmlns:h="http://java.sun.com/jsf/html";
   xmlns:f="http://java.sun.com/jsf/core";
    xmlns:ui="http://java.sun.com/jsf/facelets";
    xmlns:f="http://java.sun.com/jsf/core";
    xmlns:af="http://xmlns.oracle.com/adf/faces";
    title="Hello World">
   <af:form>
     Hello World!
  </af:form>
</af:document>

3. Directly replace <af:forEach> tags with <c:forEach>. The <af:forEach>
tags are not provided in the contributed tag library, but the <c:forEach>
worked fine wherever I substituted them. 

4. Replace <af:region> with <ui:include>, providing a src attribute pointing
to the page instead of the old region attributes. (Consider <ui:decorate> as
an alternative if you like.) This requires some manual rewriting. The region
<af:attribute>s need to be replaces by include <ui:param>s. Get rid of the
"var." in the former region definition files. Consider surrounding the
region definition files with <ui:composition>. 

5. (Optionally - cleaner). Get rid of <f:verbatim> by writing straight
inline HTML.

6. (Optionally - cleaner). Replace <af:outputFormatted> with <af:outputText>
and HTML markup for user supplied values, so user-supplied markup is
filtered out.

7. Take care not to include any non-ADF stuff such as inline text or markup
in ADF tables, including the "details". This will cause an ugly stack trace
that completely messes up the involved session. I didn't encounter this
problem with any other of the ADF tags.

8. Entities: It seems that inline HTML entities need to escaped such as:
&amp;nbsp; (for the non-breakable backspace).

HTH someone.
Frank Felix