P.S.: the link to our issue tracking system: http://myfaces.apache.org/issue.html
On 8/31/05, Marty Hall <[EMAIL PROTECTED]> wrote: > 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 > > -- http://www.irian.at Your JSF powerhouse - JSF Trainings in English and German
