Creazione di moduli adattivi con lo schema JSON

Prerequisiti

Per creare un modulo adattivo utilizzando uno schema JSON come modello di modulo, è necessario conoscere a fondo lo schema JSON. Si consiglia di leggere il contenuto seguente prima di questo articolo.

Utilizzo di uno schema JSON come modello di modulo

AEM Forms supporta la creazione di un modulo adattivo utilizzando uno schema JSON esistente come modello di modulo. Questo schema JSON rappresenta la struttura in cui i dati vengono prodotti o utilizzati dal sistema back-end della tua organizzazione. Lo schema JSON utilizzato deve essere conforme alle specifiche v4.

Le caratteristiche chiave dell'utilizzo di uno schema JSON sono:

  • La struttura del JSON viene visualizzata come struttura ad albero nella scheda Content Finder nella modalità di creazione per un modulo adattivo. Puoi trascinare e aggiungere elementi dalla gerarchia JSON al modulo adattivo.
  • È possibile precompilare il modulo utilizzando JSON conforme allo schema associato.
  • Al momento dell'invio, i dati immessi dall'utente vengono inviati come JSON che si allinea allo schema associato.

Uno schema JSON è costituito da tipi di elementi semplici e complessi. Gli elementi hanno attributi che aggiungono regole all'elemento. Quando questi elementi e attributi vengono trascinati su un modulo adattivo, vengono mappati automaticamente sul componente modulo adattivo corrispondente.

La mappatura degli elementi JSON con componenti per moduli adattivi è la seguente:

"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, proprietà o attributi JSON Componente modulo adattivo

Proprietà delle stringhe con vincolo enum e enumNames.

Sintassi,

{

"type" : "string",

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

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

}

Componente a discesa:

  • I valori elencati in enumNames vengono visualizzati nella casella di rilascio.
  • I valori elencati nell'enum sono utilizzati per il calcolo.

Proprietà stringa con vincolo di formato. Ad esempio, e-mail e data.

Sintassi,

{

"type" : "string",

"format" : "email"

}
  • Il componente e-mail viene mappato quando il tipo è stringa e il formato è e-mail.
  • Il componente Textbox con convalida viene mappato quando il tipo è stringa e il formato è nomehost.

{

"type" : "string",

}

Campo di testo
number property
 Campo numerico con sottotipo impostato su Mobile
proprietà integer
 Campo numerico con sottotipo impostato su integer
proprietà booleana
 Scambia
proprietà object
 Pannello
array, proprietà Pannello ripetibile con min e max uguali rispettivamente a minItems e maxItems. Sono supportati solo gli array omogenei. Pertanto, il vincolo degli elementi deve essere un oggetto e non un array.

Proprietà comuni dello schema

Il modulo adattivo utilizza le informazioni disponibili nello schema JSON per mappare ciascun campo generato. In particolare:

  • La proprietà title funge da etichetta per i componenti per modulo adattivo.
  • La proprietà description è impostata come descrizione lunga per un componente modulo adattivo.
  • La proprietà predefinita funge da valore iniziale di un campo modulo adattivo.
  • La proprietà maxLength è impostata come attributo maxlength del componente Campo di testo.
  • Per il componente Casella numerica vengono utilizzate le proprietà minima, massima, esclusivaMinimum ed esclusivaMaximum.
  • Per supportare l'intervallo per il componente DatePicker, vengono fornite ulteriori proprietà dello schema JSON: minDate e maxDate.
  • Le proprietà minItems e maxItems vengono utilizzate per limitare il numero di elementi/campi che possono essere aggiunti o rimossi da un componente del pannello.
  • La proprietà readOnly imposta l’attributo di sola lettura di un componente modulo adattivo.
  • La proprietà richiesta contrassegna il campo modulo adattivo come obbligatorio, mentre nel caso del pannello (dove type è object), i dati JSON inviati finali hanno campi con un valore vuoto corrispondente a tale oggetto.
  • La proprietà pattern è impostata come pattern di convalida (espressione regolare) in forma adattiva.
  • L'estensione del file di schema JSON deve essere mantenuta .schema.json. Ad esempio, <nomefile>.schema.json.

Schema JSON di esempio

Ecco un esempio di uno schema 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"
  }
 }
}

Definizioni dello schema riutilizzabili

Le chiavi di definizione vengono utilizzate per identificare gli schemi riutilizzabili. Le definizioni dello schema riutilizzabili vengono utilizzate per creare i frammenti. È simile all'identificazione di tipi complessi in XSD. Di seguito è riportato un esempio di schema JSON con definizioni:

{
  "$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" }
  }
}

L'esempio precedente definisce un record cliente, in cui ogni cliente dispone sia di un indirizzo di spedizione che di un indirizzo di fatturazione. La struttura di entrambi gli indirizzi è la stessa (gli indirizzi hanno un indirizzo, una città e uno stato) quindi è una buona idea non duplicare gli indirizzi. Consente inoltre di aggiungere ed eliminare campi con facilità per qualsiasi modifica futura.

Pre-configurazione dei campi nella definizione dello schema JSON

È possibile utilizzare la proprietà aem:afProperties per preconfigurare il campo Schema JSON in modo che venga associato a un componente modulo adattivo personalizzato. Di seguito è riportato un esempio:

{
    "properties": {
        "sizeInMB": {
            "type": "integer",
            "minimum": 16,
            "maximum": 512,
            "aem:afProperties" : {
                 "sling:resourceType" : "/apps/fd/af/components/guideTextBox",
                 "guideNodeClass" : "guideTextBox"
             }
        }
    },
    "required": [ "sizeInMB" ],
    "additionalProperties": false
}

Configurare script o espressioni per gli oggetti modulo

JavaScript è il linguaggio di espressione dei moduli adattivi. Tutte le espressioni sono espressioni JavaScript valide e utilizzano API per modelli di script di moduli adattivi. È possibile pre-configurare gli oggetti modulo in modo che valuti un'espressione in un evento del modulo.

Utilizzare la proprietà aem:afproperties per preconfigurare le espressioni di modulo adattivo o gli script per i componenti modulo adattivi. Ad esempio, quando si attiva l'evento initialize, il codice seguente imposta il valore del campo telefonico e stampa un valore nel 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\") "
    }
  }
}

Per configurare script o espressioni per l'oggetto modulo, è necessario essere membri del gruppo forms-power-user. Nella tabella seguente sono elencati tutti gli eventi di script supportati per un componente modulo adattivo.

Componente \ Evento initialize
Calcola Visibilità Convalida Abilitato Conferma valore Clic Opzioni
Campo testo
Campo numerico
Stepper numerico
Pulsante di scelta
Telefono
Scambia
Pulsante
Casella di controllo
A Discesa
Scelta immagine
Campo immissione data
Selettore data
E-mail
Allegato file
Immagine
Draw
Pannello

Alcuni esempi dell'utilizzo degli eventi in un JSON nascondono un campo in corrispondenza dell'evento initialize e configurano il valore di un altro campo in corrispondenza dell'evento value commit. Per informazioni dettagliate sulla creazione di espressioni per gli eventi di script, vedere Espressioni modulo adattive.

Di seguito è riportato il codice JSON di esempio per i suddetti esempi.

Nascondere un campo all'evento di inizializzazione

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

Configurare il valore di un altro campo sull'evento di commit del valore

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

Limitare i valori accettabili per un componente modulo adattivo

È possibile aggiungere le seguenti limitazioni agli elementi dello schema JSON per limitare i valori accettabili per un componente modulo adattivo:

Proprietà Schema

Tipo di dati

Descrizione

Componente

maximum

Stringa

Specifica il limite superiore per i valori numerici e le date. Per impostazione predefinita, è incluso il valore massimo.
  • Casella numerica
  • Stepper numerico
  • Selettore data

minimum

Stringa

Specifica il limite inferiore per i valori numerici e le date. Per impostazione predefinita, è incluso il valore minimo.
  • Casella numerica
  • Stepper numerico
  • Selettore data

exclusiveMaximum

Booleano

Se true, il valore numerico o la data specificati nel componente del modulo devono essere inferiori al valore numerico o alla data specificati per la proprietà massima.

Se è false, il valore numerico o la data specificati nel componente del modulo deve essere minore o uguale al valore numerico o alla data specificati per la proprietà massima.
  • Casella numerica
  • Stepper numerico
  • Selettore data

exclusiveMinimum

Booleano

Se true, il valore numerico o la data specificati nel componente del modulo devono essere maggiori del valore numerico o della data specificati per la proprietà minima.

Se è false, il valore numerico o la data specificati nel componente del modulo deve essere maggiore o uguale al valore numerico o alla data specificati per la proprietà minima.
  • Casella numerica
  • Stepper numerico
  • Selettore data

minLength

Stringa

Specifica il numero minimo di caratteri consentiti in un componente. La lunghezza minima deve essere uguale o maggiore di zero.
  • Casella di testo
maxLength Stringa Specifica il numero massimo di caratteri consentiti in un componente. La lunghezza massima deve essere uguale o maggiore di zero.
  • Casella di testo

pattern

Stringa

Specifica la sequenza dei caratteri. Un componente accetta i caratteri se questi sono conformi al pattern specificato.

La proprietà pattern viene mappata sul pattern di convalida del componente modulo adattivo corrispondente.
  • Tutti i componenti di moduli adattivi mappati a uno schema XSD
maxItems Stringa Specifica il numero massimo di elementi in un array. Gli elementi massimi devono essere uguali o maggiori di zero.
minItems Stringa Specifica il numero minimo di elementi in un array. Gli elementi minimi devono essere uguali o maggiori di zero.

costrutti non supportati

I moduli adattivi non supportano i seguenti costrutti dello schema JSON:

  • Tipo Null
  • tipi di Unione, quali eventuali, e
  • Uno, AnyOf, AllOf e NO
  • Sono supportati solo gli array omogenei. Pertanto, il vincolo elementi deve essere un oggetto e non un array.

Domande frequenti

Perché non è possibile trascinare singoli elementi di un sottomodulo (struttura generata da qualsiasi tipo complesso) per sottomoduli ripetibili (i valori minOccours o maxOccurs sono maggiori di 1)?

In un sottomodulo ripetibile, è necessario utilizzare il sottomodulo completo. Se desiderate solo campi selettivi, utilizzate l'intera struttura ed eliminate quelli indesiderati.

In Content Finder ho una struttura complessa molto lunga. Come posso trovare un elemento specifico?

Sono disponibili due opzioni:

  • Scorrere la struttura ad albero
  • Utilizzare la casella di ricerca per trovare un elemento

Quale dovrebbe essere l'estensione del file di schema JSON?

L'estensione del file di schema JSON deve essere .schema.json. Ad esempio, <nomefile>.schema.json.

In questa pagina