Exemple de page

<%@include file="_include.jsp"%>
<e:page
    stringsVar="msgs"
    menuItem="preferences"
    locale="#{sessionController.locale}"
    authorized="#{preferencesController.pageAuthorized}">
  <%@include file="_navigation.jsp"%>
  <h:form id="preferencesForm">
    <e:section value="#{msgs['PREFERENCES.TITLE']}" />
    <e:messages />
    <e:panelGrid columns="2">
      <e:outputLabel
          for="locale"
          value="#{msgs['PREFERENCES.TEXT.LANGUAGE']}" />
      <h:panelGroup>
        <e:selectOneMenu
            id="locale"
            onchange="submit();"
            value="#{preferencesController.locale}"
            converter="#{localeConverter}" >
          <f:selectItems
              value="#{preferencesController.localeItems}" />
        </e:selectOneMenu>
        <e:commandButton
            value="#{msgs['_.BUTTON.CHANGE']}"
            id="localeChangeButton" />
      </h:panelGroup>
    </e:panelGrid>
  </h:form>
  <script type="text/javascript">
    hideButton("preferencesForm:localeChangeButton");
  </script>
</e:page>

Dans la page ci-dessus :

• la balise JSP <%@include file="_include.jsp"%> permet d'inclure toutes les librairies nécessaires (voir plus loin).
• La balise JSF <e:page> se charge de la mise en forme globale, que l'on soit en servlet ou en portlet.
• La balise JSP <%@include file="_navigation.jsp"%> permet d'inclure la barre de navigation, commune à toutes les pages.
• La balise JSF <e:section> affiche le titre de la page.
• La balise JSF <h:form> encadre un formulaire.
• La balise JSF <e:outputLabel> affiche le label d'un formulaire, celui qui possède l'identifiant locale.
• La balise JSF <e:selectOneMenu> propose un choix simple de valeurs dans une boite déroulante.
• La balise JSF <f:selectItems> renseigne la balise précédente sur les choix possibles, fournis par la méthode getLocaleItems() du bean preferencesController.
• La balise JSF <e:commandButton> est un bouton de soumission du formulaire. Lors de la soumission du formulaire, la méthode setLocale() du bean preferencesController est appelée avec la valeur sélectionnée dans la boite déroulante.

Syntaxe EL

JSF dispose d'un Expressions Language (EL) qui lui est propre. Syntaxiquement différent de l'EL de JSP 2.0. Il est utilisable dans les attributs des taglibs JSF. Il permet d'accéder en lecture ou en écriture à des propriétés du contrôleur (dans la mesure où celui-ci implémente des getters/setters sur ses propriétés). Il permet aussi d'invoquer une action du contrôleur (méthode sans paramètres qui renvoie une chaîne).

La syntaxe de base est

#{beanName.propertyName}

ou

#{beanName.methodName}

.Il est possible d'accéder à des objets récursivement, par exemple :

#{homeController.context.name}

Il est possible d'accéder à des éléments de tableaux ou de Map, par exemple :

#{tableau[1]}
#{hash.key}
#{hash["key"]}
#{hash[keyvar]}

