Aller au contenu principal

Valeurs d'attributs

Les attributs sont la manière dont OneEntry décrit le contenu : une page, un produit, un bloc, un utilisateur, une commande ou un champ de formulaire porte une carte de valeurs d'attributs indexées par marqueur. Le SDK normalise chaque attribut de chaque réponse à la même forme, de sorte que le même champ ait le même aspect peu importe le module qui l'a renvoyé.

const page = await Pages.getPageByUrl('catalog');

page.attributeValues.title.value;   // "Catalog"        — string
page.attributeValues.amount.value;  // 5                — number
page.attributeValues.cover.value;   // { downloadLink } — the file object itself
page.attributeValues.notes.value;   // null             — no value set

La forme normalisée​

Une valeur d'attribut est un IAttributeValue : { type, value, position?, additionalFields? }. Ce que value contient dépend de type :

Type d'attributvalue
string, textstring
integer, float, realnumber — converti à partir de la forme chaîne de l'API
image, file avec un fichierl'objet fichier lui-même
image, file avec plusieurs fichiersun tableau d'objets fichier
groupOfImagestoujours un tableau — c'est une collection par définition
listun tableau
timeIntervalun tableau de groupes — voir Intervalles de temps
aucune valeur définietoujours null

Les attributs à fichier unique sont déballés​

Lorsqu'un attribut image ou file contient exactement un fichier, sa value est l'objet fichier lui-même. Seules les valeurs avec deux fichiers ou plus restent un tableau.

const block = await Blocks.getBlockByMarker('promo');

// before: block.attributeValues.img.value[0].downloadLink
// now:    block.attributeValues.img.value.downloadLink

Cela s'applique dans chaque module. Auparavant, le déballage ne se faisait que dans les produits, les menus, les formulaires, les champs de données de formulaire, les ensembles d'attributs, les collections d'intégration et Pages.searchPage, et uniquement sur la clé attributeValues — partout ailleurs (blocs, toutes les autres méthodes de pages, Products.getProductsEmptyPage, Products.getProductBlockById, admins, remises, modèles, commandes, utilisateurs) le même attribut arrivait sous forme de tableau à un élément, donc les consommateurs devaient se ramifier sur la forme. Les attributes de formulaire, les champs de données de formulaire et les additionalFields imbriqués n'étaient jamais déballés.

⚠️ Migration : le code qui lit value[0] à partir des produits ou des menus n'est pas affecté — ces modules renvoyaient déjà l'objet. Le code qui lit value[0] à partir des blocs, pages, utilisateurs ou commandes doit abandonner l'index.

groupOfImages est une collection par définition et reste toujours un tableau. Du côté de la requête, IBodyTypeFile.value est typé IFileValue | IFileValue[] en conséquence.

Les nombres sont des nombres​

Les valeurs integer, float et real sont converties en nombre. real était auparavant laissé sous forme de chaîne, donc le même champ numérique atteignait le consommateur sous la forme 10 ou "10" selon le type avec lequel il avait été déclaré :

const page = await Pages.getPageByUrl('catalog');

// before: page.attributeValues.amount.value // "5"
// now:    page.attributeValues.amount.value // 5

La normalisation numérique s'applique également aux attributs de formulaire et aux champs de données de formulaire, qui étaient entièrement ignorés — un champ rating d'un attribut de formulaire integer est un number, pas une chaîne.

Lors de l'envoi de données, envoyez une chaîne : IBodyTypeStringNumberFloat.value est string | number | null, et les réponses reviennent normalisées.

Une valeur vide est toujours null​

L'API renvoie une carte de localisation vide pour une valeur non définie. Le SDK avait l'habitude de la transmettre pour les types de texte, tandis que les types numériques devenaient null — le même état "sans valeur" avait trois représentations. C'est maintenant toujours null.

if (page.attributeValues.notes.value === null) {
  // nothing configured for this attribute
}

⚠️ Migration : un integer/float non défini n'est plus 0. Number(null) est 0, donc un null explicite de l'API était auparavant signalé comme un vrai zéro — une valeur indiscernable d'un 0 configuré.

Tout est trié par position​

attributeValues a toujours été renvoyé dans l'ordre de position, et les attributes de formulaire le sont maintenant aussi. L'API renvoie les champs de formulaire dans un ordre non trié — un champ avec position: 10 pourrait arriver après position: 14 — donc le rendu d'un formulaire dans l'ordre CMS nécessitait un tri du côté du consommateur.

Un formulaire sans attributs renvoie attributes: []. L'API envoie un objet vide dans ce cas, et le SDK le normalise en un tableau vide, donc attributes est toujours IFormAttribute[] et form.attributes.map(...) est sûr sur chaque formulaire.

Champs imbriqués : additionalFields​

Les valeurs d'attributs imbriquées arrivent sous additionalFields. Par défaut, le SDK convertit le tableau que l'API renvoie en un objet indexé par marker ; définissez rawData: true dans la configuration pour conserver le tableau original — voir Format des champs supplémentaires.

// default (rawData: false)
attribute.additionalFields['my_field'].value;

// rawData: true
attribute.additionalFields.find((f) => f.marker === 'my_field').value;

Les additionalFields imbriqués passent par la même normalisation que les attributs de premier niveau — les fichiers uniques sont déballés et les nombres sont également convertis.

Typage d'une valeur d'attribut​

IAttributeValue.value est typé unknown, car sa forme dépend de type. Rétrécissez-le avant utilisation — pour les attributs timeInterval, le SDK fournit un garde de type :

import { isTimeIntervalAttribute } from 'oneentry';
import type { IAttributeValues } from 'oneentry';

function readText(values: IAttributeValues, marker: string): string {
  const value = values[marker]?.value;
  return typeof value === 'string' ? value : '';
}

🔗 Documentation Connexe​