Mixing JSF and HTML

WARNING: This blog entry was imported from my old blog on blogs.sun.com (which used different blogging software), so formatting and links may not be correct.

A subject that comes up regularly is how to mix HTML with JSF. There are several gotchas and limitations you need to be aware of.

1. The "content inter-weaving problem". The issue here is that if you mix and match JSF components and normal "plaintext", these are processed separately, and it's possible for the text to appear out-of-sync with the component. See this article for more information. However, the good news is that this issue is fixed in JSF 1.2! (Creator however is still using JSF 1.1; JSF 1.2 is not out yet.) You need to be aware of this issue, and obviously test your application thoroughly. The problem does not show up
   at designtime in Creator because we don't process the page using the normal JSP engine.
   
   
   
   • You can use a <f:verbatim> tag around your markup to make it "JSF friendly". This will force the embedded text to be processed by JSF rather than the JSP handler, so the right thing will happen.
     
   
   
   • In Creator 2 you can also use the <ui:markup> component. It's easier to use than <f:verbatim> for some use cases. It's in the Advanced palette.
     
   
   




2. Components that render their own children frequently don't handle HTML child content. (Examples of these are the Data Table, and the Panel Grid components.) These are the UIComponents that return true from getRendersChildren.
   These components specifically state that they want to handle rendering of their children themselves, and unless they
   are really careful, they won't pick up the HTML markup children nodes (whereas the standard child iteration used for
   most components does get this right.)
   Thus, for these components you need to resort to the <f:verbatim> technique again.
   




3. 
   By now you may wonder why you wouldn't ALWAYS just put <f:verbatim> around your HTML tags - and all your problems would be solved. The problem is that what verbatim does what its name suggests - it renders its child content verbatim. That means you don't get to put other JSF components inside of it! You'll see your JSF tags emitted as text. In other words, you can't freely insert <div> tags around your JSF content to do normal HTML page layouts.
   




4. 
   Your HTML needs to be well formed XHTML. This isn't necessarily a JSF requirement, although it should be noted JSF emits XHTML, not HTML. However, Creator requires this. Specifically this means that you need to remember to close your tags - I've often seen people write <br> which is invalid XHTML. It needs to be <br/>. As another example, remember that your tags need to be lowercase - don't insert <STYLE>color:blue</STYLE>.
   




5. 
   The way you actually add HTML to your web pages is to switch to the JSP view and edit away.
   However, note that you don't get to write plain HTML there, because you're actually editing an XML-formatted JSP
   file. Tags work the same way as in HTML - you can for example add <hr> to add a horizontal ruler.
   But entities are different. They need to be "XML escaped". If you want to write the HTML entity for the Spanish n for example,
   ñ, you cannot simply write ñ. You have to replace the & with &. Thus, if you want the page to render in the browser as Piña Colada, in HTML you would have had to type, Piñna Colada, but in the JSP file you need to escape the & such that you end up with Piña Colada.
   

With all those potential problems, you may wonder why you should bother with HTML at all?
It would be ideal if you didn't have to.
However, if you restrict yourself to standard JSF components there is simply too much markup you cannot get to. For example, you cannot add a horizontal ruler since there's no component for that. In Creator 2 we have a new component library which adds a wide array of new components.

However, there are two remaining areas where you might find yourself resorting to HTML.

• Flexible layouts. If you want to achieve a really advanced layout that offers good resize behavior etc. you may need to resort to old-school HTML tables with rowspans and colspans. However, I urge you to consider using CSS for your layouts instead. It may be a bit harder at first, but it will pay off. True, CSS is not supported well in older browsers, but many of these older browsers aren't supported for similar reasons in the existing markup rendered for many components already.




• Pre-existing content. You may have existing HTML that you want to reuse directly - perhaps it was crafted by a web designer and you want the same look in your JSF app with no rewrite effort. You can import these into Creator using File | Add Existing Item. The screenshot on the right for example shows the java.net page imported into Creator. The import mechanism will not catch all the gotchas above however so you need to Test, Test, Test.

As should be evident from the gotchas list however, you need to consider this carefully.