Diseño de un esquema JSON para un formulario adaptable

Requisitos previos

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.

Uso de un esquema JSON como modelo de formulario

Adobe Experience Manager 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 Especificaciones de la versión 4.

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 JSON que cumpla con el esquema asociado.
  • Al enviar, los datos introducidos por el usuario se envían como JSON que se adhieren 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 de formulario adaptable correspondiente.

Esta asignación de elementos JSON con componentes de formulario adaptable es la siguiente:

"birthDate": {
              "type": "string",
              "format": "date",
              "pattern": "date{DD MMMM, YYYY}",
              "aem:affKeyword": [
                "DOB",
                "Date of Birth"
              ],
              "description": "Date of birth in DD MMMM, YYYY",
              "aem:afProperties": {
                "displayPictureClause": "date{DD MMMM, YYYY}",
                "displayPatternType": "date{DD MMMM, YYYY}",
                "validationPatternType": "date{DD MMMM, YYYY}",
                "validatePictureClause": "date{DD MMMM, YYYY}",
                "validatePictureClauseMessage": "Date must be in DD MMMM, YYYY format."
              }
Elemento, propiedades o atributos JSON Componente de formulario adaptable

Propiedades de cadena con restricción enum y enumNames.

Sintaxis,

{

"type" : "string",

"enum" : ["M", "F"]

"enumNames" : ["Male", "Female"]

}

Componente desplegable:

  • Los valores enumerados en enumNames se muestran en el cuadro desplegable.
  • Los valores enumerados en la enumeración se utilizan para el cálculo.

Propiedad de cadena con restricción de formato. Por ejemplo, correo electrónico y fecha.

Sintaxis,

{

"type" : "string",

"format" : "email"

}

  • El componente Correo electrónico se asigna cuando el tipo es cadena y el formato es correo electrónico.
  • El componente de cuadro de texto con validación se asigna cuando el tipo es cadena y el formato es nombre de host.

{

"type" : "string",

}



Campo de texto


number, propiedad
Campo numérico con subtipo definido como flotante
integer, propiedad
Campo numérico con subtipo definido como entero
propiedad booleana
Cambiar
propiedad object
Panel
propiedad array Panel repetible con mínimo y máximo igual a minItems y maxItems respectivamente. Solo se admiten matrices homogéneas. Por lo tanto, la restricción de elementos debe ser un objeto y no una matriz.

Propiedades de esquema comunes

El formulario adaptable utiliza la información disponible en el esquema JSON para asignar cada campo generado. En particular:

  • La variable title sirve como etiqueta para los componentes del formulario adaptable.
  • La variable description se define como una descripción larga para un componente de formulario adaptable.
  • La variable default sirve como valor inicial de un campo de formulario adaptable.
  • La variable maxLength la propiedad se establece como maxlength del componente de campo de texto.
  • La variable minimum, maximum, exclusiveMinimumy exclusiveMaximum las propiedades se utilizan para el componente de cuadro numérico.
  • Para admitir el intervalo para DatePicker component propiedades de esquema JSON adicionales minDate y maxDate se proporcionan.
  • La variable minItems y maxItems las propiedades se utilizan para restringir el número de elementos/campos que se pueden agregar o eliminar de un componente de panel.
  • La variable readOnly la propiedad define el readonly de un componente Formulario adaptable.
  • La variable required la propiedad marca el campo Formulario adaptable como obligatorio, mientras que en el panel (donde el tipo es objeto), los datos JSON enviados finales tienen campos con el valor vacío correspondiente a ese objeto.
  • La variable pattern se define como el patrón de validación (expresión regular) en el formulario adaptable.
  • La extensión del archivo de esquema JSON debe conservarse como .schema.json. Por ejemplo, <filename>.schema.json.

Esquema JSON de muestra

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

Las claves de definición se utilizan para identificar esquemas reutilizables. Las definiciones de esquema reutilizables se utilizan para crear fragmentos. A continuación se muestra un ejemplo de 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 es aconsejable no duplicar las direcciones. También facilita la adición y eliminación de campos para cualquier cambio futuro.

Preconfiguración de campos en la definición del esquema JSON

Puede usar la variable aem:afProperties para preconfigurar el campo Esquema JSON para 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
}

Límite de valores aceptables para un componente Formulario adaptable

Puede añadir las siguientes restricciones a los elementos del esquema JSON para limitar los valores aceptables para un componente de formulario adaptable:

Propiedad Schema

Tipo de datos

Descripción

Componente

maximum

Cadena

Especifica el límite superior de valores numéricos y fechas. De forma predeterminada, se incluye el valor máximo.

  • Cuadro numérico
  • Stepper numérico
  • Selector de fecha

minimum

Cadena

Especifica el límite inferior de valores numéricos y fechas. De forma predeterminada, se incluye el valor mínimo.

  • Cuadro numérico
  • Stepper numérico
  • Selector de fecha

exclusiveMaximum

Booleano

Si es true, el valor numérico o la fecha especificados en el componente del formulario deben ser menores que el valor numérico o la fecha especificados para la propiedad máxima.

Si es false, el valor numérico o la fecha especificados en el componente del formulario deben ser menores o iguales que el valor numérico o la fecha especificados para la propiedad maximum.

  • Cuadro numérico
  • Stepper numérico
  • Selector de fecha

exclusiveMinimum

Booleano

Si es true, el valor numérico o la fecha especificados en el componente del formulario deben ser buenos que el valor numérico o la fecha especificados para la propiedad Minimum.

Si es false, el valor numérico o la fecha especificados en el componente del formulario deben ser buenos o iguales al valor numérico o la fecha especificados para la propiedad Minimum.

  • Cuadro numérico
  • Stepper numérico
  • Selector de fecha

minLength

Cadena

Especifica el número mínimo de caracteres permitidos en un componente. La longitud mínima debe ser igual o buena que cero.

  • Cuadro de texto
maxLength Cadena Especifica el número máximo de caracteres permitidos en un componente. La longitud máxima debe ser igual o buena a cero.
  • Cuadro de texto

pattern

Cadena

Especifica la secuencia de los caracteres. Un componente acepta los caracteres si se ajustan al patrón especificado.

La propiedad pattern se asigna al patrón de validación del componente de formulario adaptable correspondiente.

  • Todos los componentes de Forms adaptable asignados a un esquema XSD
maxItems Cadena Especifica el número máximo de elementos de una matriz. Los elementos máximos deben ser iguales o buenos a cero.
minItems Cadena Especifica el número mínimo de elementos de una matriz. Los elementos mínimos deben ser iguales o buenos que cero.

Construcciones no compatibles

Forms adaptable no admite las siguientes construcciones de esquema JSON:

  • Tipo nulo
  • Tipos de unión, como cualquier, y
  • OneOf, AnyOf, AllOf y NOT
  • Solo se admiten matrices homogéneas. Por lo tanto, la restricción de elementos debe ser un objeto y no una matriz.

Preguntas frecuentes

¿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 buenos a 1)?

En un subformulario repetible, debe utilizar el subformulario completo. Si solo desea campos selectivos, utilice toda la estructura y elimine los no deseados.

Tengo una estructura compleja y larga en el Buscador de Contenido. ¿Cómo puedo encontrar un elemento específico?

Tiene dos opciones:

  • Desplácese por la estructura de árbol
  • Utilice el cuadro Buscar para buscar un elemento

¿Cuál debe ser la extensión del archivo de esquema JSON?

La extensión del archivo de esquema JSON debe ser .schema.json. Por ejemplo, <filename>.schema.json.

En esta página