Valores de Atributo

Los atributos son la forma en que OneEntry describe el contenido: una página, producto, bloque, usuario, pedido o campo de formulario lleva un mapa de valores de atributo indexados por marcador. El SDK normaliza cada atributo de cada respuesta a la misma forma, por lo que el mismo campo se ve igual sin importar qué módulo lo devolvió.

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 forma normalizada

Un valor de atributo es un IAttributeValue: { type, value, position?, additionalFields? }. Lo que value contiene depende de type:

Tipo de atributo	value
string, text	string
integer, float, real	number — convertido de la forma de cadena de la API
image, file con un archivo	el objeto de archivo en sí
image, file con varios archivos	un array de objetos de archivo
groupOfImages	siempre un array — es una colección por definición
list	un array
timeInterval	un array de grupos — ver Intervalos de Tiempo
sin valor establecido	siempre null

Los atributos de un solo archivo se desenvuelven

Cuando un atributo image o file contiene exactamente un archivo, su value es el objeto de archivo en sí. Solo los valores con dos o más archivos permanecen como un array.

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

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

Esto se aplica en cada módulo. Anteriormente, el desenvuelto solo se realizaba en productos, menús, formularios, campos de datos de formularios, conjuntos de atributos, colecciones de integración y Pages.searchPage, y solo en la clave attributeValues — en cualquier otro lugar (bloques, todos los demás métodos de páginas, Products.getProductsEmptyPage, Products.getProductBlockById, admins, descuentos, plantillas, pedidos, usuarios) el mismo atributo llegaba como un array de un elemento, por lo que los consumidores tenían que ramificarse según la forma. Los attributes de formularios, los campos de datos de formularios y los additionalFields anidados nunca se desenvuelven en absoluto.

⚠️ Migración: el código que lee value[0] de productos o menús no se ve afectado — esos módulos ya devolvían el objeto. El código que lee value[0] de bloques, páginas, usuarios o pedidos debe eliminar el índice.

groupOfImages es una colección por definición y siempre permanece como un array. En el lado de la solicitud, IBodyTypeFile.value está tipado como IFileValue | IFileValue[] en consecuencia.

Los números son números

Los valores integer, float y real se convierten a un número. real solía dejarse como una cadena, por lo que el mismo campo numérico llegaba al consumidor como 10 o como "10" dependiendo de cuál de los tres tipos se declarara:

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

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

La normalización numérica también se aplica a atributos de formularios y campos de datos de formularios, que se omitieron por completo — un campo de rating de un atributo de formulario integer es un number, no una cadena.

Al enviar datos, envía una cadena: IBodyTypeStringNumberFloat.value es string | number | null, y las respuestas llegan normalizadas.

Un valor vacío es siempre null

La API devuelve un mapa de localización vacío para un valor no establecido. El SDK solía pasarlo para tipos similares a texto, mientras que los tipos numéricos se convertían en null — el mismo estado de "sin valor" tenía tres representaciones. Ahora es siempre null.

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

⚠️ Migración: un integer/float no establecido ya no es 0. Number(null) es 0, por lo que un null explícito de la API solía informarse como un cero real — un valor indistinguible de un 0 configurado.

Todo está ordenado por posición

attributeValues siempre se ha devuelto en orden de position, y los attributes de formularios ahora también. La API devuelve los campos de formulario desordenados — un campo con position: 10 podría llegar después de position: 14 — por lo que renderizar un formulario en el orden del CMS requería ordenar en el lado del consumidor.

Un formulario sin atributos devuelve attributes: []. La API envía un objeto vacío en ese caso, y el SDK lo normaliza a un array vacío, por lo que attributes es siempre IFormAttribute[] y form.attributes.map(...) es seguro en cada formulario.

Campos anidados: additionalFields

Los valores de atributo anidados llegan bajo additionalFields. Por defecto, el SDK convierte el array que devuelve la API en un objeto indexado por marker; establece rawData: true en la configuración para mantener el array original — ver Formato de Campos Adicionales.

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

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

Los additionalFields anidados pasan por la misma normalización que los atributos de nivel superior — los archivos individuales se desenvuelven y los números también se convierten allí.

Tipando un valor de atributo

IAttributeValue.value está tipado como unknown, porque su forma depende de type. Redúcelo antes de usarlo — para atributos timeInterval, el SDK proporciona un guardia de tipo:

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 : '';
}

---

🔗 Documentación Relacionada

• Intervalos de Tiempo - expandiendo atributos timeInterval en slots
• Importando Tipos - IAttributeValue, IAttributeValues y el resto
• Módulo AttributesSets - cómo se configuran los atributos

---