Travailler avec des fichiers et des images

Stocker une seule image dans un agrégat

Quand l’utiliser :
Choisissez cette approche lorsque l’agrégat requiert exactement un champ image lié à un objectif métier précis, par exemple :

• Une photo d’équipement dans un enregistrement d’actif

• Une photo de profil dans un compte utilisateur

• Un logo d’entreprise dans un profil d’organisation

C’est utile lorsque l’image :

• Possède sa propre commande de mise à jour et ses permissions d’accès

• Doit toujours représenter le même type de visuel (et non une collection arbitraire d’images)

• Doit être stockée, affichée et gérée comme une valeur unique plutôt que dans une galerie ou une liste

Comment faire :

1. Définir le champ image et la commande de mise à jour

• Ajoutez un champ de type Image à l’agrégat.

• Créez une commande (p. ex., updateImage).

• Ajoutez le champ image comme paramètre de commande.

---

2. Pour la consultation et la modification sur place

• Glissez-déposez le champ image sur l’écran.

• Sélectionnez l’option d’affichage « Value only ».

• Cliquez sur le composant image pour examiner sa configuration.

• Retirez la commande de mise à jour de la configuration si vous voulez que l’image soit en lecture seule.

• Si la commande de mise à jour est conservée :

  • Cliquer sur l’image invitera l’utilisateur à parcourir pour un nouveau fichier si aucun n’est défini.

  • Si une image est déjà définie, cliquer l’effacera.

---

3. Pour utiliser un dialogue de modification

• Glissez-déposez le champ image sur l’écran.

• Sélectionnez l’option d’affichage « Value and label ».

• Cliquez sur le composant de champ pour examiner sa configuration.

• Cliquer sur le champ ouvre un dialogue d’action standard.

  • Le dialogue peut être configuré pour permettre d’effacer l’image (si le paramètre n’est pas marqué comme requis).

  • Le dialogue peut aussi permettre de sélectionner une nouvelle image.

  • Vous pouvez ajouter des paramètres supplémentaires à la commande de mise à jour pour une logique de mise à jour plus complexe.

Stocker un seul fichier dans un agrégat

Quand l’utiliser :
Utilisez ce modèle lorsqu’un agrégat doit stocker un fichier nommé et spécifique qui possède sa propre commande de mise à jour et ses permissions d’accès. C’est idéal lorsque :

• Le fichier sert un objectif métier dédié et est toujours du même type de document.

• Il doit être géré indépendamment des autres fichiers du système.

• Les droits d’accès et les règles de mise à jour diffèrent des autres documents de l’agrégat.

Exemple :
Un enregistrement Employee pourrait stocker trois documents distincts — employmentContract, jobDescription et signedNDA — chacun nécessitant ses propres permissions et logique de mise à jour. Au lieu de les traiter comme une collection unique de pièces jointes, définissez chacun comme un champ fichier individuel.

---

Comment faire :

1. Définir le champ fichier et la commande de mise à jour

• Ajoutez un champ de type File à l’agrégat.

• Créez une commande (p. ex., updateFile).

• Ajoutez le champ fichier comme paramètre de cette commande.

---

2. Ajouter le champ à l’écran

• Glissez-déposez le champ fichier sur l’écran.

• Sélectionnez l’option d’affichage « Value and label ».

• Cliquez sur le composant de champ pour examiner sa configuration.

---

3. Configurer l’interaction avec le fichier

• Cliquer sur le champ ouvrira un dialogue d’action standard.

  • Le dialogue permet à l’utilisateur d’effacer le fichier (si le paramètre n’est pas marqué comme requis).

  • Le dialogue permet à l’utilisateur de parcourir et de sélectionner un nouveau fichier.

  • Vous pouvez ajouter des paramètres supplémentaires à la commande de mise à jour pour une logique de mise à jour plus complexe.

Stocker une collection de fichiers dans un agrégat

Quand l’utiliser :
Utilisez ce modèle lorsqu’un agrégat doit stocker et gérer plusieurs fichiers connexes du même type comme un ensemble, plutôt que comme des champs nommés distincts. C’est idéal lorsque :

• Tous les fichiers partagent la même commande de mise à jour et les mêmes permissions.

• Les fichiers sont ajoutés, affichés et supprimés à partir d’une liste unifiée.

• Le nombre de fichiers peut changer au fil du temps.

Exemple :
Un enregistrement Project pourrait stocker des images de référence, des ébauches de conception ou des documents de support qui suivent tous les mêmes règles. Au lieu de créer un champ par fichier, stockez-les ensemble dans un seul champ de collection de fichiers pour une gestion plus simple.

---

1. Définir le champ de collection et la commande de mise à jour

• Ajoutez un champ de type File à l’agrégat.

• Marquez-le comme collection.

• Créez une commande (p. ex., updateFiles).

• Ajoutez le champ de collection de fichiers comme paramètre de commande.

---

2. Option la plus simple — affichage automatique avec gestion intégrée des fichiers

• Glissez-déposez la commande sur l’écran et sélectionnez « Automatic form ».

• Retirez les boutons Submit et Cancel.

• Dans le panneau Page Structure, sélectionnez la boîte qui possède le comportement Create a Command Form et activez auto-save.

Résultat :
Cela affiche automatiquement une liste de fichiers qui permet :

• Téléverser de nouveaux fichiers

• Supprimer des fichiers existants

• Télécharger des fichiers en cliquant dessus

Aucun câblage supplémentaire ni logique personnalisée n’est nécessaire.

---

