Saltar al contenido principal

​
Resumen

Los Attributes te permiten agregar campos custom a los objetos de CXF —Contacts, Orders, Documents, Content Instances y más— sin cambiar ningún schema. Cada attribute tiene un tipo que se valida automáticamente, puede contener un solo valor o un array, puede agruparse en estructuras anidadas, y puede scopearse a un Template o Profile específico. Para el modelo mental de cómo encajan los campos custom en el modelo de objetos compartido, consulta Conceptos básicos.

​
Dónde encontrarlo

Los Attributes se configuran dentro de un Template o Profile —por ejemplo, en un Content Template, un Order Template o un Contact Profile—. En la UI, las Properties de un objeto (sus campos fijos) y sus Attributes (campos custom) se muestran como grupos separados.

​
Properties

La definición de un attribute tiene las siguientes properties configurables:
PropertyTipoRequeridoDefaultDescripción
titlestringSí—Nombre visible del campo.
slugstringSí—Identificador, único dentro de su object type, Template y grupo padre.
object_typeenumSí—El tipo de objeto que extiende el campo — ver Object types.
data_typeenumSí—El tipo de dato que contiene el campo (ver Tipos de attribute).
appearanceenumSí—Cómo se presenta y se valida el campo dentro de su data type.
descriptionstringNo—Descripción interna del campo.
help_textstringNo—Guía mostrada a quien llena el campo.
placeholderstringNo—Texto placeholder del input.
is_requiredbooleanNofalseSi el valor es obligatorio.
is_arraybooleanNofalseSi el campo contiene múltiples valores.
is_editablebooleanNotrueSi el valor se puede cambiar después de crearse.
is_visiblebooleanNotrueSi el campo se muestra en la UI.
is_searchablebooleanNotrueSi el campo se puede buscar.
is_listablebooleanNotrueSi el campo aparece en las vistas de lista.
is_disabledbooleanNofalseSi el campo está desactivado.
is_unboundbooleanNofalseSi el campo se expone en la vista unbound (ver la nota abajo).
is_systembooleanNofalseMarca un campo integrado — visible, pero protegido de edición y borrado.
has_indexbooleanNofalseSi el campo está indexado para búsqueda y filtrado más rápidos.
allow_facetsbooleanNofalseSi el campo se puede usar como faceta de búsqueda.
optionsarrayNo—Valores permitidos, para el appearance list.
validationsobjectNo—Reglas de validación configurables del tipo — ver Reglas configurables.
parent_idreferenceNo—Grupo padre, para campos anidados.
template_idreferenceCondicional—El Template al que se scopea el campo, para object types basados en templates.
Campos unbound. Un usuario autenticado que abre un registro que no posee solo ve sus campos unbound — el subconjunto público y no sensible. Marca un attribute con is_unbound: true para incluirlo en esa vista; de lo contrario queda privado y requiere ownership. El scoping por Profile y Template sigue aplicando.

​
Tipos de attribute

El tipo de un attribute —la combinación de su data_type y appearance— determina cómo se presenta y se valida su valor, y qué reglas extra puedes configurar. Consulta la lista completa en su propia página:

Attribute types

Cada data type y appearance, con su validación y reglas configurables.
Los campos de texto corto en Content Instances y Documents también pueden usar una convención de nombrado auto-incremental — un patrón año/mes/contador que genera el valor cuando se crea el registro.

​
Comportamiento y reglas

  • Los campos deben definirse primero. Solo puedes asignar un campo custom que exista como definición de attribute para ese object type (y que coincida con el Template o Profile). Asignar un campo no definido se rechaza con The attribute <slug> is not allowed.
  • Validación type-safe. Cada valor se valida contra su tipo (ver Tipos de attribute). Los valores inválidos se rechazan con un mensaje claro, por ejemplo:
    • The attribute <slug> must be a number.
    • The attribute <slug> must be one of: active, inactive, pending.
    • The attribute <slug> must be an image.
  • Las reglas de requerido y array se aplican desde is_required e is_array.
  • Los grupos validan recursivamente — un attribute group valida cada hijo anidado contra su propio tipo, hasta 3 niveles de profundidad.
  • Indexado para búsqueda. Los campos marcados con has_index se indexan para búsqueda y filtrado más rápidos. Solo los tipos text, number, boolean y location se pueden indexar.
  • Los campos en uso están protegidos. Un attribute cuyo Template ya tiene instancias (o cuyo Profile ya tiene registros asociados) se considera en uso y no se puede borrar.

