Crear formularios adaptables mediante el esquema JSON creating-adaptive-forms-using-json-schema
Requisitos previos prerequisites
La creación de un formulario adaptable utilizando un esquema JSON como modelo de formulario requiere una comprensión básica del esquema JSON. Se recomienda leer el siguiente contenido antes de este artículo.
Usar un esquema JSON como modelo de formulario using-a-json-schema-as-form-model
AEM Forms admite la creación de un formulario adaptable mediante el uso de un esquema JSON existente como modelo de formulario. Este esquema JSON representa la estructura en la que el sistema back-end de su organización produce o consume datos. El esquema JSON que utilice debe cumplir con las especificaciones v4.
Las características clave del uso de un esquema JSON son:
- La estructura del JSON se muestra como un árbol en la pestaña Buscador de contenido en el modo de creación de un formulario adaptable. Puede arrastrar y agregar un elemento de la jerarquía JSON al formulario adaptable.
- Puede rellenar previamente el formulario utilizando un JSON que cumpla con el esquema asociado.
- En el envío, los datos especificados por el usuario se envían como JSON, que se adhiere al esquema asociado.
Un esquema JSON consta de tipos de elementos simples y complejos. Los elementos tienen atributos que agregan reglas al elemento. Cuando estos elementos y atributos se arrastran a un formulario adaptable, se asignan automáticamente al componente del formulario adaptable correspondiente.
Esta asignación de elementos JSON con componentes del formulario adaptable se produce de la siguiente forma:
Propiedades de esquema comunes common-schema-properties
El formulario adaptable utiliza la información disponible en el esquema JSON para asignar cada campo generado. En particular:
- La propiedad title sirve como etiqueta para los componentes de formulario adaptables.
- La propiedad description se define como una descripción larga para un componente de formulario adaptable.
- La propiedad predeterminada sirve como valor inicial de un campo de formulario adaptable.
- La propiedad maxLength se establece como atributo maxlength del componente de campo de texto.
- Las propiedades Minimum, Maximum, UniqueMinimum y exclusivoMaximum se utilizan para el componente Cuadro numérico.
- Para admitir el intervalo para el componente DatePicker, se proporcionan las propiedades adicionales del esquema JSON minDate y maxDate .
- Las propiedades minItems y maxItems se utilizan para restringir el número de elementos/campos que se pueden agregar o eliminar de un componente de panel.
- La propiedad readOnly establece el atributo de sólo lectura de un componente de formulario adaptable.
- La propiedad requerida marca el campo de formulario adaptable como obligatorio, mientras que en el caso de panel (donde el tipo es objeto), los datos JSON enviados finales tienen campos con el valor vacío correspondiente a ese objeto.
- La propiedad pattern se define como el patrón de validación (expresión regular) en forma adaptable.
- La extensión del archivo de esquema JSON debe mantenerse como .schema.json. Por ejemplo, <filename>.schema.json.
Ejemplo de esquema JSON sample-json-schema
Este es un ejemplo de esquema JSON.
{
"$schema": "https://json-schema.org/draft-04/schema#",
"definitions": {
"employee": {
"type": "object",
"properties": {
"userName": {
"type": "string"
},
"dateOfBirth": {
"type": "string",
"format": "date"
},
"email": {
"type": "string",
"format": "email"
},
"language": {
"type": "string"
},
"personalDetails": {
"$ref": "#/definitions/personalDetails"
},
"projectDetails": {
"$ref": "#/definitions/projectDetails"
}
},
"required": [
"userName",
"dateOfBirth",
"language"
]
},
"personalDetails": {
"type": "object",
"properties": {
"GeneralDetails": {
"$ref": "#/definitions/GeneralDetails"
},
"Family": {
"$ref": "#/definitions/Family"
},
"Income": {
"$ref": "#/definitions/Income"
}
}
},
"projectDetails": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
},
"projects": {
"$ref": "#/definitions/projects"
}
}
},
"minItems": 1,
"maxItems": 4
},
"projects": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
},
"projectsAdditional": {
"$ref": "#/definitions/projectsAdditional"
}
}
},
"minItems": 1,
"maxItems": 4
},
"projectsAdditional": {
"type": "array",
"items": {
"properties": {
"Additional_name": {
"type": "string"
},
"Additional_areacode": {
"type": "number"
}
}
},
"minItems": 1,
"maxItems": 4
},
"GeneralDetails": {
"type": "object",
"properties": {
"age": {
"type": "number"
},
"married": {
"type": "boolean"
},
"phone": {
"type": "number",
"aem:afProperties": {
"sling:resourceType": "/libs/fd/af/components/guidetelephone",
"guideNodeClass": "guideTelephone"
}
},
"address": {
"type": "string"
}
}
},
"Family": {
"type": "object",
"properties": {
"spouse": {
"$ref": "#/definitions/spouse"
},
"kids": {
"$ref": "#/definitions/kids"
}
}
},
"Income": {
"type": "object",
"properties": {
"monthly": {
"type": "number"
},
"yearly": {
"type": "number"
}
}
},
"spouse": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"Income": {
"$ref": "#/definitions/Income"
}
}
},
"kids": {
"type": "array",
"items": {
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
}
}
},
"minItems": 1,
"maxItems": 4
}
},
"type": "object",
"properties": {
"employee": {
"$ref": "#/definitions/employee"
}
}
}
Definiciones de esquema reutilizables reusable-schema-definitions
Las claves de definición se utilizan para identificar esquemas reutilizables. Las definiciones de esquema reutilizables se utilizan para crear fragmentos. Es similar a identificar tipos complejos en XSD. A continuación, se muestra un ejemplo de un esquema JSON con definiciones:
{
"$schema": "https://json-schema.org/draft-04/schema#",
"definitions": {
"address": {
"type": "object",
"properties": {
"street_address": { "type": "string" },
"city": { "type": "string" },
"state": { "type": "string" }
},
"required": ["street_address", "city", "state"]
}
},
"type": "object",
"properties": {
"billing_address": { "$ref": "#/definitions/address" },
"shipping_address": { "$ref": "#/definitions/address" }
}
}
El ejemplo anterior define un registro de cliente en el que cada cliente tiene una dirección de envío y de facturación. La estructura de ambas direcciones es la misma (las direcciones tienen una dirección de calle, una ciudad y un estado), por lo que no se recomienda duplicar las direcciones. También facilita la el hecho de agregar o eliminar campos para cualquier cambio futuro.
Preconfigurar campos en la definición del esquema JSON pre-configuring-fields-in-json-schema-definition
Puede usar la propiedad aem:afProperties para preconfigurar el campo del esquema JSON y asignarlo a un componente de formulario adaptable personalizado. A continuación se muestra un ejemplo:
{
"properties": {
"sizeInMB": {
"type": "integer",
"minimum": 16,
"maximum": 512,
"aem:afProperties" : {
"sling:resourceType" : "/apps/fd/af/components/guideTextBox",
"guideNodeClass" : "guideTextBox"
}
}
},
"required": [ "sizeInMB" ],
"additionalProperties": false
}
Limitar los valores aceptables para un componente de formulario adaptable limit-acceptable-values-for-an-adaptive-form-component
Puede agregar las siguientes restricciones a los elementos del esquema JSON para limitar los valores aceptables para un componente de formulario adaptable:
Construcciones no compatibles non-supported-constructs
Los formularios adaptables no admiten las siguientes construcciones de esquema JSON:
- Tipo nulo
- Tipos de unión, como any y
- OneOf, AnyOf, AllOf y NOT
- Solo es compatible con matrices homogéneas. Por lo tanto, la restricción de elementos debe ser un objeto y no una matriz.
Preguntas frecuentes frequently-asked-questions
¿Por qué no puedo arrastrar elementos individuales de un subformulario (estructura generada a partir de cualquier tipo complejo) para subformularios repetibles (los valores minOccours o maxOccurs son superiores a 1)?
En un subformulario repetible, debe utilizar el subformulario completo. Si solo le interesan los campos selectivos, utilice toda la estructura y elimine los no deseados.
Tengo una estructura larga y compleja en el Buscador de contenido. ¿Cómo puedo encontrar un elemento específico?
Tiene dos opciones:
- Desplazarse por la estructura de árbol
- Utilizar el cuadro Buscar para buscar un elemento