HOW-TO : Création de portlets "à la main"

Auteur: Oscar Figueiredo (CPE Lyon)   <oscar at cpe point fr>

IMPORTANT: Pour créer un portlet personnalisé, on peut utiliser avantageusement l'insertion de Custom Portlet dans le 'Portlet Manager' de CPSSkins qui rend l'opération extrêmement simple mais ce document a plus pour objectif de donner une idée plus précise des mécanismes internes de rendu des portlets. La méthode proposée a pour autre avantage de permettre de personnaliser non seulement le portlet mais aussi son interface d'édition.

Notion fondamentale : un portlet est un CPSDocument donc lire Products/CPSDocuments/doc/creating-new-content-types.txt

IMPORTANT: Lire également les consignes dans Products/CPSPortlets/doc/portlet-creation-guidelines.txt

Grossièrement 4 étapes sont nécessaires:

1. définition d'un schema dans portal_schema
2. définition d'un layout dans portal_layout
3. définition d'un type flexible dans portal_types
4. définition des ZPT et scripts de rendu dans portal_skins

1. Schema (portal_schema)

La création d'un schéma ne s'impose que si le portlet demande des champs spécifiques pour sa configuration. Si besoin donc créer un nouveau schéma. Y ajouter les champs souhaités.

2. Layout (portal_layouts)

Cette opération se passe dans l'outil portal_layouts.

Il faut :

• créer un nouveau layout de même nom que le schéma
• dans l'onglet 'Widgets' ajouter un widget de type 'Generic Portlet Widget' appelé 'portlet'.
• Dans la propriété 'zpt or py script method' renseigner le nom du ZPT ou script python qui sera chargé du rendu proprement dit. Voir point 4.
• A la propriété 'Hidden in layout modes' préciser 'edit'. Le rendu normal du portlet ne sera ainsi pas fait dans le dialogue d'édition. Inversement, tous les autres widgets personnalisés utilisés dans le dialogue d'édition doivent avoir la valeur 'view' dans ce champ de manière à ne pas être visibles lors du rendu du widget.
• dans l'onglet 'Layout', ajouter une ligne et dans la liste déroulante, choisir 'portlet' pour faire référence au widget de rendu. Ajouter au besoin des lignes supplémentaires pour les widgets d'édition.

Noter au passage l'option 'Hidden if empty' qui peut être intéressante.

3. Ajout d'un type flexible (portal_types)

Dans l'outil portal_types, copier un portlet existant tel que Breadcrumbs_Portlet et modifier ses propriétés Schemas et Layout. A défaut, instancier un objet 'Flexible Type Information' et spécifier les propriétés suivantes:

• Product meta type : 'CPS Portlet'
• Product name : 'CPSPportlets'
• Product factory method : 'addCPSPortlet'
• Initial view name : 'cpsportlet_edit_form'
• Implicitly addable : non
• Filter content types : non
• Allow discussion : non
• CPS searchable : non
• CPS proxy type : aucun
• Schemas : portlet_common CUSTOM_SCHEMA common metadata
• Layouts : portlet_common CUSTOM_LAYOUT Layout
• clusters : metadata:metadata
• CPS Portlet : oui

CUSTOM_SCHEMA et CUSTOM_LAYOUT sont à remplacer par le nom du schema et le nom du layout.

Puis modifier les actions en recopiant les valeurs depuis un objet similaire.

4. Scripts et ZPT de rendu (portal_skins)

Le(s) script(s) personnel(s) de rendu sont à installer dans l'outil portal_skins avec les règles qui s'y appliquent concernant l'accès par couches (layers). Voir l'onglet Properties de portal_skins et notamment la propriété 'default_skin' indiquant le skin par défaut. C skin par défaut est en principe CPSSkins dont on voit que la première couche est 'custom'. Ceci conduit donc à l'instanciation des scripts et ZPT personnels dans ce répertoire éventuellement par customisation d'un script existant (bouton Customize dans la visualisation d'un de ces documents).

Pour une liste de liens utiliser la forme suivante

  <ul class="cpsskinsMenu">

   <li><a href="...">Lien</a></li>

  </ul>

Cache de portlets

Les portlets sont mis en cache, après tout changement il faut vider le cache sous peine de ne pas en voir l'effet. Voir l'onglet 'Cache' de l'objet portal_cpsportlets.