Composant standard
Page reference
Table des matières
1. Introduction
Le composant PageReferenceComponent permet d'afficher une liste de pages sélectionnées avec de nombreuses options de personnalisation. Il expose plusieurs variables dans le contexte JSTL pour faciliter l'affichage des données.
Note : Ce composant nécessite l'import des taglibs JSTL core et functions dans vos templates JSP.
2. Variables disponibles
Le composant expose les variables suivantes dans le contexte de la requête :
| Variable | Type | Description |
|---|---|---|
| pages | Collection<SmartPageBean> | Liste des pages sélectionnées à afficher |
| title | String | Titre du composant (configurable) |
| linkTitle | String | Titre du lien (configurable) |
| comp | PageReferenceComponent | Instance du composant actuel |
| firstPage | String | Contenu HTML de la première page (si activé) |
| pagination | PaginationContext | Contexte de pagination pour la navigation |
| pagesStatus | PagesStatus | Statistiques sur les pages (total, avec contenu réel) |
| months | List<String> | Liste des mois disponibles pour le filtrage |
| tags | Collection<String> | Liste des tags disponibles |
| popup | boolean | Indique si les liens s'ouvrent en popup |
| interactive | boolean | Indique si le mode interactif est activé |
| jsonUrl | String | URL pour récupérer les données en JSON |
| referenceLink | String | URL vers la page parent de référence |
3. Propriétés des pages (SmartPageBean)
Chaque page dans la collection pages est un objet SmartPageBean avec les propriétés suivantes :
| Propriété | Type | Description |
|---|---|---|
| id | String | Identifiant unique de la page |
| title | String | Titre de la page |
| htmlTitle | String | Titre HTML de la page |
| description | String | Description de la page |
| url | String | URL de la page |
| linkOn | String | Lien externe (si configuré) |
| name | String | Nom de la page |
| path | String | Chemin de la page |
| date | DateBean | Date de contenu de la page |
| contentDate | DateBean | Date de contenu (jamais null) |
| dateInfo | String | Information de date formatée |
| timeRange | SmartTimeRange | Plage de dates (pour les événements) |
| images | Collection<Image> | Collection d'images de la page |
| imagePath | String | Chemin de la première image |
| imageDescription | String | Description de la première image |
| tags | Collection<String> | Tags de la page |
| tagsLabel | Collection<String> | Labels des tags (traduits) |
| firstTag | String | Premier tag de la page |
| firstTagLabel | String | Label du premier tag |
| category | String | Catégorie de la page |
| creator | String | Créateur de la page |
| authors | String | Informations sur l'auteur |
| realContent | boolean | Indique si la page a du contenu réel |
| selected | boolean | Indique si la page est sélectionnée |
| children | List<SmartPageBean> | Pages enfants |
| product | ProductBean | Informations produit (si applicable) |
Propriétés des images
Chaque image dans la collection images a les propriétés suivantes :
| Propriété | Type | Description |
|---|---|---|
| url | String | URL de l'image |
| viewURL | String | URL pour l'affichage |
| linkURL | String | URL du lien |
| description | String | Description de l'image |
| path | String | Chemin de l'image |
| cssClass | String | Classe CSS de l'image |
4. Exemples d'utilisation
Exemple basique - Liste simple
<%@ taglib prefix="c" uri="jakarta.tags.core" %><%@ taglib prefix="fn" uri="jakarta.tags.functions" %><c:if test="${fn:length(pages) > 0}"> <c:if test="${not empty title}"> <h2>${title}</h2> </c:if> <ul> <c:forEach items="${pages}" var="page" varStatus="status"> <li> <a href="${page.url}" title="${page.title}"> ${page.title} </a> <c:if test="${not empty page.description}"> <p>${page.description}</p> </c:if> </li> </c:forEach> </ul></c:if>
Exemple avec images - Galerie
<%@ taglib prefix="c" uri="jakarta.tags.core" %><%@ taglib prefix="fn" uri="jakarta.tags.functions" %><c:if test="${fn:length(pages) > 0}"> <div class="gallery"> <c:forEach items="${pages}" var="page" varStatus="status"> <c:if test="${fn:length(page.images) > 0}"> <c:set var="image" value="${page.images[0]}" /> <div class="gallery-item"> <figure> <a href="${page.url}" title="${page.title}"> <img src="${image.url}" alt="${image.description}" /> </a> <figcaption> <h3><a href="${page.url}">${page.title}</a></h3> <c:if test="${not empty page.description}"> <p>${page.description}</p> </c:if> </figcaption> </figure> </div> </c:if> </c:forEach> </div></c:if>
Exemple avec dates et tags
<%@ taglib prefix="c" uri="jakarta.tags.core" %><%@ taglib prefix="fn" uri="jakarta.tags.functions" %><c:if test="${fn:length(pages) > 0}"> <div class="articles-list"> <c:forEach items="${pages}" var="page" varStatus="status"> <article class="article-item"> <header> <h2><a href="${page.url}">${page.title}</a></h2> <div class="meta"> <c:if test="${not empty page.date}"> <time datetime="${page.date}">${page.dateInfo}</time> </c:if> <c:if test="${not empty page.creator}"> <span class="author">Par ${page.authors}</span> </c:if> </div> </header> <c:if test="${not empty page.description}"> <div class="excerpt"> ${page.description} </div> </c:if> <c:if test="${fn:length(page.tags) > 0}"> <div class="tags"> <c:forEach items="${page.tagsLabel}" var="tag"> <span class="tag">${tag}</span> </c:forEach> </div> </c:if> </article> </c:forEach> </div></c:if>
Exemple avec pagination
<%@ taglib prefix="c" uri="jakarta.tags.core" %><%@ taglib prefix="fn" uri="jakarta.tags.functions" %><c:if test="${fn:length(pages) > 0}"> <!-- Affichage des pages --> <div class="pages-list"> <c:forEach items="${pages}" var="page"> <div class="page-item"> <h3><a href="${page.url}">${page.title}</a></h3> <p>${page.description}</p> </div> </c:forEach> </div> <!-- Pagination --> <c:if test="${not empty pagination}"> <div class="pagination"> <c:if test="${pagination.hasPrevious}"> <a href="${pagination.previousUrl}" class="prev">Précédent</a> </c:if> <span class="info"> Page ${pagination.currentPage} sur ${pagination.totalPages} (${pagination.totalItems} éléments) </span> <c:if test="${pagination.hasNext}"> <a href="${pagination.nextUrl}" class="next">Suivant</a> </c:if> </div> </c:if></c:if>
5. Templates intégrés
Le composant propose plusieurs templates prédéfinis :
Template "menu" - Liste simple
<c:if test="${fn:length(pages) > 0}"> <c:if test="${not empty title}"><h4>${title}</h4></c:if> <ul> <c:forEach items="${pages}" var="page" varStatus="status"> <li class="${page.name}${page.selected ? ' selected' : ''}"> <a title="${page.title}" href="${page.url}">${page.title}</a> </li> </c:forEach> </ul></c:if>
Template "thumbnails" - Miniatures
<ul class="portfolio"> <c:forEach items="${pages}" var="page" varStatus="status"> <c:set var="image" value="${page.images[0]}" /> <li> <figure> <a title="${page.title}" href="${page.url}"> <img src="${image.url}" alt="${image.description}" /> </a> <figcaption> <a title="${page.title}" href="${page.url}"> <h4>${page.title}</h4> </a> <c:if test="${not empty page.description}"> <p>${page.description}</p> </c:if> </figcaption> </figure> </li> </c:forEach></ul>
Template "carousel" - Carrousel
<c:if test="${not empty title}"> <h2>${title}</h2></c:if><div class="carousel-wrapper"> <div class="carousel"> <ul class="slides"> <c:forEach items="${pages}" var="page" varStatus="status"> <c:if test="${fn:length(page.images) > 0}"> <c:set var="image" value="${page.images[0]}" /> <c:set var="url" value="${page.url}" /> <c:set var="target" value="" /> <c:if test="${!page.realContent && not empty page.linkOn}"> <c:set var="url" value="${page.linkOn}" /> <c:if test="${info.openExternalLinkAsPopup}"> <c:set var="target" value=" target=\"_blank\"" /> </c:if> </c:if> <li class="slide"> <a href="${url}" title="${page.title}"${target}> <figure> <img src="${fn:replace(image.url,'reference-list','carousel')}" alt="${image.description}"> <figcaption>${page.title}</figcaption> </figure> </a> </li> </c:if> </c:forEach> </ul> </div></div>
6. Gestion de la pagination
Le composant gère automatiquement la pagination via l'objet pagination :
| Propriété | Type | Description |
|---|---|---|
| currentPage | int | Numéro de la page actuelle |
| totalPages | int | Nombre total de pages |
| totalItems | int | Nombre total d'éléments |
| itemsPerPage | int | Nombre d'éléments par page |
| hasPrevious | boolean | Indique s'il y a une page précédente |
| hasNext | boolean | Indique s'il y a une page suivante |
| previousUrl | String | URL de la page précédente |
| nextUrl | String | URL de la page suivante |
7. Filtres et taxonomie
Le composant supporte plusieurs types de filtres :
Filtrage par tags
<!-- Affichage des tags disponibles --><c:if test="${fn:length(tags) > 0}"> <div class="tag-filters"> <c:forEach items="${tags}" var="tag"> <a href="?tag=${tag}" class="tag-filter">${tag}</a> </c:forEach> </div></c:if><!-- Affichage des tags de chaque page --><c:forEach items="${pages}" var="page"> <c:if test="${fn:length(page.tags) > 0}"> <div class="page-tags"> <c:forEach items="${page.tagsLabel}" var="tag"> <span class="tag">${tag}</span> </c:forEach> </div> </c:if></c:forEach>
Filtrage par mois
<!-- Affichage des mois disponibles --><c:if test="${fn:length(months) > 0}"> <div class="month-filters"> <c:forEach items="${months}" var="month"> <a href="?month=${month}" class="month-filter">${month}</a> </c:forEach> </div></c:if>
8. Modes interactifs
Le composant peut fonctionner en mode interactif pour permettre la recherche et le filtrage dynamique :
<c:if test="${interactive}"> <div class="interactive-filters"> <!-- Formulaire de recherche --> <form method="get"> <input type="text" name="query" placeholder="Rechercher..." value="${param.query}" /> <input type="submit" value="Rechercher" /> </form> <!-- Filtres par taxonomie --> <c:if test="${not empty taxonomyList}"> <div class="taxonomy-filters"> <c:forEach items="${taxonomyList}" var="taxonomy"> <label> <input type="checkbox" name="taxonomy" value="${taxonomy.id}" /> ${taxonomy.label} </label> </c:forEach> </div> </c:if> </div> <!-- Chargement dynamique via AJAX --> <div id="pages-container" data-json-url="${jsonUrl}"> <!-- Le contenu sera chargé dynamiquement --> </div></c:if>
Utilisation de l'API JSON
En mode interactif, vous pouvez récupérer les données via l'URL JSON :
<script>// Exemple de chargement AJAXfetch('${jsonUrl}') .then(response => response.json()) .then(data => { // Traitement des données JSON data.forEach(page => { console.log(page.title, page.url); }); });</script>
Attention : En mode interactif, le composant n'est pas mis en cache et les performances peuvent être impactées.
9. Bonnes pratiques
- Vérification de l'existence des données : Toujours vérifier que la collection pages n'est pas vide avant de l'utiliser.
- Gestion des images : Vérifier la présence d'images avant de les afficher avec fn:length(page.images) > 0.
- Échappement HTML : Utiliser les propriétés appropriées comme htmlTitle pour éviter les problèmes d'échappement.
- Échappement JSTL : Dans les fichiers JSP, échapper les expressions
${}pour éviter l'interprétation prématurée. - Performance : Éviter le mode interactif si la pagination classique suffit.
- Accessibilité : Toujours fournir des attributs
altettitlepour les images et liens.
Note finale : Cette documentation couvre les principales fonctionnalités du composant PageReferenceComponent. Pour des cas d'usage spécifiques, consultez les templates d'exemple fournis dans le système.