Lutece : guide développeur
Créer une application Front Office (XPage)
Une XPage est une page spéciale qui ne fait pas partie de l'arborescence des pages construites avec des portlets. Elle est autonome et s'appelle en utilisant le parametre page comme suit :
Portal.jsp?page=ma_xpageCe composant est typiquement destiné à réaliser des applications fonctionnant au sein du portail.
Implémentation de base
La création d'un XPage nécessite seulement deux actions :
- la création d'une classe Java qui implemente l'interface XPageApplication
- la déclaration de la XPage dans le fichier xml du plugin
Implémentation de l'interface XPageApplication
L'implementation de l'interface XPageApplication ne nécessite que de définir la seule méthode suivante:
XPage getPage( HttpServletRequest request, int nMode, Plugin plugin)Dans le chapitre suivant, plusieurs implémentations sont présentées dans le cadre d'un plugin HelloWorld.
Déclaration dans le fichier XML du plugin
La déclaration doit se faire comme suit :
<applications>
<application>
<application-id>mypage</application-id>
<application-class>fr.paris.lutece.plugins.myplugin.web.MyApp </application-class>
</application>
<applications>Principe de mise en oeuvre du modèle MVC
La framework MVC, évoqué précédemment dans le livre, propose une implémentation MVCApplication de l'interface XPageApplication offrant des mécanismes permettant de découper les fonctions selon le pattern Modèle-Vue-Controleur.
Le point d'entrée de la XPage joue le rôle de contrôleur. C'est la classe MVCApplication qui prend en charge cette fonction en implémentant la méthode getPage de l'interface.
Les actions et les vues sont désignées par des annotations @Action et @View.
Le contrôleur dispatche les traitements sur les méthodes annotées en fonction des paramètres de la request.
L'annotation @Controller à définir sur la classe dérivée de MVCApplication sert à définir des paramètres de la classe.
La page d'accueil de la XPage doit positionner le paramètre defaultView de l'annotation @View à true.
Les vues
Le framework MVC apporte une notion de vues et d'actions.
Les vues servent à afficher un contenu à l'utilisateur. Une vue est une méthode d'un contrôleur ayant l'annotation @View. Cette annotation prend en paramètre la clé unique de la vue qui sera utilisée par le framework pour la définir. Une fois le contenu d'une vue généré, elle doit renvoyer son résultat dans un objet XPage. La vue qui correspond à la page d'accueil de l'application doit comporter le paramètre defaultView de l'annotation @View à true. Lorsqu'une requête est effectuée sur une application, et qu'aucune vue ou action n'est spécifiée, alors la page d'accueil est affichée.
L'URL d'une vue est générée sur le modèle suivant :
jsp/site/Portal.jsp?page=nomdelapplication&view=nomdelavue
où :
- nomdelapplication est le nom de l'application (définie dans le paramètre de l'annotation @Controller)
- nomdelavue est le nom de la vue à afficher (définie comme paramètre de l'annotation @View).
Le mot clé view est donc un mot clé réservé et ne doit pas être utilisé comme nom de paramètre HTML pour une autre raison.
Les actions
Les actions servent à effectuer des traitements. Les actions ne doivent pas générer de contenu à afficher à l'utilisateur.
Une action est une méthode d'un contrôleur ayant l'annotation @Action. Cette annotation prend en paramètre la clé unique de l'action qui sera utilisée par le framework pour la définir. Lorsqu'une action termine son traitement, elle doit effectuer une redirection vers une vue grâce aux méthodes de redirection de la librairie (cf paragraphe suivant). Une action doit renvoyer un objet de type XPage. Lorsqu'elle effectue une redirection, elle doit renvoyer la XPage créée par la méthode de redirection.
L'URL d'une vue est générée sur le modèle suivant : jsp/site/Portal.jsp?page=nomdelapplication&action=nomdelaction
où :
- nomdelapplication est le nom de l'application (définie dans le paramètre de l'annotation
@Controller)
- nomdelaction est le nom de l'action à effectuer (définie comme paramètre de l'annotation
@Action).
Le mot clé action est donc un mot clé réservé et ne doit pas être utilisé comme nom de paramètre HTML pour une autre raison.
Les redirections
Lorsqu'une vue ou une action souhaite effectuer une redirection vers une autre vue ou une URL définie, elle doit appeler une des méthodes redirect( ... ) de la classe MVCApplication.
Ces méthodes permettent d'effectuer des redirections vers des vues de l'application en spécifiant uniquement le nom de la vue à afficher, ou vers une URL complète définie manuellement. Lorsque la redirection se fait vers une vue de l'application, des paramètres peuvent être spécifiés en les ajoutant dans une Map.
Une fois le traitement de la méthode de redirection terminé, la réponse HTTP est envoyé. Il n'est donc pas possible d'afficher un contenu HTML ou de faire une autre redirection pour ignorer la première.
Les méthodes de redirection renvoient des objets de type XPage. Ces objets doivent être renvoyés par les vues ou actions ayant appelé la méthode de redirection.
Exemple de code
Voici le code d'une XPage proposant 2 vues :
- la page d'accueil affichant une liste de contacts
- la page de création d'un contact
ainsi que 2 actions :
- créer un contact
- supprimer un contact
// MVCDemoApp.java
@Controller( xpageName = "mvcdemo" , pageTitle = "mvcdemo.pageTitle" , pagePath = "mvcdemo.pagePathLabel" )
public class MVCDemoApp extends MVCApplication
{
private static final String TEMPLATE_HOME = "/skin/plugins/mvcdemo/home.html";
private static final String TEMPLATE_FORM = "/skin/plugins/mvcdemo/form.html";
private static final String VIEW_HOME = "home";
private static final String VIEW_ADD_CONTACT = "addContact";
private static final String ACTION_ADD_CONTACT = "addContact";
private static final String ACTION_REMOVE_CONTACT = "removeContact";
private static final String MARK_CONTACTS_LIST = "contacts_list";
private static final String PARAMETER_ID = "id";
@View( value = VIEW_HOME , defaultView = true )
public XPage viewHome(HttpServletRequest request)
{
Map<String,Object> model = getModel();
model.put( MARK_CONTACTS_LIST , ContactService.getContacts() );
return getXPage( TEMPLATE_HOME, request.getLocale( ) , model );
}
@View( VIEW_ADD_CONTACT )
public XPage viewAddContact(HttpServletRequest request)
{
return getXPage( TEMPLATE_FORM, request.getLocale( ) );
}
@Action( ACTION_ADD_CONTACT )
public XPage addContact(HttpServletRequest request)
{
Contact contact = new Contact();
populate(contact, request);
if ( !validateBean(contact))
{
return redirectView( request , VIEW_ADD_CONTACT );
}
ContactService.addContact(contact);
return redirectView( request , VIEW_HOME );
}
@Action( ACTION_REMOVE_CONTACT )
public XPage removeContact(HttpServletRequest request)
{
String strContact = request.getParameter( PARAMETER_ID );
ContactService.removeContact( strContact );
return redirectView( request , VIEW_HOME );
}Fonctions avancées
Formulaires multi-actions
Exemple de formulaire mono action :
<form action="jsp/site/Portal.jsp" >
<input type="hidden" name="page" value="myplugin" />
<input type="hidden" name="action" value="action1" />
...
<button type="submit" value="Action 1" />
</form>Exemple de formulaire multi-actions :
<form action="jsp/site/Portal.jsp">
<input type="hidden" name="page" value="myplugin" />
...
<button type="submit" name=action_action1 value="Action 1" />
<button type="submit" name=action_action2 value="Action 2" />
<button type="submit" name=view_view1 value="Action 3" />
</form>Les prefix action_ et view_ dans les noms des boutons sont interprétés comme des appels d'actions ou de vues. L'autre partie du nom est interprétée comme la valeur de l'action ou de la vue.
Renvoie de flux JSON ou XML par la XPage
A partir de Lutece 5.0
Cette fonctionnalité peut être utile pour réaliser certaine partie de la page en Ajax tout en gardant le code de la partie serveur dans la même classe.
Pour cela deux méthodes ont été ajoutées au framework dans la classe MVCApplication :
- XPage responseJSON( HttpServletRequest request )
- XPage responseXML( HttpServletRequest request )
Voici un exemple qui renvoie une liste d'images au format JSON :
@View( VIEW_LIST_IMAGES )
public XPage viewListImages( HttpServletRequest request )
{
String strTopicId = request.getParameter( Constants.PARAMETER_TOPIC_ID );
JSONArray array = new JSONArray();
if( strTopicId != null )
{
int nTopicId = Integer.parseInt(strTopicId);
List<Image> list = ImageHome.findByTopic( nTopicId , _plugin );
for( Image image : list )
{
JSONObject jsonImage = new JSONObject();
jsonImage.accumulate( "id", image.getId() );
jsonImage.accumulate( "name", image.getName() );
array.add( jsonImage );
}
}
return responseJSON( array.toString() );
}