3. Avancé — créer un affichage personnalisé

• Glissez-déposez le champ fichier sur l’écran.

• Choisissez Repeater comme type d’affichage.

• Glissez-déposez la commande et sélectionnez un type Button.

• Activez le Play mode, cliquez sur le bouton et sélectionnez un ou plusieurs fichiers à téléverser.

• Désactivez le Play mode.

• Stylisez le repeater pour correspondre à votre mise en page.

• Liez l’événement click sur les éléments du repeater pour exécuter la commande de mise à jour.

---

4. Prendre en charge la suppression de fichiers individuels (approche personnalisée)

Créer la commande de suppression :

• Créez une commande deleteFile.

• Ajoutez un paramètre storageId (type : Text).

• Créez un nouveau champ de mutation ciblant le champ de collection.

• Dans le champ de mutation, utilisez :

return data.files.reject({ storageId }).add({ $replace: true })

Câbler l’interface utilisateur :

• Dans le repeater, ajoutez un comportement Add Dependency avant Set Component Data :

  • Nom : parentData

  • Valeur : data

• Ajoutez une icône de corbeille à chaque carte du repeater.

• Sur l’événement onClick de l’icône de corbeille, ajoutez un comportement Show Custom Dialog.

• Dans le On submit du dialogue, exécutez :

parentData.removeFile({ storageId: data.storageId })

Stocker une collection de fichiers dans un agrégat où chaque fichier possède des champs propres au domaine

Quand l’utiliser

Choisissez cette approche lorsque chaque fichier est essentiellement une entité avec ses propres données et cycle de vie, et non une simple pièce jointe. Besoins typiques :

• Métadonnées personnalisées (p. ex., propriétaire, statut, étiquettes)

• Commandes métier (p. ex., Approve, Reject)

• Flux de travail / cycle de vie (p. ex., Draft → Approved → Archived)

Exemple :
Un Project possède une collection documents d’entités Document. Chaque Document a un seul fichier (content), plus des champs comme owner et status, et des commandes telles que Approve / Reject.

---

Définir le champ de collection et l’entité dans l’agrégat

1. Ajouter la collection à l’agrégat

• Créez un nouveau champ sur l’agrégat (p. ex., documents).

• Définissez son type à New Entity.

• Lorsque demandé, nommez l’entité Document.

• L’interface lie documents (collection) ↔ Document (entité).

2. Ajouter des champs à la nouvelle entité

• Dans Document, ajoutez un champ File (p. ex., content).

• Ajoutez les champs métier nécessaires (p. ex., owner, status, tags).

3. Créer la commande de mise à jour sur le parent

• Sur l’agrégat, créez updateDocuments (commande régulière, pas « Entity Create »).

• Ajoutez la collection documents comme paramètre, en vous assurant que le paramètre est défini comme collection (Is Collection).

• Définissez la mutation pour ce paramètre à Replace values.

4. Créer la commande de suppression sur l’entité

• Sur Document, ajoutez une commande Delete standard.

5. Configurer le dialogue de téléversement (sur updateDocuments)

• Ajoutez une Dialog declaration.

• Configurez le champ documents :

  componentId: @skyjs/data-model/web/DocumentsInput
  props: { "hidePreview": true, "fieldName": "content" }
  Hide label : true

  fieldName doit correspondre au seul champ File de l’entité.

6. Définir les valeurs par défaut lors de l’ajout de nouveaux fichiers

• Dans la propriété onChange du paramètre, utilisez :

  return newValue => newValue.assignNewDocumentsValues(
    { uploadDate: new DateTime(), owner: currentUser, status: 'DRAFT' },
    data
  );

  Ce code est l’occasion de définir des valeurs par défaut pour votre entité personnalisée lors de l’ajout de nouveaux fichiers. Vous pourriez, par exemple, définir l’utilisateur actuel comme propriétaire, initialiser un statut, ou appliquer toute autre métadonnée par défaut pertinente à votre domaine.

---

Interface utilisateur — Liste de fichiers automatique via formulaire de commande

• Glissez updateDocuments sur l’écran → choisissez Manual form.

• Retirez les boutons Submit et Cancel.

• Dans Page Structure, sélectionnez la boîte avec Create a Command Form → activez auto-save.

Résultat :
Une liste fonctionnelle qui prend en charge le téléversement, la suppression et le téléchargement.

Avec "hidePreview": true, les fichiers sélectionnés n’afficheront pas l’aperçu par défaut.
Définissez-le à false pour le nom de fichier / la taille, ou créez une vue personnalisée (ci-dessous) pour afficher les champs et actions du domaine.

---

Interface utilisateur — Cartes de documents personnalisées dans un Repeater

• Glissez la collection documents sur l’écran → choisissez Repeater.

• Glissez updateDocuments sur la page → choisissez un type Button.

• En Play mode, cliquez sur le bouton et sélectionnez un ou plusieurs fichiers ; quittez le Play mode.

• Stylisez le repeater.

• À l’intérieur de chaque carte :

  • Ajoutez la commande Delete (bouton / icône / lien).

  • Ajoutez vos commandes métier (p. ex., Approve / Reject).

  • Affichez les champs comme owner, status, tags, uploadDate.

• Pour permettre le téléchargement du fichier, attachez à un composant de nom de fichier ou à une icône de téléchargement un comportement Execute JavaScript :

window.location = await getFileUrl("get", data.content.storageId, data.name)

• data.content = le nom de votre champ content

• data.name = nom de fichier suggéré pour le téléchargement