10 nov. 2021 14:52:02 Thomas Dumont avatar

Intégrer Extend dans un plugin

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" />

Attention, si le plugin est désactivé, alors la ressource ne sera pas disponible auprès du plugin extend !

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 );
}