​
Relationships

  • Objeto host — todo attribute extiende un object type: Contacts, Organizations, Users, Orders, Documents, Content Instances y Content Versions.
  • Scoping — los attributes se scopean por Templates (Content Instances, Content Versions, Orders, Documents) o Profiles (Contacts, Organizations, Users), lo que controla exactamente qué campos aplican a un registro dado.
  • Los attributes de tipo media referencian assets en el DAM.
  • Los attributes group contienen attributes hijos anidados.
Attributes vs Properties. Las Properties son los campos fijos e integrados que CXF define para un objeto — su estructura base, el mínimo que necesita para existir. Los Attributes son los campos custom que agregas encima para extenderlo. Sus valores viven uno al lado del otro en el objeto; la UI normalmente los presenta como grupos separados.

​
Seeds

Este objeto se puede mover entre entornos con Seeds:
Tipo de seedSoportadoNotas
StructuralSíLas definiciones de attribute viajan como configuración estructural.
InstanceNoLos attributes definen estructura, no instancias de templates.

​
Un attribute en un seed

En un seed estructural, cada attribute es un ítem con object_type: "attributes" y un objeto data con sus campos. Crea el grupo primero, y luego haz que cada campo hijo lo referencie mediante parent_id (resuelto por el helper getAttributeGroup) y use un full_slug con puntos: 
[
  {
    "object_type": "attributes",
    "data": {
      "title": "Default",
      "slug": "default",
      "data_type": "group",
      "appearance": "default",
      "object_type": "content_versions",
      "template_type": "stories",
      "template_id": "{{getRecordAttribute('content_templates', 'slug', 'blog')}}",
      "full_slug": "default"
    }
  },
  {
    "object_type": "attributes",
    "data": {
      "title": "Cover Image",
      "slug": "cover_image",
      "data_type": "media",
      "appearance": "image",
      "is_required": true,
      "object_type": "content_versions",
      "template_type": "stories",
      "template_id": "{{getRecordAttribute('content_templates', 'slug', 'blog')}}",
      "parent_id": "{{getAttributeGroup('content_versions', 'default', 'blog', 'stories')}}",
      "full_slug": "default.cover_image"
    }
  }
]

​
Gobernanza y permisos

  • Quién puede gestionar attributes. Solo un super admin o un Master puede crear, editar o borrar definiciones de attribute. No hay permisos por módulo.
  • El scoping aísla los campos. El scoping por Template y Profile mantiene separados los attributes de cada Template o Profile.
  • La visibilidad y la edición se controlan con is_visible, is_editable e is_disabled.
  • Los system attributes (is_system) están protegidos de edición y borrado.
  • Los attributes en uso no se pueden borrar (ver Comportamiento y reglas).

​
Acceso por API

Las definiciones de attribute se crean y gestionan en la UI de CXF (dentro de un Template o Profile) — no se pueden crear actualmente por API. Los valores de attribute en un registro se leen y escriben como cualquier otro campo de ese objeto a través de la API reference.

​
Límites y cuotas

  • Los attributes group anidados se validan hasta 3 niveles de profundidad. Fuera de eso, no hay un límite fijo en la cantidad de attributes por objeto ni en la longitud de un attribute de tipo array.

​
Relacionado

Profiles

Agrupa attributes en Profiles para Contacts, Organizations y Users.

DAM

De donde los attributes media e image obtienen sus assets.

API reference

Gestiona attributes y valores programáticamente.