Show Menu
TEMAS×

Creación de formularios adaptables mediante el esquema JSON

Requisitos previos

La creación de un formulario adaptable con 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

AEM Forms admite la creación de un formulario adaptable mediante 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 de v4.
Las características clave del uso de un esquema JSON son:
  • La estructura del JSON se muestra como un árbol en la ficha Buscador de contenido en el modo de creación de un formulario adaptable. Puede arrastrar y agregar elementos de la jerarquía JSON al formulario adaptable.
  • Puede rellenar previamente el formulario con JSON que sea compatible con el esquema asociado.
  • Al enviar, los datos introducidos por el usuario se envían como JSON que se alinean con el 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 adaptables 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 configurado para flotar
integer, propiedad Campo numérico con subtipo definido como entero
boolean, propiedad Cambiar
object property Panel
array, propiedad 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 items 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 propiedad title sirve como etiqueta para los componentes del formulario adaptable.
  • 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 el atributo maxlength del componente de campo de texto.
  • Para el componente de cuadro numérico se utilizan las propiedades Minimum, Maximum, uniqueMinimum y uniqueMaximum como mínimo.
  • Para admitir el intervalo para el componente DatePicker, se proporcionan las propiedades adicionales minDate y maxDate del esquema JSON.
  • Las propiedades minItems y maxItems se utilizan para restringir el número de elementos o campos que se pueden agregar o quitar de un componente de panel.
  • La propiedad readOnly establece el atributo de sólo lectura de un componente de formulario adaptable.
  • La propiedad required marca el campo de formulario adaptable como obligatorio, mientras que en el caso de panel (donde type es object), los datos JSON enviados por última vez 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 conservarse como .schema.json. Por ejemplo, <filename>.schema.json.

Esquema JSON de muestra

Este es un ejemplo de un 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. Es similar a identificar tipos complejos en XSD. A continuación se muestra un esquema JSON de muestra 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, donde cada cliente tiene una dirección de envío y una dirección de facturación. La estructura de ambas direcciones es la misma: las direcciones tienen una dirección, ciudad y estado— por lo tanto, es recomendable no duplicar las direcciones. También facilita la adición y eliminación de campos para cualquier cambio futuro.

Configuración previa de campos en la definición de esquema JSON

Puede utilizar la propiedad aem:afProperties para preconfigurar el campo 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
}

Configuración de secuencias de comandos o expresiones para objetos de formulario

JavaScript es el lenguaje de expresión de los formularios adaptables. Todas las expresiones son expresiones JavaScript válidas y utilizan API de modelos de secuencias de comandos de formularios adaptables. Puede configurar previamente los objetos de formulario para evaluar una expresión en un suceso de formulario.
Utilice la propiedad aem:afproperties para preconfigurar expresiones de formulario adaptables o secuencias de comandos para componentes de formulario adaptables. Por ejemplo, cuando se activa el suceso initialize, el código siguiente establece el valor del campo telefónico e imprime un valor en el registro:
"telephone": {
  "type": "string",
  "pattern": "/\\d{10}/",
  "aem:affKeyword": ["phone", "telephone","mobile phone", "work phone", "home phone", "telephone number", "telephone no", "phone number"],
  "description": "Telephone Number",
  "aem:afProperties" : {
    "sling:resourceType" : "fd/af/components/guidetelephone",
    "guideNodeClass" : "guideTelephone",
    "events": {
      "Initialize" : "this.value = \"1234567890\"; console.log(\"ef:gh\") "
    }
  }
}

Debe ser miembro del grupo de formularios de usuario avanzado para configurar secuencias de comandos o expresiones para el objeto de formulario. En la tabla siguiente se enumeran todos los sucesos de secuencia de comandos admitidos para un componente de formulario adaptable.
Componente \ Evento initialize Calcular Visibilidad Validar Activado Implementación de valor Haga clic Opciones
Campo de texto
Campo numérico
Stepper numérico
Botón de opción
Teléfono
Cambiar
Botón
Casilla de verificación
Desplegable
Opción de imagen
Campo de introducción de fecha
Selector de fecha
Correo electrónico
Archivo adjunto
Imagen
Draw
Panel
Algunos ejemplos de uso de eventos en un JSON están ocultando un campo en el evento initialize y configurando el valor de otro campo en el evento value commit. Para obtener información detallada sobre la creación de expresiones para los sucesos de secuencia de comandos, consulte Expresiones de formulario adaptables.
Este es el código JSON de muestra para los ejemplos mencionados.

Ocultar un campo en el suceso initialize

"name": {
    "type": "string",
    "aem:afProperties": {
        "events" : {
            "Initialize" : "this.visible = false;"
        }
    }
}

Configurar el valor de otro campo en el evento de confirmación de valor

"Income": {
    "type": "object",
    "properties": {
        "monthly": {
            "type": "number",
            "aem:afProperties": {
                "events" : {
                    "Value Commit" : "IncomeYearly.value = this.value * 12;"
                }
            }
        },
        "yearly": {
            "type": "number",
            "aem:afProperties": {
                "name": "IncomeYearly"
            }
        }
    }
}

Límite de valores aceptables para un componente de formulario adaptable

Puede agregar las siguientes restricciones a los elementos de esquema JSON para limitar los valores aceptables para un componente de formulario adaptable:
Propiedad de esquema
Tipo de datos
Descripción
Componente
maximum
Cadena
Especifica el límite superior de los valores numéricos y las 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 los valores numéricos y las 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 debe ser menor o igual que el valor numérico o la fecha especificados para la propiedad máxima.
  • 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 mayores que el valor numérico o la fecha especificados para la propiedad mínima.
Si es false, el valor numérico o la fecha especificados en el componente del formulario deben ser mayores o iguales que el valor numérico o la fecha especificados para la propiedad mínima.
  • 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 mayor 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 mayor que cero.
  • Cuadro de texto
pattern
Cadena
Especifica la secuencia de los caracteres. Un componente acepta los caracteres si éstos 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 formularios adaptables 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 mayores que cero.
minItems Cadena Especifica el número mínimo de elementos de una matriz. Los elementos mínimos deben ser iguales o mayores que cero.

Construcciones no compatibles

Los formularios adaptables no admiten las siguientes construcciones de esquema JSON:
  • Tipo nulo
  • Tipos de Unión como cualquiera, y
  • OneOf, AnyOf, AllOf y NOT
  • Solo se admiten matrices homogéneas. Por lo tanto, la restricción items debe ser un objeto y no una matriz.

Frequently asked questions

¿Por qué no se pueden arrastrar elementos individuales de un subformulario (estructura generada a partir de cualquier tipo complejo) para subformularios repetibles (los valores minOccours o maxOccurs son mayores que 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 larga y compleja en Content Finder. ¿Cómo puedo encontrar un elemento específico?
Tiene dos opciones:
  • Desplácese por la estructura de árbol
  • Utilice el cuadro Buscar para encontrar 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.