myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marty Hall <h...@coreservlets.com>
Subject Errors in MyFaces Documentation
Date Wed, 31 Aug 2005 20:39:22 GMT
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 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, 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.,


Mime
View raw message