Esempi di sviluppo e utilizzo di funzioni personalizzate
- Si applica a:
- Experience Manager as a Cloud Service
- Argomenti:
- Moduli adattivi
Creato per:
- Principiante
- Intermedio
- Utente
- Sviluppatore
L’articolo fornisce esempi dettagliati di funzioni personalizzate per un modulo adattivo basato su componenti core, fornendo informazioni utili sulla loro effettiva implementazione in vari scenari. Le funzioni personalizzate vengono utilizzate nell’editor di regole di un’AEM Forms, consentendo agli sviluppatori di definire e controllare la logica che regola il comportamento dei moduli.
Questo articolo esplora diverse implementazioni di funzioni personalizzate, mostrando come possono essere utilizzate per adattare i moduli in modo da soddisfare requisiti specifici e migliorare le funzionalità generali.
Popolare le opzioni dell’elenco a discesa utilizzando le funzioni personalizzate
L'editor di regole nei componenti core non supporta la proprietà Imposta opzioni per popolare dinamicamente le opzioni dell'elenco a discesa in fase di esecuzione. Tuttavia, puoi popolare le opzioni dell’elenco a discesa utilizzando funzioni personalizzate, che ti consentono di recuperare le opzioni in base a una logica specifica. Le funzioni personalizzate forniscono maggiore flessibilità e controllo su come e quando vengono compilate le opzioni a discesa, migliorando l’esperienza utente.
Per popolare le opzioni dell'elenco a discesa utilizzando una funzione personalizzata, aggiungere il codice seguente come descritto nella sezione create-custom-function:
/**
* @name setEnums
* @returns {string[]}
**/
function setEnums() {
return ["0","1","2","3","4","5","6"];
}
/**
* @name setEnumNames
* @returns {string[]}
**/
function setEnumNames() {
return ["Sunday","Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
}
Nel codice riportato sopra, setEnums viene utilizzato per impostare la proprietà enum e setEnumNames per impostare la proprietà enumNames dell'elenco a discesa.
Creiamo una regola per il pulsante Next, che imposta il valore dell'opzione dell'elenco a discesa quando l'utente fa clic sul pulsante Next:
Fai riferimento all’illustrazione seguente per dimostrare dove sono impostate le opzioni dell’elenco a discesa facendo clic sul pulsante Visualizza:
Mostra un pannello utilizzando la regola SetProperty
Scopri in che modo le funzioni personalizzate utilizzano gli oggetti campo e globali con l'aiuto di un modulo Contact Us.
Aggiungere il codice seguente nella funzione personalizzata come descritto nella sezione create-custom-function per impostare il campo modulo come Required.
/**
* enablePanel
* @name enablePanel
* @param {object} field1
* @param {object} field2
* @param {scope} globals
*/
function enablePanel(field1,field2, globals)
{
if(globals.functions.validate(field1).length === 0)
{
globals.functions.setProperty(field2, {visible: true});
}
}
NOTE- È possibile configurare le proprietà del campo utilizzando le proprietà disponibili in
[form-path]/jcr:content/guideContainer.model.json. - Le modifiche apportate al modulo utilizzando il metodo
setPropertydell'oggetto Globals sono di natura asincrona e non vengono applicate durante l'esecuzione della funzione personalizzata.
In questo esempio, la convalida del pannello personaldetails viene eseguita facendo clic sul pulsante. Se non vengono rilevati errori nel pannello, un altro pannello, il pannello feedback, diventa visibile al clic del pulsante.
Creiamo una regola per il pulsante Next, che convalida il pannello personaldetails e rende visibile il pannello feedback quando l'utente fa clic sul pulsante Next.
Fare riferimento all'illustrazione seguente per dimostrare dove viene convalidato il pannello personaldetails facendo clic sul pulsante Next. Se tutti i campi all'interno di personaldetails sono convalidati, il pannello feedback diventa visibile.
Se nei campi del pannello personaldetails sono presenti errori, questi vengono visualizzati a livello di campo facendo clic sul pulsante Next e il pannello feedback rimane invisibile.
Convalida il campo
Scopri in che modo le funzioni personalizzate utilizzano gli oggetti campo e globali per convalidare il campo con l'aiuto di un modulo Contact Us.
Aggiungi il seguente codice nella funzione personalizzata come descritto nella sezione create-custom-function per convalidare il campo.
/**
* validateField
* @name validateField
* @param {object} field
* @param {scope} globals
*/
function validateField(field,globals)
{
globals.functions.validate(field);
}
validate() non viene passato alcun argomento, il modulo viene convalidato.In questo esempio, al campo contact viene applicato un pattern di convalida personalizzato. Gli utenti devono immettere un numero di telefono che inizia con 10 seguito da 8 cifre. Se l'utente immette un numero di telefono che non inizia con 10 o che contiene più o meno di 8 cifre, viene visualizzato un messaggio di errore di convalida al clic del pulsante:
Il passaggio successivo consiste nel creare una regola per il pulsante Next che convalida il campo contact al clic del pulsante.
Fare riferimento all'illustrazione seguente per dimostrare che se l'utente immette un numero di telefono che non inizia con 10, viene visualizzato un messaggio di errore a livello di campo:
Se l'utente immette un numero di telefono valido e tutti i campi nel pannello personaldetails sono convalidati, il pannello feedback viene visualizzato sullo schermo:
Reimpostare un pannello
Scopri in che modo le funzioni personalizzate utilizzano gli oggetti campo e globali per reimpostare il campo con l'aiuto di un modulo Contact Us.
Aggiungi il seguente codice nella funzione personalizzata, come descritto nella sezione create-custom-function, per ripristinare il pannello.
/**
* resetField
* @name resetField
* @param {string} input1
* @param {object} field
* @param {scope} globals
*/
function resetField(field,globals)
{
globals.functions.reset(field);
}
reset() non viene passato alcun argomento, il modulo viene convalidato.In questo esempio, il pannello personaldetails viene ripristinato facendo clic sul pulsante Clear. Il passaggio successivo consiste nel creare una regola per il pulsante Clear che ripristini il pannello al clic del pulsante.
Vedere l'illustrazione seguente per mostrare che se l'utente fa clic sul pulsante clear, il pannello personaldetails viene ripristinato:
Per visualizzare un messaggio personalizzato a livello di campo e contrassegnare il campo come non valido
Scopri in che modo le funzioni personalizzate utilizzano gli oggetti campo e globali per visualizzare un messaggio personalizzato a livello di campo e contrassegnare il campo come non valido con l’aiuto di un modulo Contact Us.
È possibile utilizzare la funzione markFieldAsInvalid() per definire un campo come non valido e impostare un messaggio di errore personalizzato a livello di campo. Il valore fieldIdentifier può essere fieldId, field qualifiedName o field dataRef. Il valore dell'oggetto denominato option può essere {useId: true}, {useQualifiedName: true} o {useDataRef: true}.
Le sintassi utilizzate per contrassegnare un campo come non valido e impostare un messaggio personalizzato sono:
globals.functions.markFieldAsInvalid(field.$id,"[custom message]",{useId: true});globals.functions.markFieldAsInvalid(field.$qualifiedName, "[custom message]", {useQualifiedName: true});globals.functions.markFieldAsInvalid(field.$dataRef, "[custom message]", {useDataRef: true});
Aggiungi il seguente codice nella funzione personalizzata, come descritto nella sezione create-custom-function, per abilitare un messaggio personalizzato a livello di campo.
/**
* customMessage
* @name customMessage
* @param {object} field
* @param {scope} globals
*/
function customMessage(field, globals) {
const minLength = 15;
const comments = field.$value.trim();
if (comments.length < minLength) {
globals.functions.markFieldAsInvalid(field.$id, "Comments must be at least 15 characters long.", { useId: true });
}
}
In questo esempio, se l'utente immette meno di 15 caratteri nella casella di testo dei commenti, viene visualizzato un messaggio personalizzato a livello di campo.
Il passaggio successivo consiste nel creare una regola per il campo comments:
Vedere la dimostrazione seguente per visualizzare che l'immissione di un feedback negativo nel campo comments attiva la visualizzazione di un messaggio personalizzato a livello di campo:
Se l’utente immette più di 15 caratteri nella casella di testo dei commenti, il campo viene convalidato e il modulo viene inviato:
Invia dati modificati al server
Scopri in che modo le funzioni personalizzate utilizzano oggetti campo e globali per inviare dati manipolati sul server con l'aiuto di un modulo Contact Us.
La seguente riga di codice:globals.functions.submitForm(globals.functions.exportData(), false); viene utilizzato per inviare i dati del modulo dopo la manipolazione.
- Il primo argomento è costituito dai dati da inviare.
- Il secondo argomento indica se il modulo deve essere convalidato prima dell'invio. È
optionaled è impostato cometrueper impostazione predefinita. - Il terzo argomento è
contentTypedell'inoltro, che è anche facoltativo con il valore predefinitomultipart/form-data. Gli altri valori possono essereapplication/jsoneapplication/x-www-form-urlencoded.
Aggiungi il seguente codice nella funzione personalizzata, come descritto nella sezione create-custom-function, per inviare i dati manipolati sul server:
/**
* submitData
* @name submitData
* @param {object} field
* @param {scope} globals
*/
function submitData(globals)
{
var data = globals.functions.exportData();
if(!data.comments) {
data.comments = 'NA';
}
console.log('After update:{}',data);
globals.functions.submitForm(data, false);
}
In questo esempio, se l'utente lascia vuota la casella di testo comments, NA viene inviato al server al momento dell'invio del modulo.
Creare una regola per il pulsante Submit che invia i dati:
Fare riferimento all'illustrazione di console window seguente per dimostrare che se l'utente lascia vuota la casella di testo comments, il valore NA viene inviato nel server:
È inoltre possibile esaminare la finestra della console per visualizzare i dati inviati al server:
Ignora gestori di errori e operazioni riuscite per l’invio del modulo
Scopri in che modo le funzioni personalizzate utilizzano gli oggetti campo e globali per sostituire i gestori di invio con l'aiuto di un modulo Contact Us.
Aggiungi la seguente riga di codice come descritto nella sezione create-custom-functionas per personalizzare l'invio o il messaggio di errore per l'invio dei moduli e visualizzare i messaggi di invio dei moduli in una casella modale:
/**
* Handles the success response after a form submission.
*
* @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
* @returns {void}
*/
function customSubmitSuccessHandler(globals) {
var event = globals.event;
var submitSuccessResponse = event.payload.body;
var form = globals.form;
if (submitSuccessResponse) {
if (submitSuccessResponse.redirectUrl) {
window.location.href = encodeURI(submitSuccessResponse.redirectUrl);
} else if (submitSuccessResponse.thankYouMessage) {
showModal("success", submitSuccessResponse.thankYouMessage);
}
}
}
/**
* Handles the error response after a form submission.
*
* @param {string} customSubmitErrorMessage - The custom error message.
* @param {scope} globals - This object contains a read-only form instance, target field instance, triggered event, and methods for performing form modifications within custom functions.
* @returns {void}
*/
function customSubmitErrorHandler(customSubmitErrorMessage, globals) {
showModal("error", customSubmitErrorMessage);
}
function showModal(type, message) {
// Remove any existing modals
var existingModal = document.getElementById("modal");
if (existingModal) {
existingModal.remove();
}
// Create the modal dialog
var modal = document.createElement("div");
modal.setAttribute("id", "modal");
modal.setAttribute("class", "modal");
// Create the modal content
var modalContent = document.createElement("div");
modalContent.setAttribute("class", "modal-content");
// Create the modal header
var modalHeader = document.createElement("div");
modalHeader.setAttribute("class", "modal-header");
modalHeader.innerHTML = "<h2>" + (type === "success" ? "Thank You" : "Error") + "</h2>";
// Create the modal body
var modalBody = document.createElement("div");
modalBody.setAttribute("class", "modal-body");
modalBody.innerHTML = "<p class='" + type + "-message'>" + message + "</p>";
// Create the modal footer
var modalFooter = document.createElement("div");
modalFooter.setAttribute("class", "modal-footer");
// Create the close button
var closeButton = document.createElement("button");
closeButton.setAttribute("class", "close-button");
closeButton.innerHTML = "Close";
closeButton.onclick = function() {
modal.remove();
};
// Append the elements to the modal content
modalFooter.appendChild(closeButton);
modalContent.appendChild(modalHeader);
modalContent.appendChild(modalBody);
modalContent.appendChild(modalFooter);
// Append the modal content to the modal
modal.appendChild(modalContent);
// Append the modal to the document body
document.body.appendChild(modal);
}
In questo esempio, quando l'utente utilizza le funzioni personalizzate customSubmitSuccessHandler e customSubmitErrorHandler, i messaggi di esito positivo e negativo vengono visualizzati in un modale. La funzione JavaScript showModal(type, message) viene utilizzata per creare e visualizzare in modo dinamico una finestra di dialogo modale su uno schermo.
Ora, crea una regola per l’invio corretto del modulo:
Fai riferimento all’illustrazione seguente per dimostrare che, quando il modulo viene inviato correttamente, il messaggio di successo viene visualizzato in una finestra modale:
Allo stesso modo, creiamo una regola per gli invii di moduli non riusciti:
Fai riferimento all’illustrazione seguente per dimostrare che quando l’invio del modulo non riesce, il messaggio di errore viene visualizzato in un modale:
Per visualizzare l'invio dei moduli completato e non riuscito in modo predefinito, sono disponibili le funzioni Default submit Form Success Handler e Default submit Form Error Handler pronte all'uso.
Nel caso in cui il gestore di invio personalizzato non riesca a eseguire le operazioni previste nei progetti o moduli AEM esistenti, consulta la sezione risoluzione dei problemi.
Eseguire azioni in un'istanza specifica del pannello ripetibile
Le regole create utilizzando l’editor di regole visive in un pannello ripetibile si applicano all’ultima istanza del pannello ripetibile. Per scrivere una regola per una specifica istanza del pannello ripetibile, possiamo utilizzare una funzione personalizzata.
Creiamo un altro modulo come Booking Form per raccogliere informazioni sui viaggiatori che si dirigono verso una destinazione. Un pannello viaggiatore viene aggiunto come pannello ripetibile, in cui l'utente può aggiungere dettagli per 5 viaggiatori utilizzando il pulsante Add Traveler.
Aggiungi la seguente riga di codice come descritto nella sezione create-custom-function per eseguire azioni in un'istanza specifica del pannello ripetibile, diversa dall'ultima:
/**
* @name hidePanelInRepeatablePanel
* @param {scope} globals
*/
function hidePanelInRepeatablePanel(globals)
{
var repeatablePanel = globals.form.travelerinfo;
// hides a panel inside second instance of repeatable panel
globals.functions.setProperty(repeatablePanel[1].traveler, {visible : false});
}
In questo esempio, la funzione personalizzata hidePanelInRepeatablePanel esegue un'azione in un'istanza specifica del pannello ripetibile. Nel codice precedente, travelerinfo rappresenta il pannello ripetibile. Il codice repeatablePanel[1].traveler, {visible: false} nasconde il pannello nella seconda istanza del pannello ripetibile.
Aggiungiamo un pulsante con etichetta Hide e una regola per nascondere la seconda istanza di un pannello ripetibile.
Fare riferimento al video seguente per dimostrare che quando si fa clic su Hide, il pannello nella seconda istanza ripetibile si nasconde:
Precompila il campo con un valore al caricamento del modulo
Scopri in che modo le funzioni personalizzate utilizzano gli oggetti campo e globali per precompilare il campo con l'aiuto di Booking Form.
Aggiungi la seguente riga di codice, come spiegato nella sezione create-custom-function, per caricare il valore precompilato in un campo quando il modulo viene inizializzato:
/**
* Tests import data
* @name testImportData
* @param {scope} globals
*/
function testImportData(globals)
{
globals.functions.importData(Object.fromEntries([['amount','10000']]));
}
Nel codice sopra indicato, la funzione testImportData compila il campo della casella di testo Booking Amount al caricamento del modulo. Supponiamo che il modulo di prenotazione richieda un importo minimo di prenotazione pari a 10,000.
Creiamo una regola al momento dell'inizializzazione del modulo, in cui il valore nel campo della casella di testo Booking Amount viene precompilato con un valore specificato al caricamento del modulo:
Fai riferimento alla schermata seguente, che dimostra che quando il modulo viene caricato, il valore nella casella di testo Booking Amount è precompilato con un valore specificato:
Imposta lo stato attivo sul campo specifico
Scopri in che modo le funzioni personalizzate utilizzano gli oggetti campo e globali per impostare lo stato attivo su un campo specifico con l'aiuto di Booking Form.
Aggiungere la seguente riga di codice, come spiegato nella sezione create-custom-function, per attivare il campo specificato quando si fa clic sul pulsante Submit.:
/**
* @name testSetFocus
* @param {object} emailField
* @param {scope} globals
*/
function testSetFocus(field, globals)
{
globals.functions.setFocus(field);
}
Aggiungiamo una regola al pulsante Submit per impostare lo stato attivo sul campo della casella di testo Email ID quando si fa clic su di esso:
Fare riferimento alla schermata seguente, che dimostra che quando si fa clic sul pulsante Submit, lo stato attivo è impostato sul campo Email ID:
NOTE$focusOption se si desidera concentrarsi sul campo successivo o precedente relativo al campo email.Aggiungere o eliminare un pannello ripetibile utilizzando la proprietà dispatchEvent
Scopri in che modo le funzioni personalizzate utilizzano gli oggetti field e global per aggiungere o eliminare un pannello ripetibile utilizzando la proprietà dispatchEvent con l'aiuto di un Booking Form.
Aggiungi la seguente riga di codice, come spiegato nella sezione create-custom-function, per aggiungere un pannello quando fai clic sul pulsante Add Traveler utilizzando la proprietà dispatchEvent:
/**
* Tests add instance with dispatchEvent
* @name testAddInstance
* @param {scope} globals
*/
function testAddInstance(globals)
{
var repeatablePanel = globals.form.traveler;
globals.functions.dispatchEvent(repeatablePanel,'addInstance');
}
Aggiungiamo una regola al pulsante Add Traveler per aggiungere il pannello ripetibile quando viene fatto clic:
Fare riferimento al file GIF riportato di seguito, a dimostrazione che quando si fa clic sul pulsante Add Traveler, il pannello viene aggiunto utilizzando la proprietà dispatchEvent:
Analogamente, aggiungere la seguente riga di codice, come spiegato nella sezione create-custom-function, per eliminare un pannello quando si fa clic sul pulsante Delete Traveler utilizzando la proprietà dispatchEvent:
/**
* @name testRemoveInstance
* @param {scope} globals
*/
function testRemoveInstance(globals)
{
var repeatablePanel = globals.form.traveler;
globals.functions.dispatchEvent(repeatablePanel, 'removeInstance');
}
Aggiungiamo una regola al pulsante Delete Traveler per eliminare il pannello ripetibile quando viene selezionato:
Fare riferimento al file GIF riportato di seguito, a dimostrazione che quando si fa clic sul pulsante Delete Traveler, il pannello del viaggiatore viene eliminato utilizzando la proprietà dispatchEvent:
Risoluzione dei problemi
-
Se il gestore di invio personalizzato non funziona come previsto nei progetti o moduli AEM esistenti, effettua le seguenti operazioni:
-
Verificare che la versione dei componenti core sia aggiornata a 3.0.18 e versioni successive. Tuttavia, per i progetti e i moduli AEM esistenti, vi sono ulteriori passi da seguire:
-
Per il progetto AEM, l'utente deve sostituire tutte le istanze di
submitForm('custom:submitSuccess', 'custom:submitError')consubmitForm()e distribuire il progetto tramite la pipeline Cloud Manager. -
Per i moduli esistenti, se i gestori di invio personalizzati non funzionano correttamente, l'utente deve aprire e salvare la regola
submitFormsul pulsante Invia utilizzando l'editor di regole. Questa azione sostituisce la regola esistente disubmitForm('custom:submitSuccess', 'custom:submitError')consubmitForm()nel modulo.
-
Consulta anche
- Introduzione all’editor di regole per moduli adattivi basati su componenti core
- Tipi di operatori ed eventi nell’editor di regole di un modulo adattivo basato su componenti core
- Interfaccia utente dell’editor di regole per moduli adattivi basati su componenti core
- Diversi casi d’uso dell’editor di regole per un modulo adattivo basato su componenti core
- Differenza nelle varie edizioni dell’editor di regole
- Utilizzo di funzioni asincrone in un modulo adattivo
- Miglioramenti a Avvia servizio nell’editor di regole visive per i moduli basati su componenti core
- Introduzione alle funzioni personalizzate per moduli adattivi basati su componenti core
- Creare una funzione personalizzata per un modulo adattivo basato su componenti core
- Oggetto ambito nelle funzioni personalizzate
- Esempi di sviluppo e utilizzo di una funzione personalizzata