Groupes, collections et valeurs initiales

Un group produit un objet nommé ; une collection produit une liste d'éléments de même schéma. Ses éléments peuvent eux-mêmes être des groupes ou des collections. Voir schéma et types.

Quatre moments distincts

Moment	Valeurs utilisées
Installation initiale / calcul des défauts	defaults[langue], sinon default, sinon le défaut propre au type.
Ajout manuel d'un élément de collection	wuOptions.prototypeDatas[langue], sinon wuOptions.prototypeData.
Mise à jour de l'appli	Anciennes valeurs compatibles ou migrations, avec les nouveaux défauts pour ce qui n'est pas repris.
Réinitialisation volontaire	Action explicite sur les réglages ; changer le default du schéma ne réinitialise pas les installations existantes.

Un défaut localisé remplace le défaut général ; ne le considère pas comme un patch à fusionner avec lui. Les valeurs false, 0, null et une collection vide doivent être traitées selon le contrat du champ, sans les confondre avec un chemin absent.

Le default d'un groupe est un objet ; celui d'une collection est un tableau. Pour une collection de groupes, fournis des objets correspondant aux enfants de groupItems.

Exemple complet de collection

Objet à exporter depuis preferences.config.js :

{
  "type": "group",
  "groupItems": {
    "rounds": {
      "type": "collection",
      "label": { "fr": "Manches", "en": "Rounds" },
      "collectionItems": {
        "type": "group",
        "label": "@self.title",
        "groupItems": {
          "title": { "type": "string", "required": true },
          "points": { "type": "number", "wuOptions": { "min": 0 } }
        }
      },
      "default": [{ "title": "Round 1", "points": 10 }],
      "defaults": { "fr": [{ "title": "Manche 1", "points": 10 }] },
      "wuOptions": {
        "minCount": 0,
        "maxCount": 20,
        "sortable": true,
        "confirmDelete": true,
        "addButtonLabel": { "fr": "Ajouter une manche", "en": "Add round" },
        "prototypeData": { "title": "New round", "points": 5 },
        "prototypeDatas": { "fr": { "title": "Nouvelle manche", "points": 5 } }
      }
    }
  }
}

En français, la liste initiale contient « Manche 1 », 10 points. Le bouton d'ajout préremplit « Nouvelle manche », 5 points. Placer seulement un default dans le champ enfant n'est pas la recette de préremplissage du bouton d'ajout.

minCount / maxCount bornent le nombre d'éléments. Le calcul initial complète une liste plus courte que minCount avec les défauts du schéma d'élément ; ce mécanisme est distinct du prototype d'ajout. sortable active le tri ; confirmDelete demande confirmation avant suppression dans le formulaire.

Pour une liste de chaînes, utilise collectionItems: { type: 'string' }, un default: ['A', 'B'] et wuOptions.prototypeData: 'Nouvelle valeur'. La valeur runtime est un tableau de chaînes.

Lecture, identités et écriture

const rounds = kapp.preferences.get('rounds') ?? [];
for (const round of rounds) {
    console.info(round.title, round.points);
}

Les collections de groupes transportent des identifiants techniques, notamment _uuid. Préserve les propriétés d'un élément existant si tu le réécris. Ne fabrique pas de nouveaux identifiants pour de simples modifications de libellé : les triggers et les variantes peuvent dépendre de ces identités.

Les collections scalaires sont exposées comme des valeurs nues. Le formulaire et le stockage utilisent en interne un groupe avec scalarCollectionItem et des métadonnées ; n'ajoute pas cette enveloppe à ta lecture runtime.

set([{ path: 'rounds', data: nouvelleListe }]) remplace une valeur de préférence. Ce n'est pas une API générique d'ajout atomique ou de compteur : une copie locale peut être ancienne lorsqu'un autre éditeur intervient. Pour les données métier concurrentes, préfère les stockages dédiés. Une collection est surchargée en bloc dans les variantes.

Tags des valeurs initiales

Les chaînes compatibles peuvent contenir des tags ##channel_name## remplacés par les valeurs du channel lors du calcul/hydratation des préférences. Les tags simples #channel_name# restent destinés à un traitement ultérieur, notamment par le moteur d'annonces.

Clés disponibles : channel_name, channel_login, channel_display_name, channel_background_color, channel_primary_color, channel_secondary_color, channel_font_color, channel_currency_name, channel_currency_symbol, channel_command_symbol, channel_language.

Les prototypes de collection passent aussi par le remplacement des tags. Le comportement précis dépend du type composé : pour les annonces, utilise la fiche dédiée.