Creazione di moduli adattivi tramite lo schema JSON

Prerequisiti

Per creare un modulo adattivo utilizzando uno schema JSON come modello di modulo, è necessario conoscere di base lo schema JSON. Prima di questo articolo, è consigliabile consultare il contenuto seguente.

• Creazione di un modulo adattivo
• Schema JSON

Utilizzo di uno schema JSON come modello di modulo

Adobe Experience Manager 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 principali dell’utilizzo di uno schema JSON sono le seguenti:

• La struttura del JSON viene visualizzata come una struttura nella scheda Content Finder nella modalità di creazione per un modulo adattivo. Puoi trascinare e aggiungere un elemento 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 in linea con lo schema associato.

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

Questa 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."
              }

Proprietà dello schema comuni

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

• La proprietà title funge da etichetta per i componenti dei moduli adattivi.
• La proprietà description viene impostata come descrizione lunga per un componente modulo adattivo.
• La proprietà default funge da valore iniziale di un campo modulo adattivo.
• La proprietà maxLength viene impostata come attributo maxlength del componente campo di testo.
• Le proprietà minimum, maximum, exclusiveMinimum e exclusiveMaximum vengono utilizzate per il componente Casella numerica.
• Per supportare l’intervallo per DatePicker component vengono fornite proprietà aggiuntive 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 readonly di un componente modulo adattivo.
• La proprietà required contrassegna il campo modulo adattivo come obbligatorio, mentre nel pannello (in cui il tipo è oggetto), i dati JSON inviati finali hanno campi con valore vuoto corrispondente a tale oggetto.
• La proprietà pattern viene impostata come pattern di convalida (espressione regolare) in forma adattiva.
• L’estensione del file di schema JSON deve essere mantenuta .schema.json. Ad esempio, <filename>.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 riutilizzabile 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 ha sia un indirizzo di spedizione che un indirizzo di fatturazione. La struttura di entrambi gli indirizzi è la stessa - gli indirizzi hanno un indirizzo di strada, una città e uno stato - quindi è una buona idea non duplicare gli indirizzi. Permette inoltre di aggiungere ed eliminare facilmente i campi per eventuali modifiche future.

Preconfigurazione dei campi nella definizione dello schema JSON

Puoi utilizzare la proprietà aem:afProperties per preconfigurare il campo Schema JSON per la mappatura su 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 modello di script per moduli adattivi. È possibile preconfigurare gli oggetti modulo in modo da valutare un'espressione su un evento modulo.

Utilizza la proprietà aem:afproperties per preconfigurare le espressioni o gli script di moduli adattivi per i componenti di moduli adattivi. Ad esempio, quando viene attivato 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\") "
    }
  }
}

È necessario essere membro del gruppo forms-power-user per configurare script o espressioni per l'oggetto modulo. 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 di eventi in un JSON nascondono un campo su un evento initialize e configurano il valore di un altro campo su un evento di commit dei valori. Per informazioni dettagliate sulla creazione di espressioni per gli eventi di script, vedere Espressioni modulo adattivo.

Di seguito è riportato il codice JSON di esempio per gli esempi menzionati in precedenza.

Nascondere un campo durante l’evento initialize

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

Configura il valore di un altro campo su un 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

Puoi aggiungere le seguenti restrizioni agli elementi dello schema JSON per limitare i valori accettabili per un componente modulo adattivo:

costrutti non supportati

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

• Tipo Null
• tipi dell'Unione, quali eventuali, e
• Uno, AnyOf, AllOf e NOT
• 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 maxOccours sono maggiori di 1)?

In un sottomodulo ripetibile, è necessario utilizzare il sottomodulo completo. Se desideri solo campi selettivi, utilizza l’intera struttura ed elimina quelli indesiderati.

Ho una lunga struttura complessa in Content Finder. Come posso trovare un elemento specifico?

Sono disponibili due opzioni:

• Scorrere la struttura ad albero
• Utilizza la casella 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, <filename>.schema.json.