JSF / JavaCareers Guidelines

During the JSF development of the JavaCareers pages, we've encountered some problems.
To avoid future JavaCareers/JSF problems you can find below some basic JSF guidelines.

Avoid duplicate JSF IDs, all JSF elements must have a unique ID, especially when you're using Struts tiles!
- We use the following syntax : pageName_JSFtype+SequenceNumber (see example below)

pageFooter.jsp

<f:subview id="pageFooter_subview1">
    <center>
	<h:panelGrid id="pageFooter_grid1"
                 columns="1"
                 styleClass="smalltext">
        <h:panelGroup id="pageFooter_panel1">
            <h:outputText id="pageFooter_t2" value="#{msgs.label_powered}"/>
            <h:outputText id="pageFooter_t3" value=" " />
            <h:outputLink id="pageFooter_l1" value="http://www.bejug.org/confluenceBeJUG/display/JAVAJOBS/Home" target="_blank">
                <h:outputText id="pageFooter_t4" value="#{msgs.label_bejug}"/>
            </h:outputLink>
            <h:outputText id="pageFooter_t5" value=" "/>
            <h:outputFormat id="pageFooter_f1" value="#{msgs.label_version}">
                <f:param id="pageFooter_p1" value="#{config.version}"/>
                <f:param id="pageFooter_p2" value="#{config.buildDate}"/>
            </h:outputFormat>
            <h:outputLink id="pageFooter_l2" value="http://sourceforge.net/tracker/?group_id=136441&atid=735895" target="_blank">
                <h:outputText id="pageFooter_t6" value="#{msgs.label_bug}"/>
            </h:outputLink>
            <h:outputText id="pageFooter_t7" value=" - "/>
            <h:outputLink id="pageFooter_l3" value="mailto:info@bejug.org?subject=JavaCareers">
                <h:outputText id="pageFooter_t8" value="#{msgs.label_contact}"/>
            </h:outputLink>
        </h:panelGroup>
	</h:panelGrid>
    </center>
</f:subview>

Use an outputFormat tag with parameters where applicable.
- In the PageFooter.jsp example the msgs.label_version has the following syntax :

label_version = (Version {0}, build on {1})

JSF page names use the camelNotation (like Java classes)
- JSF page names should be nouns, in mixed case with the first letter of each internal word capitalized.
  Also known as the CamelNotation (see also JJGuidelines, class names)

We've only one resource bundle and one location where this resource bundle gets defined!
- JavaCareers uses struts tiles for the composite pattern, the layout gets defined in the mainTemplate.jsp Struts page.
  This is where the I18N resource bundle is defined using a msgs variable name. All other JSF pages have now access to one resource bundle through the variable msgs.

mainTemplate.jsp

...
<f:loadBundle basename="org.bejug.common.view.jsf.resources.messages"
	          var="msgs" />
...

I18N resource bundles are accessed using the 'dot' notation, see example below.

<h:outputFormat id="pageFooter_f1" value="#{msgs.label_version}">

I18N labels have a predefined prefix and are seperated with an underscore.
We can logically group each type with a comment box and sub-groups with a none comment box.
- Label strings start with 'label'
- Button strings start with 'button'
- Navigation (links) start with 'nav'
- Page titles start with 'title'
- Items for a dropdown start with 'item''the type of the items''name'

messages_en.properties

########################################################################
#
# Labels text (have a label prefix)
#
########################################################################

#
# Footer messages
#
label_powered = Powered by
label_bejug = The Java Community - BeJUG
label_version = (Version {0}, build on {1})
...

The sequence for taglibs must be first URI and then the prefix. I know this is a trivial guideline but I like all JSF pages to be consistent

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>

A JSF form must have a suffix label named 'Form' (for example changePasswordForm) and all form elements are appended using a colon and the form field name (for example changePasswordForm:password). See also example below:

changePasswordContent.jsp

<h:form id="changePasswordForm">
    <h:panelGrid columns="2">
        <h:outputLabel for="changePasswordForm:password" value="#{messages.label_password}" />
        <h:panelGroup>
            <h:inputSecret id="password"
                value="#{userProfileForm.password}"
                binding="#{userProfileForm.passwordInput}"
                required="true" />
            <h:message for="changePasswordForm:password" styleClass="error" />
        </h:panelGroup>
        
        <h:outputLabel for="changePasswordForm:confirmpassword" value="#{messages.label_confirmpassword}" />
        <h:panelGroup>
            <h:inputSecret id="confirmpassword"
                validator="#{userProfileForm.validatePassword}"
                required="true" />
            <h:message for="changePasswordForm:confirmpassword" styleClass="error" />
        </h:panelGroup>
    </h:panelGrid>
...
</h:form>

JSF/JavaCareers Design Guidelines

The JSF package is located in the org.bejug.javacareers.jobs.view.jsf package.
This allows us (if needed) to introduce other view strategies later in the project.

The JSF view code uses coarse-grained interface services (aka. Session Facade, but defined using Spring beans) to access the non-view related business logic. Through the services the data access object (dao's) are also reached.

More guidelines will follow later.