MyFaces Core
  1. MyFaces Core
  2. MYFACES-734

Documentation bugs, as pointed out by Marty Hall

    Details

    • Type: Bug Bug
    • Status: Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None

      Description

      This has been posted on the mailing list quite some time ago, and somehow we forgot about it. This is why I am opening a jira issue on this.

      regards,

      Martin

      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.,

        Activity

        No work has yet been logged on this issue.

          People

          • Assignee:
            Matthias Weßendorf
            Reporter:
            Martin Marinschek
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:

              Development