(dans ce dernier exemple keyvar est évalué avant de retrouver l'entrée dans la table hash). Certains tableaux associatifs sont définis par défaut : param, header, cookie, etc.

On peut également utiliser quelques opérateurs logiques (and, or, not, empty, ...) ainsi que la plupart des opérateurs mathématiques.

Navigation entre les pages

La navigation entre les pages de l'application est faite en JSF à l'aide de règles de navigation écrites en XML, définies dans esup-commons par convention dans le fichier /properties/jsf/navigation-rules.xml.

Cette approche permet de bien dissocier les contrôleurs de la navigation en elle-même. Quand on appelle une méthode d'un contrôleur, par exemple au moment de la validation d'un formulaire, cette méthode (callback) renvoie une simple chaîne de caractères qui sera utilisée par JSF pour trouver la règle de navigation correspondante dans le fichier /properties/jsf/navigation-rules.xml.

Voici ci-dessous un exemple de règle de navigation :

<navigation-rule>
  <display-name>administrators</display-name>
  <from-view-id>/stylesheets/administrators.jsp</from-view-id>
  <navigation-case>
    <from-outcome>addAdmin</from-outcome>
    <to-view-id>/stylesheets/administratorAdd.jsp</to-view-id>
  </navigation-case>
  <navigation-case>
    <from-outcome>deleteAdmin</from-outcome>
    <to-view-id>
      /stylesheets/administratorDelete.jsp
    </to-view-id>
  </navigation-case>
</navigation-rule>

La balise from-view-id est facultative. Elle donne la vue (page) à partir de laquelle les règles de navigation vont s'appliquer. Si elle n'est pas présente, la règle est potentiellement applicable depuis toutes les pages de l'application.

Note : La vue est techniquement une page JSP mais l'utilisateur accède à des vues dont l'extension est .faces (paramétrage du fichier web.xml). Le noeud navigation-case permet de définir une règle de navigation :

• from-outcome est l'action de l'utilisateur. Cette action peut être définie « en dur » dans la page JSP (par ex. <h:commandButton value="suivant" action="next"/>) ou bien être le résultat de l'exécution d'une méthode d'un bean contrôleur de l'application (par ex. <h:commandButton value="suivant" action="#{controller.value}"/>).
• to-view-id donne la page de destination.
• <redirect /> peut être utilisé pour indiquer que l'affichage de la page de destination doit être fait sous forme d'une redirection HTTP (code HTTP 302). Cette balise doit être utilisée pour protéger l'utilisateur des effets de soumission multiple des formulaires à l'aide des boutons « Page précédente » et « Page suivante » des navigateurs.
• Il est parfois complexe (et peu confortable) d'éditer les règles de navigation « à la main ». On peut alors utiliser des outils graphiques, tel Exadel.

Protection des pages JSP

Les pages JSP ne devraient pas être accessibles directement. En effet, pour accéder aux vues on utilise l'extension .faces pour activer le filtreMyFaces. Une solution pour interdire l'accès aux JSP consiste à définir une contrainte de sécurité dans le /webapps/WEB-INF/web.xml. On utilisera par exemple :

<security-constraint>
  <display-name>Protect the raw JSP pages</display-name>
  <web-resource-collection>
    <web-resource-name>Raw JSF JSP Pages</web-resource-name>
    <url-pattern>/stylesheets/administrators.jsp</url-pattern>
    <url-pattern>/stylesheets/administratorsAdd.jsp</url-pattern>
    <url-pattern>/stylesheets/administratorsDelete.jsp</url-pattern>
  </web-resource-collection>
  <auth-constraint>
    <description>No roles, so no direct access</description>
  </auth-constraint>
</security-constraint>\\

Bibliothèques utilisées

esup-commons utilise très communément les deux tabligs prévues par la spécification JSF (jsf/core et jsf/html) ainsi que les bibliothèques JSF esup-commons (cf. ci-dessous) et Tomahawk (http://myfaces.apache.org/tomahawk/).

Afin de ne pas avoir à redéfinir ces bibliothèques dans toutes les pages de votre application, esup-commons est livré avec le fichier _include.jsp à inclure dans l'entête de vos pages JSP, de cette manière :

<%@include file="_include.jsp"%>

Le contenu de ce fichier est le suivant :

<%@ page language="java"contentType="text/html; charset=ISO-8859-1"pageEncoding="ISO-8859-1"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://myfaces.apache.org/tomahawk" prefix="t" %>
<%@ taglib uri="http://commons.esup-portail.org" prefix="e"%>

Les tags commençant par <f: et <h: sont donc ceux de MyFaces (l'implémentation JSF de Apache), ceux commençant par <t: sont ceux de Tomahawk (les extensions de MyFaces) et ceux commençant par <e: ceux de esup-commons.

Page d'accueil de l'application

La page d'accueil de votre application se configure différemment suivant que votre application sera utilisée en mode servlet ou en mode portlet.

En mode servlet

En mode servlet, esup-commons propose par défaut une page index.jsp qui fait une redirection vers stylesheets/welcome.faces.

Il est possible de surcharger cette page dans votre application.

En mode portlet

En mode portlet on utilise le paramètre default-view de la portlet org.esupportail.commons.web.portlet.FacesPortlet dont la définition est présente dans le fichier /webapps/WEB-INF/portlet.xml.

Exemple :

<portlet>
  <portlet-name>esup-formation</portlet-name>
  <portlet-class>
    org.esupportail.commons.web.portlet.FacesPortlet
  </portlet-class>
  <init-param>
    <name>default-view</name>
    <value>/stylesheets/welcome.jsp</value>
  </init-param>
  ...
</portlet>