Ooops, the last message got cut off. Here is the full version:
=====================================
I am currently switching over my JSF tutorial
(http://www.coreservlets.com/JSF-Tutorial/) from the Sun Reference
Implementation to MyFaces, updating it significantly, and adding in info on:
- MyFaces setup and configuration
- MyFaces/Tomahawk custom validators
- MyFaces/Tomahawk custom components
In the process, I uncovered a few errors or omissions in the current
MyFaces documentation. I mention all of these things in my tutorial, but I
figured the MyFaces team would like to know. Here's what I noticed so far:
1) http://myfaces.apache.org/gettingstarted.html: Required JAR files
A) The docs say that commons-codec-1.2.jar is required only if you
are uploading files, but most of my apps crash when that JAR file is
omitted. These same apps run fine in the Sun RI.
B) The docs do not mention jstl.jar.
First of all, some I18N code crashes if jstl.jar is not
included. For example, if I do this:
<f:view locale="#{facesContext.externalContext.request.locale}">
<f:loadBundle basename="messages" var="msgs"/>
it crashes if jstl.jar is not included, even though JSTL is not being
explicitly used anywhere. The same code runs fine in the Sun RI.
Secondly, since JSTL is supposed to be bundled with JSTL,
IMHO you should mention jstl.jar on the gettingstarted.html page anyhow.
C) The docs *do* mention commons-validator.jar but *do not*
mention jakarta-oro.jar. But the MyFaces validators that use regular
expressions (validateEmail, validateRegExpr, etc.) crash if jakarta-oro.jar
is not included.
D) Since you are mentioning some non-JSF-standard stuff here
anyhow, you might as well mention myfaces-extensions.jar, IMHO.
2) General configuration and documentation.
A) File extension. All of the examples use ".jsf" as the file
extension. I actually prefer that over ".faces", but since ".faces" is much
more standard and is what the JSF spec and all the JSF books use, IMHO you
should highlight this change to users and remind them how to edit web.xml
to change the file extension back.
B) Similarly, all the examples use examples-config.xml as the
configuration file. Again, newbie users will be confused since they will be
expecting faces-config.xml. IMHO you should highlight the change and remind
users how to edit web.xml to change the name of the config file.
C) The TLD Javadocs for the h: and f: libraries
(http://myfaces.apache.org/tlddoc/core/) is pretty poor. In contrast, the
TLD Javadocs for the Sun RI
(http://java.sun.com/j2ee/javaserverfaces/1.1/docs/tlddocs/) is pretty
good. Since they refer to the identical tag libraries, is it kosher for you
to just grab the Sun docs and use it as a starting point? Or just have your
link point there?
3) Custom components and validators.
A) I could not see where you document *anywhere* that you need the
filter and filter-mapping definitions in web.xml in order to use the custom
components that use JavaScript. IMHO you need to really highlight this or
newbie users will never figure it out. I also think you should clearly say
that the url-pattern of the filter-mapping needs to match the url-pattern
of servlet-mapping. Otherwise, users who changed the file extension from
.jsf to the more standard .faces will cut-and-paste the filter and
filter-mapping definitions from myfaces-examples/WEB-INF/web.xml, and it
won't work.
B) In myfaces-examples, validate.jsf crashes because
jakarta-oro.jar is not in WEB-INF/lib.
C) Most of the online docs for the custom components (e.g.,
http://myfaces.apache.org/tomahawk/dataList.html) use "t" as the prefix,
but the top-level page (http://myfaces.apache.org/tomahawk/overview.html)
and the myfaces-examples app use "x". Obviously, it is arbitrary, but you
might as well be consistent to avoid confusing newbies. I personally prefer
"x".
D) I couldn't find any documentation on how to enable client-side
validation in JavaScript for the custom validators.
4) Tiles.
A) There is a typo in #1 of
http://myfaces.apache.org/tomahawk/tiles.html: the "/" is missing from
</view-handler>, so users who simply cut-and-paste will get errors.
B) The docs say to use tiles.xml as the configuration file. This
is perfectly fine, of course, but I thought in Struts it was normal to call
it tiles-defs.xml, so you might as well be consistent so that users can
just copy over their Tiles definitions files (or at least highlight a bit
more prominently that it is configurable in web.xml).
C) I had trouble following the explanation of what happens when
your tiles definitions are called xxxxx.tiles. Since the name is arbitrary
in Struts, this could probably use some extra explanation.
I find that many (most?) of my clients are switching over from the Sun RI
to MyFaces, so I am pleased to see all the good stuff coming out in
MyFaces. Thanks!
Cheers-
- Marty
