Intégrer Extend dans un plugin
- Introduction
- Intégrer Extend dans une ressource
- Afficher les informations d'une extension dans une XPage
Introduction
Le plugin-extend permet permet d'associer des extensions génériques (ajout de commentaires, notation, comptage de vues, ...) à des ressources (pages du site, documents , ...).
Les ressources pouvant accepter des extensions doivent respecter certaines contraintes techniques de manière à être "extensibles".
Le plugin propose une interface de Back Office qui permet d'associer dynamiquement tous les types de ressource trouvés avec toutes les extensions installées et disponibles sur le système. Une extension peut être associée à toutes les ressources d'un type donné ou à une instance particulière définie par son identifiant (par exemple, on peut activer les commentaires sur une page particulière du site et prévoir le comptage de vues sur toutes les pages).
Intégrer Extend dans une ressource
Afin de faciliter la compréhension du guide, l'intégration de Extend se fera à partir d'un exemple : intégration de extend sur le plugin-document.
Implémentation de l'interface IExtendableResource
Faire implémenter l'interface IExtendableResource à la classe représentative de la ressource Document. La classe en question Document doit alors implémenter les méthodes suivantes :
public class Document implements Localizable, IExtendableResource { ... /** * {@inheritDoc} */ @Override public String getIdExtendableResource( ) { return Integer.toString( _nIdDocument ); } /** * {@inheritDoc} */ @Override public String getExtendableResourceType( ) { return PROPERTY_RESOURCE_TYPE; } /** * {@inheritDoc} */ @Override public String getExtendableResourceName( ) { return _strTitle; } /** * {@inheritDoc} */ @Override public String getExtendableResourceDescription( ) { return _strDescription; } /** * {@inheritDoc} */ @Override public String getExtendableResourceImageUrl( ) { return _strImageUrl; } ... }
Implémentation du service DocumentExtendableResourceService
Ce service permet de récupérer la ressource à partir d'un type de ressource et de son ID. Il permet également de déclarer le type de ressource "Document" auprès du plugin extend :
public class DocumentExtendableResourceService implements IExtendableResourceService { /** * {@inheritDoc} */ @Override public boolean isInvoked( String strResourceType ) { return Document.PROPERTY_RESOURCE_TYPE.equals( strResourceType ); } /** * {@inheritDoc} */ @Override public IExtendableResource getResource( String strIdResource, String strResourceType ) { if ( StringUtils.isNotBlank( strIdResource ) && StringUtils.isNumeric( strIdResource ) ) { int nIdDocument = Integer.parseInt( strIdResource ); return DocumentHome.findByPrimaryKey( nIdDocument ); } return null; } /** * {@inheritDoc} */ @Override public String getResourceType( ) { return Document.PROPERTY_RESOURCE_TYPE; } /** * {@inheritDoc} */ @Override public String getResourceTypeDescription( Locale locale ) { return I18nService.getLocalizedString( MESSAGE_DOCUMENT_RESOURCE_TYPE_DESCRIPTION, locale ); } /** * {@inheritDoc} */ @Override public String getResourceUrl( String strIdResource, String strResourceType ) { String strUrl ; ... return strUrl; } }
Ce service est instancié par Spring. Il faut alors le déclarer au niveau du fichier de contexte du plugin (ex : document_context.xml ) :
<bean id="[plugin].[resource_type]ExtendableResourceService" class="fr.paris.lutece.plugins.[plugin].service.resource.[Resource_type]ExtendableResourceService" />
exemple :
<bean id="document.documentExtendableResourceService" class="fr.paris.lutece.plugins.document.service.resource.DocumentExtendableResourceService" />
Ajout des boutons en BO pour interagir avec extend
Modification de la JSPBean
Dans la méthode getModifyDocument, y ajouter la ligne suivante :
public String getModifyDocument( HttpServletRequest request ) { ... ExtendableResourcePluginActionManager.fillModel( request, getUser( ), model, strDocumentId, Document.PROPERTY_RESOURCE_TYPE ); ... }
Cette appel va ajouter dans le model les boutons.
Modification de la template
Modifier la template modify_document.html et y ajouter la ligne suivante :
${extendableResourceActionsHtml!}
Affichage des contenus en FO
Pour afficher un contenu particulier en front office, il faut configurer dans le menu du back office "Gestion des extensions de contenu" (.../jsp/admin/plugins/extend/ManageResourceExtendersByResource.jsp) une règle activant les extensions pour ces ressources (on peut choisir une ressource en particulier, ou toutes les ressources d'un type). Il faut ensuite ajouter le marker suivant dans une template :
@ Extender[<idExtendableResource>,<resourceType>,<extenderType>,<parameters>]@
où :
- <idExtendableResource> correspond à l'ID de la ressource (ex : 1)
- <resourceType> correspond au type de ressource (attention, le type est sensible à la casse). Par exemple :
- PAGE pour les pages classiques d'un portail Lutèce
- document pour les documents du plugin-document
- <extenderType> correspond au type de l'extension (attention, le type est sensible à la casse). Par exemple :
- comment pour commenter les ressources
- hit pour le nombre de vues sur la ressource
- rating pour voter les ressources
- feedback pour donner son avis sur les ressources
- <parameters> correspond aux paramètres supplémentaires à ajouter pour les extensions (ex : {show:true})
Quelques exemples :
Markeur | Description |
---|---|
@ Extender[1,document,comment]@ | Affiche les commentaires pour le document ayant l'ID 1. |
@ Extender[1,document,hit,{show:true}]@]@ | Affiche le nombre de vues sur le document ayant l'ID 1. |
@ Extender[1,document,hit,{show:false}]@ | N'affiche pas le nombre de vues pour le document ayant l'ID 1, mais incrémente le compteur. |
@ Extender[1,document,hit,{increment:true}]@ | incrémente le compteur |
@ Extender[1,document,hit,{increment:false}]@ | n'incrémente pas le compteur |
@ Extender[1,document,rating,{show:"vote"}]@ | Affiche la note du document ayant l'ID 1@ |
@ Extender[1,document,rating,{show:"voteAction"}]@ | Affiche les liens pour voter le document ayant l'ID 1 |
@ Extender[1,document,rating,{show:"all"}]@ | Affiche la note et les liens du document ayant l'ID 1 |
@ Extender[2,PAGE,feedback]@ | Affiche un formulaire pour donner son avis sur la page ayant l'ID 2 |
Markeurs avec ID paramétrables
Dans le cas où le traitement des extensions est fait côté serveur, Il est possible d'utiliser des ID de ressource paramétrables. Dans ce cas, l'ID doit toujours être définie dans un template HTML, mais peut être définie à n'importe quel endroit. Cela permet par exemple de mettre un markeur dans le header (qui est géré par le cœur Lutece), et de ne définir l'ID de la ressource que dans le body (par exemple dans un template géré par un plugin).
Pour faire cela, il suffit, au lieu de mettre l'identifiant, de mettre ExtendParameteredId.
L'id doit ensuite être définie dans un markeur :
@ ExtenderParameter[<idExtendableResource>,<resourceType>,<extenderType>]@
Si l'ID n'est pas spécifiée par un markeur ExtenderParameter, alors le markeur d'origine est ignoré.
Exemple :
Afin d'ajouter dans l'en-tête les meta données liées à Open graph, on ajoute dans la balise <head> du fichier page_framset.html le markeur :
@ Extender[ExtendParameteredId,document,opengraph,{header:true}]@
On ajouter ensuite par exemple dans le template page_template_document1.html du plugin Document le markeur de paramètre suivant :
@ ExtenderParameter[1,document,opengraph]@
Ainsi, si le contenu du template page_template_document1.html est inclus dans la page finale, alors le premier markeur sera remplacé par les meta données relative au document d'id 1, et seront placées dans la balise <head>.
Suppression de ressource
Lorsqu'une ressource extencible (dans notre exemple, un document) est supprimée, il faut notifier les différentes extensions de la suppression de cette ressource. Pour cela, il suffit d’appeler la méthode fr.paris.lutece.portal.service.resource.ExtendableResourceRemovalListenerService.doRemoveResourceExtentions( String strExtendableResourceType, String strExtendableResourceId ). Cette méthode se chargera de supprimer toutes les données contenues en base relative à la ressource supprimée.
Le premier paramètre de cette méthode est le type de la ressource supprimée (par exemple "document" dans notre cas. Le deuxième paramètre est l'identifiant de la ressource.
Afficher les informations d'une extension dans une XPage
Certains des modules du plugin Extend permettent de visualiser des informations relatives à l’extension (ex : le module extend comment permet de visualiser les commentaires d'une ressource dans la page de gestion des informations de l’extension). Cette page d'information de l’extension peut être intégrée dans une XPage d'un plugin. Pour cela, il suffit de récupérer le contenu de la page d'information grace au ResourceExtenderComponent de ce module.
Par exemple, la méthode suivante permet d'afficher de façon autonome la page d'information du module extend comment :
public String getPage( HttpServletRequest request ) { ResourceExtenderDTO resourceExtender = new ResourceExtenderDTO( ); String strIdExtendableResource = request.getParameter( MARK_ID_EXTENDABLE_RESOURCE ); // Votre marqueur permettant d'obtenir l'identifiant de la ressource String strExtendableResourceType = request.getParameter( MARK_EXTENDABLE_RESOURCE_TYPE ); // Votre marqueur permettant d'obtenir le type de la ressource resourceExtender.setIdExtendableResource( strIdExtendableResource ); resourceExtender.setExtendableResourceType( strExtendableResourceType ); resourceExtender.setExtenderType( EXTENDER_TYPE_COMMENT ); // Le type d’extension que vous souhaitez afficher (ici comment) // On récupère ensuite le ResourceExtenderComponent du module désiré IResourceExtenderComponentManager extenderComponentManager = SpringContextService.getBean( ResourceExtenderComponentManager.BEAN_MANAGER ); IResourceExtenderComponent resourceExtendercomponent = extenderComponentManager.getResourceExtenderComponent( EXTENDER_TYPE_COMMENT ); // On récupère le contenu HTML de la page d'information String strHtml = resourceExtendercomponent.getInfoHtml( resourceExtender, AdminUserService.getLocale( request ), request ); return getAdminPage( strHtml ); }