myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Marinschek <martin.marinsc...@gmail.com>
Subject Re: Resend: Errors in MyFaces Documentation
Date Wed, 31 Aug 2005 20:54:25 GMT
Thanks,

it's very very good to have that kind of feedback from someone
starting off at the beginning with MyFaces.

Can I kindly ask you to do even more and file a jira-bug issue on
this? I think this should by no means get lost!

regards,

Martin

On 8/31/05, Marty Hall <hall@coreservlets.com> 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

Mime
View raw message