Galerie en mosaïque

La Masonry Gallery affiche des images de proportions différentes. Chaque image conserve son ratio et rejoint la colonne la plus courte. Le contrôle charge la page suivante lorsque l’utilisateur fait défiler la page, sans créer une seconde barre de défilement interne.

Elle convient aux portfolios, inspirations, photos et ressources visuelles. Elle reste distincte de CardSet : CardSet résume des enregistrements métier avec états, métadonnées et actions, tandis que Masonry Gallery privilégie l’image et la navigation continue.

1. Ajouter et configurer le contrôle

Dans Page Designer, ouvrez Containers.
Faites glisser Masonry Gallery sur la page.
Configurez d’abord Data Source, puis les champs.
Donnez un nom stable au contrôle, par exemple portfolioGallery.

L’aperçu de conception montre des cartes de ratios différents. Preview charge les vraies données, mais s’arrête après deux pages afin d’éviter un chargement continu pendant l’édition.

2. Source de données

Masonry Gallery accepte Model Data Source, Custom API, Media Library et Object Storage. Les deux dernières sources passent par un connecteur média côté serveur.

2.1 Exemple Custom API

L’exemple de base utilise :

POST /spark/api/sample/masonry-gallery/images

Propriété	Valeur
URL	`/spark/api/sample/masonry-gallery/images`
Request Method	`POST`
Rows Path	`data.records`
Total Path	`data.total`
Current Page Path	`data.current`
Page Size Path	`data.pageSize`

Utilisez Test & Import pour demander une page et importer les Response Fields :

Field Path	Data Type	Utilisation
`id`	TEXT	Clé unique stable
`imageUrl`	URL	Adresse de l’image
`title`	TEXT	Titre
`caption`	TEXT	Texte complémentaire
`badge`	TEXT	Catégorie
`alt`	TEXT	Texte alternatif
`width`	NUMBER	Largeur d’origine
`height`	NUMBER	Hauteur d’origine

Requête :

{"current": 1, "pageSize": 6}

Réponse recommandée :

{
  "success": true,
  "data": {
    "current": 1,
    "pageSize": 6,
    "total": 24,
    "records": [{
      "id": "gallery-1",
      "imageUrl": "/spark/api/sample/masonry-gallery/assets/coastal-architecture.jpg",
      "title": "Coastal Geometry",
      "caption": "Sunlit concrete forms above a quiet blue sea.",
      "badge": "Architecture",
      "alt": "White coastal architecture above the sea",
      "width": 1200,
      "height": 1200
    }]
  }
}

total constitue la condition de fin la plus fiable. Sans ce champ, la galerie s’arrête quand une page contient moins d’éléments que Items Per Request. Row Unique Key doit rester unique entre toutes les pages ; les doublons sont éliminés.

2.2 Media Library et Object Storage

Créez d’abord une connexion réutilisable dans App Settings → Integrations → Media Connections :

Créez un identifiant dans Secret Management. Utilisez OBJECT_STORAGE pour OSS/S3/MinIO et MEDIA_PROVIDER pour une plateforme média.
Dans Media Connections, choisissez le Provider et le Secret existant. Le formulaire n’affiche que les paramètres nécessaires au Provider ; les endpoints API officiels utilisés automatiquement restent masqués.
Dans la Data Source de Masonry Gallery, choisissez Media Library ou Object Storage et référencez uniquement la Connection. Renseignez ensuite Collection/Container, Path, filtres et Page Size.
Cliquez sur Test. Le test, l’aperçu de conception et l’exécution utilisent la même passerelle média et le même parseur.

Providers de production actuellement disponibles :

Provider	Secret Management	Paramètres Media Connection
Cloudinary	`MEDIA_PROVIDER` ; API Key dans Clé API et API Secret dans Secret API	Cloud Name obligatoire ; Root Folder facultatif
ImageKit	`MEDIA_PROVIDER` ; Public API Key dans Clé API et Private API Key dans Secret API	Root Folder facultatif ; endpoint API officiel automatique
Aliyun OSS / AWS S3 / MinIO	`OBJECT_STORAGE` ; Access Key et Access Secret	Endpoint, Bucket par défaut et Root Prefix selon le stockage

Spark Sample Media Library sert uniquement au développement sans compte externe. Cloudinary et ImageKit sont des connecteurs Media Library de production ; Bynder, AEM Assets et la Media Library Spark complète ne sont pas encore disponibles.

Le JSON de la page ne stocke ni secretId, ni clé d’accès, ni URL signée temporaire. Le backend normalise la réponse en records, nextCursor, hasMore et total facultatif. Les cartes utilisent thumbnailUrl et l’aperçu plein écran utilise imageUrl.

{
  "records": [{
    "id": "asset-001",
    "imageUrl": "https://cdn.example/full.webp",
    "thumbnailUrl": "https://cdn.example/card.webp",
    "title": "Summer campaign",
    "alt": "Summer campaign launch",
    "width": 1600,
    "height": 1067
  }],
  "nextCursor": "opaque-next-cursor",
  "hasMore": true,
  "total": null
}

L’exemple exécutable se trouve dans SampleMasonryMediaConnector.java, masonry-gallery-media-connection.json et masonry-gallery-media-page.json du module spark-sample.

3. Correspondance des champs

Propriété	Correspondance conseillée	Obligatoire
Row Unique Key	`id`	Oui
Image URL Field	`imageUrl`	Oui
Title Field	`title`	Non
Caption Field	`caption`	Non
Badge Field	`badge`	Non
Alternative Text Field	`alt`	Recommandé
Image Width Field	`width`	Recommandé
Image Height Field	`height`	Recommandé

Width et Height, dans Advanced, réservent le bon ratio avant le téléchargement et réduisent les déplacements de mise en page. Le texte alternatif doit décrire l’image ; il utilise Title comme solution de repli.

4. Mise en page adaptative

Propriété	Valeur conseillée	Description
Desktop Columns	`4`	Nombre de colonnes sur écran large
Tablet Columns	`3`	Nombre de colonnes sur écran moyen
Mobile Columns	`2`, ou `1` avec beaucoup de texte	Nombre de colonnes sur mobile
Spacing	`DEFAULT`	`COMPACT`, `DEFAULT` ou `RELAXED`
Items Per Request	`6` ou `12`	Nombre d’éléments chargés par requête

Les colonnes suivent la largeur de page et les images ne sont pas recadrées à une hauteur commune.

5. Défilement et états

À environ une vue et demie de la fin, la page suivante commence à charger. Une seule requête peut être active. Le contrôle affiche les états de chargement, d’erreur avec Retry et de fin. Un retour rapide sur la page restaure les enregistrements et la position de défilement.

Évitez de placer la galerie dans un conteneur étroit, de hauteur fixe, doté de sa propre barre de défilement.

6. Aperçu plein écran et interactions

Avec Enable Fullscreen Preview, un clic ouvre la visionneuse. Les flèches, les touches fléchées, Escape, Tab, Enter et Espace sont pris en charge.

Avant onClick, l’enregistrement est écrit dans Current Record :

record.id
record.imageUrl
record.title
record.badge

Un clic peut ouvrir l’aperçu et exécuter onClick. Désactivez l’aperçu si l’interaction change immédiatement de page.

Fonction	Effet
`reloadGallery`	Efface la pagination et recharge la première page
`setGalleryData`	Remplace directement les données et arrête la pagination automatique

7. Contexte de requête et backend

Le test Data Source, l’aperçu et l’exécution partagent la même logique. Spark ajoute automatiquement :

Header	Valeurs
`X-Spark-Page-Environment`	`DEV`, `TEST` ou `PROD`
`X-Spark-Page-Render-Mode`	`DESIGN_PREVIEW` ou `RUNTIME`

Ne les ajoutez pas manuellement. Le backend peut limiter les données en conception :

@PostMapping
public ApiResult<ProTablePageResult<MasonryGalleryImageDTO>> queryByPost(
        @RequestBody(required = false) MasonryGalleryQueryRequest request,
        @RequestHeader(value = SparkPageRequestHeaders.ENVIRONMENT, required = false) String environment,
        @RequestHeader(value = SparkPageRequestHeaders.RENDER_MODE, required = false) String renderMode) {
    return SparkApiResultHelper.success(
            Locale.ENGLISH,
            galleryService.query(request,
                    SparkPageRequestHeaders.resolve(environment, renderMode)),
            "SPARK-SAMPLE-MASONRY-GALLERY-0001");
}

Le service adapte ensuite le volume de données au mode de rendu :

int total = requestContext != null
        && requestContext.getRenderMode() == SparkPageRenderMode.DESIGN_PREVIEW
        ? 12
        : 24;

L’exemple Java, le JSON de page et les images se trouvent dans spark-sample. Consultez Contexte de requête et diagnostic backend.

8. Performances et données

Servez des images adaptées à l’affichage, compressées et mises en cache.
Renvoyez toujours id, width, height et un alt utile.
Utilisez 6 à 20 éléments par requête et un tri backend stable.
Les erreurs d’image et d’API de données doivent être diagnostiquées séparément ; une image indisponible n’interrompt pas la pagination.

9. Problèmes courants

Les mêmes images se répètent : vérifiez que le backend applique current et pageSize, puis contrôlez les chemins de réponse.
Le défilement ne charge plus : vérifiez total, les pages courtes et une éventuelle requête en attente de Retry.
La mise en page se déplace : renvoyez et mappez width et height.
Des espaces réservés remplacent les images : vérifiez Image URL Field, l’authentification et CORS.
Vous avez besoin d’actions et de métadonnées métier riches : utilisez CardSet ; Masonry Gallery ne fournit pas de Card Actions.

1. Ajouter et configurer le contrôle​

2. Source de données​

2.1 Exemple Custom API​

2.2 Media Library et Object Storage​

3. Correspondance des champs​

4. Mise en page adaptative​

5. Défilement et états​

6. Aperçu plein écran et interactions​

7. Contexte de requête et backend​

8. Performances et données​

9. Problèmes courants​