Funzioni personalizzate nei componenti core di Forms adattivi

Ultimo aggiornamento: 14 luglio 2024

Argomenti:
Moduli adattivi

Creato per:

Amministratore
Utente
Sviluppatore

Questo articolo descrive la creazione di funzioni personalizzate con il componente core Modulo adattivo più recente dotato delle funzioni più recenti, ad esempio:

Funzione di memorizzazione in cache per funzioni personalizzate
Supporto globale di oggetti di ambito e oggetti di campo per le funzioni personalizzate
Supporto per le funzioni JavaScript moderne come le funzioni let e arrow (supporto ES10)

Assicurati di impostare la versione più recente del modulo nell'ambiente dei Componenti core AEM Forms per utilizzare le funzioni più recenti in Funzioni personalizzate.

Versione

Collegamento articolo

AEM 6.5

Questo articolo

AEM as a Cloud Service

Fai clic qui

Introduzione

AEM Forms 6.5 include funzioni JavaScript che ti consentono di definire regole di business complesse utilizzando l’editor di regole. AEM Forms offre diverse funzioni personalizzate predefinite; tuttavia, in molti casi è necessario definire funzioni personalizzate da utilizzare in più moduli. Queste funzioni personalizzate migliorano le funzionalità dei moduli consentendo la manipolazione e l'elaborazione dei dati immessi per soddisfare requisiti specifici. Consentono inoltre di modificare dinamicamente il comportamento della forma in base ai criteri predefiniti.

Utilizzo di funzioni personalizzate

I vantaggi dell’utilizzo di funzioni personalizzate nei componenti core di Forms adattivi sono:

Gestione dei dati: le funzioni personalizzate gestiscono ed elaborano i dati immessi nei campi dei moduli.
Elaborazione dei dati: le funzioni personalizzate consentono di elaborare i dati immessi nei campi dei moduli.
Convalida dei dati: le funzioni personalizzate consentono di eseguire controlli personalizzati sugli input dei moduli e di fornire messaggi di errore specifici.
Comportamento dinamico: le funzioni personalizzate consentono di controllare il comportamento dinamico dei moduli in base a condizioni specifiche. Ad esempio, è possibile visualizzare/nascondere campi, modificare i valori dei campi o modificare dinamicamente la logica del modulo.
Integrazione: è possibile utilizzare funzioni personalizzate da integrare con API o servizi esterni. Consente di recuperare dati da origini esterne, inviare dati agli endpoint Rest esterni o eseguire azioni personalizzate basate su eventi esterni.

Le funzioni personalizzate sono essenzialmente librerie client aggiunte al file JavaScript. Una volta creata, la funzione personalizzata diventa disponibile nell’editor di regole per la selezione da parte dell’utente in un modulo adattivo. Le funzioni personalizzate sono identificate dalle annotazioni di JavaScript nell’editor di regole.

Annotazioni di JavaScript supportate per la funzione personalizzata

Le annotazioni di JavaScript forniscono metadati per il codice JavaScript. Include commenti che iniziano con simboli specifici, ad esempio /** e @. Le annotazioni forniscono informazioni importanti su funzioni, variabili e altri elementi nel codice. Il modulo adattivo supporta le seguenti annotazioni di JavaScript per le funzioni personalizzate:

Nome

Name viene utilizzato per identificare la funzione personalizzata nell'editor di regole di un modulo adattivo. Per denominare una funzione personalizzata vengono utilizzate le sintassi seguenti:

@name [functionName] <Function Name>
@function [functionName] <Function Name>
@func [functionName] <Function Name>

NOTE

[functionName] è il nome della funzione. Gli spazi non sono consentiti.
<Function Name> è il nome visualizzato della funzione nell’editor di regole di Adaptive Forms.
Se il nome della funzione è identico al nome della funzione stessa, è possibile omettere [functionName] dalla sintassi.

Parametro

Il parametro è un elenco di argomenti utilizzati dalle funzioni personalizzate. Una funzione può supportare più parametri. Le seguenti sintassi vengono utilizzate per definire un parametro in una funzione personalizzata:

@param {type} name <Parameter Description>
@argument {type} name <Parameter Description>
@arg {type} name <Parameter Description>

{type} rappresenta il tipo di parametro. I tipi di parametri consentiti sono:
- string (stringa): rappresenta un singolo valore di stringa.
- number: rappresenta un singolo valore numerico.
- booleano: rappresenta un singolo valore booleano (true o false).
- stringa[]: rappresenta una matrice di valori stringa.
- number[]: rappresenta una matrice di valori numerici.
- booleano[]: rappresenta una matrice di valori booleani.
- data: rappresenta un singolo valore di data.
- data[]: rappresenta una matrice di valori di data.
- array: rappresenta una matrice generica contenente valori di vari tipi.
- object: rappresenta un oggetto modulo passato a una funzione personalizzata anziché passare direttamente il relativo valore.
- ambito: rappresenta l'oggetto globals, che contiene variabili di sola lettura quali istanze di moduli, istanze di campi di destinazione e metodi per l'esecuzione di modifiche di moduli nelle funzioni personalizzate. Viene dichiarato come ultimo parametro nelle annotazioni di JavaScript e non è visibile all’editor di regole di un modulo adattivo. Il parametro scope accede all'oggetto del modulo o del componente per attivare la regola o l'evento necessario per l'elaborazione del modulo. Per ulteriori informazioni sull'oggetto Globals e su come utilizzarlo, fare clic qui

Il tipo di parametro è senza distinzione tra maiuscole e minuscole e non sono consentiti spazi nel nome del parametro.

<Parameter Description> contiene dettagli sullo scopo del parametro. Può avere più parole.

Tipo restituito

Il tipo restituito specifica il tipo di valore restituito dalla funzione personalizzata dopo l'esecuzione. Le seguenti sintassi vengono utilizzate per definire un tipo restituito in una funzione personalizzata:

@return {type}
@returns {type}
{type} rappresenta il tipo restituito della funzione. I tipi restituiti consentiti sono:
string (stringa): rappresenta un singolo valore di stringa.
number: rappresenta un singolo valore numerico.
booleano: rappresenta un singolo valore booleano (true o false).
stringa[]: rappresenta una matrice di valori stringa.
number[]: rappresenta una matrice di valori numerici.
booleano[]: rappresenta una matrice di valori booleani.
data: rappresenta un singolo valore di data.
data[]: rappresenta una matrice di valori di data.
array: rappresenta una matrice generica contenente valori di vari tipi.
object: rappresenta direttamente l'oggetto modulo anziché il relativo valore.

Il tipo restituito non fa distinzione tra maiuscole e minuscole.

Privata

La funzione personalizzata, dichiarata come privata, non viene visualizzata nell’elenco delle funzioni personalizzate nell’editor delle regole di un modulo adattivo. Per impostazione predefinita, le funzioni personalizzate sono pubbliche. La sintassi per dichiarare la funzione personalizzata come privata è @private.

Linee guida per la creazione di funzioni personalizzate

Per elencare le funzioni personalizzate nell’editor di regole, puoi utilizzare uno dei seguenti formati:

Istruzione function con o senza commenti jsdoc

Puoi creare una funzione personalizzata con o senza commenti jsdoc.

    function functionName(parameters)
        {
            // code to be executed
        }

Se l’utente non aggiunge annotazioni JavaScript alla funzione personalizzata, questa viene elencata nell’editor di regole in base al nome della funzione. Tuttavia, si consiglia di includere annotazioni JavaScript per migliorare la leggibilità delle funzioni personalizzate.

Funzione freccia con annotazioni o commenti JavaScript obbligatori

È possibile creare una funzione personalizzata con una sintassi della funzione freccia:

    /**
    * test function
    * @name testFunction
    * @param {string} a parameter description
    * @param {string=} b parameter description
    * @return {string}
    */
    testFunction = (a, b) => {
    return a + b;
    };
    /** */
    testFunction1=(a) => (return a)
    /** */
    testFunction2 = a => a + 100;

Se l’utente non aggiunge annotazioni JavaScript alla funzione personalizzata, la funzione personalizzata non viene elencata nell’editor di regole di un modulo adattivo.

Espressione di funzione con annotazioni o commenti JavaScript obbligatori

Per elencare le funzioni personalizzate nell’editor di regole di un modulo adattivo, crea funzioni personalizzate nel formato seguente:

    /**
    * test function
    * @name testFunction
    * @param {string} input1 parameter description
    * @param {string=} input2 parameter description
    * @return {string}
    */
    testFunction = function(input1,input2)
        {
            // code to be executed
        }

Se l’utente non aggiunge annotazioni JavaScript alla funzione personalizzata, la funzione personalizzata non viene elencata nell’editor di regole di un modulo adattivo.

Prerequisiti per creare una funzione personalizzata

Prima di iniziare ad aggiungere una funzione personalizzata al Forms adattivo, accertati di aver installato sul computer il seguente software:

Editor di testo normale (IDE): mentre qualsiasi editor di testo normale può funzionare, un ambiente di sviluppo integrato (IDE) come Microsoft Visual Studio Code offre funzionalità avanzate per semplificare la modifica.
Git: Questo sistema di controllo della versione è necessario per la gestione delle modifiche al codice. Se non lo hai installato, scaricalo da https://git-scm.com.

Creare una funzione personalizzata

I passaggi per creare funzioni personalizzate sono i seguenti:

Crea una libreria lato client utilizzando l'archetipo di progetto AEM e aggiungi una funzione personalizzata
OPPURE
Creare funzioni personalizzate tramite CRXDE
Aggiungere una libreria client a un modulo adattivo
Utilizzare una funzione personalizzata in un modulo adattivo

Creare una libreria client utilizzando l’archetipo di progetto AEM

È possibile aggiungere funzioni personalizzate aggiungendo una libreria client al progetto creato utilizzando l'archetipo di progetto AEM.
Se hai un progetto esistente puoi aggiungere direttamente funzioni personalizzate al progetto locale.

Dopo aver creato un progetto di Archetipo o aver utilizzato un progetto esistente, crea una libreria client. Per creare una libreria client, effettua le seguenti operazioni:

Aggiungi una cartella della libreria client

Per aggiungere una nuova cartella della libreria client alla [directory del progetto AEM], eseguire la procedura seguente:

Apri la [directory del progetto AEM] in un editor.
Individuare ui.apps.
Aggiungi nuova cartella. Aggiungere ad esempio una cartella denominata experience-league.
Passare alla cartella /experience-league/ e aggiungere ClientLibraryFolder. Creare ad esempio una cartella della libreria client denominata customclientlibs.

Posizione: [AEM project directory]/ui.apps/src/main/content/jcr_root/apps/

Aggiungi file e cartelle alla cartella Libreria client

Aggiungi quanto segue alla cartella della libreria client aggiunta:

.content.xml file
js.txt file
Cartella js

Location is: [AEMaaCS project directory]/ui.apps/src/main/content/jcr_root/apps/experience-league/customclientlibs/

In .content.xml aggiungi le seguenti righe di codice:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
jcr:primaryType="cq:ClientLibraryFolder"
categories="[customfunctionscategory]"/>

NOTE

È possibile scegliere qualsiasi nome per la proprietà client library folder e categories.

In js.txt aggiungi le seguenti righe di codice:
#base=js function.js

Nella cartella js, aggiungi il file javascript come function.js che include le funzioni personalizzate:

/**
    * Calculates Age
    * @name calculateAge
    * @param {object} field
    * @return {string}
*/

function calculateAge(field) {
var dob = new Date(field);
var now = new Date();

var age = now.getFullYear() - dob.getFullYear();
var monthDiff = now.getMonth() - dob.getMonth();

if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
age--;
}

return age;
}

Salva i file.

struttura cartella funzioni personalizzata

Includi la nuova cartella nel file filter.xml:

Passa al file /ui.apps/src/main/content/META-INF/vault/filter.xml nella directory del progetto [AEMaaCS].
Apri il file e aggiungi la seguente riga alla fine:

<filter root="/apps/experience-league" />
Salva il file.
Crea la cartella della libreria client appena creata nell'ambiente AEM seguendo i passaggi indicati nella sezione Come generare.

Creare e distribuire funzioni personalizzate tramite CRXDE

Se utilizzi il componente aggiuntivo AEM Forms e Forms più recente, puoi creare una funzione personalizzata tramite CRXDE per utilizzare gli ultimi aggiornamenti delle funzioni personalizzate. A tale scopo, effettuare le seguenti operazioni:

Accedi a http://server:port/crx/de/index.jsp#.
Creare una cartella nella cartella /apps. Creare ad esempio una cartella denominata experience-league.
Salva le modifiche.
Passare alla cartella creata e creare un nodo di tipo cq:ClientLibraryFolder come clientlibs.
Passare alla cartella clientlibs appena creata e aggiungere le proprietà allowProxy e categories:

NOTE
È possibile specificare qualsiasi nome al posto di customfunctionsdemo.
Salva le modifiche.
Creare una cartella denominata js nella cartella clientlibs.
Creare un file JavaScript denominato functions.js nella cartella js.
Creare un file denominato js.txt nella cartella clientlibs.
Salva le modifiche.
La struttura di cartelle creata è simile alla seguente:

Fare doppio clic sul file functions.js per aprire l'editor. Il file contiene il codice per la funzione personalizzata.
Aggiungiamo il seguente codice al file JavaScript per calcolare l’età in base alla data di nascita (AAAA-MM-GG).

    /**
         * Calculates Age
         * @name calculateAge
         * @return {string}
    */

    function calculateAge(dateOfBirthString) {
    var dob = new Date(dateOfBirthString);
    var now = new Date();

    var age = now.getFullYear() - dob.getFullYear();
    var monthDiff = now.getMonth() - dob.getMonth();

    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
    age--;
    }

    return age;
    }

Salva function.js.
Passare a js.txt e aggiungere il codice seguente:
#base=js functions.js
Salva il file js.txt.

È possibile fare riferimento alla seguente cartella funzione personalizzata. Scarica e installa questa cartella nella tua istanza AEM.

Ora è possibile utilizzare la funzione personalizzata nel modulo adattivo aggiungendo la libreria client.

Aggiungere una libreria client in un modulo adattivo

Dopo aver implementato la libreria client nell’ambiente AEM Forms, utilizzane le funzionalità nel modulo adattivo. Per aggiungere la libreria client al modulo adattivo

Apri il modulo in modalità di modifica. Per aprire un modulo in modalità di modifica, selezionare un modulo e selezionare Modifica.
Apri il browser Contenuto e seleziona il componente Contenitore guida del modulo adattivo.
Fai clic sull’icona delle proprietà del Contenitore guida. Viene visualizzata la finestra di dialogo Contenitore modulo adattivo (Adaptive Form Container).
Apri la scheda Base e seleziona il nome della categoria di librerie client dall'elenco a discesa (in questo caso, seleziona customfunctionscategory).
Fai clic su Fine.

Ora puoi creare una regola per utilizzare funzioni personalizzate nell’editor di regole:

Aggiunta della libreria client della funzione personalizzata

Ora vediamo come configurare e utilizzare una funzione personalizzata utilizzando il servizio Invoke dell'editor di regole in AEM Forms 6.5

Utilizzo di una funzione personalizzata in un modulo adattivo

In un modulo adattivo, puoi utilizzare funzioni personalizzate all'interno dell'editor di regole.
Aggiungiamo il codice seguente al file JavaScript (Function.js file) per calcolare l'età in base alla data di nascita (AAAA-MM-GG). Creare una funzione personalizzata come calculateAge() che utilizza come input la data di nascita e restituisce l'età:

    /**
        * Calculates Age
        * @name calculateAge
        * @param {object} field
        * @return {string}
    */

    function calculateAge(field) {
    var dob = new Date(field);
    var now = new Date();

    var age = now.getFullYear() - dob.getFullYear();
    var monthDiff = now.getMonth() - dob.getMonth();

    if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < dob.getDate())) {
    age--;
    }

    return age;
    }

Nell'esempio precedente, quando l'utente immette la data di nascita nel formato (AAAA-MM-GG), la funzione personalizzata calculateAge viene richiamata e restituisce l'età.

Funzione personalizzata Calcola età nelleditor di regole

Visualizziamo in anteprima il modulo per osservare come le funzioni personalizzate vengono implementate tramite l’editor di regole:

Funzione personalizzata Calcola età nelleditor di regole Anteprima modulo

NOTE

Puoi fare riferimento alla seguente cartella funzioni personalizzate. Scarica e installa questa cartella nella tua istanza AEM utilizzando Gestione pacchetti.

Supporto delle funzioni asincrone nelle funzioni personalizzate

Le funzioni personalizzate asincrone non vengono visualizzate nell’elenco dell’editor di regole. Tuttavia, è possibile richiamare funzioni asincrone all’interno di funzioni personalizzate create utilizzando espressioni di funzioni sincrone.

Sincronizza e sincronizza funzione personalizzata

NOTE

Il vantaggio di chiamare funzioni asincrone nelle funzioni personalizzate è che le funzioni asincrone consentono l’esecuzione simultanea di più attività, con il risultato di ogni funzione utilizzata all’interno delle funzioni personalizzate.

Osserva il codice seguente per scoprire come richiamare funzioni asincrone utilizzando funzioni personalizzate:


    async function asyncFunction() {
    const response = await fetch('https://petstore.swagger.io/v2/store/inventory');
    const data = await response.json();
    return data;
    }

    /**
    * callAsyncFunction
    * @name callAsyncFunction callAsyncFunction
    */
    function callAsyncFunction() {
    asyncFunction()
        .then(responseData => {
        console.log('Response data:', responseData);
        })
        .catch(error => {
         console.error('Error:', error);
    });
}

Nell'esempio precedente, la funzione asyncFunction è un asynchronous function. Esegue un'operazione asincrona effettuando una richiesta GET a https://petstore.swagger.io/v2/store/inventory. Attende la risposta utilizzando await, analizza il corpo della risposta come JSON utilizzando response.json(), quindi restituisce i dati. La funzione callAsyncFunction è una funzione personalizzata sincrona che richiama la funzione asyncFunction e visualizza i dati di risposta nella console. Sebbene la funzione callAsyncFunction sia sincrona, chiama la funzione asyncFunction asincrona e gestisce il risultato con then e catch istruzioni.

Per vedere come funziona, aggiungiamo un pulsante e creiamo una regola per il pulsante che richiama la funzione asincrona al clic di un pulsante.

creazione regola per funzione asincrona

Fare riferimento all'illustrazione della finestra della console seguente per dimostrare che quando l'utente fa clic sul pulsante Fetch, viene richiamata la funzione personalizzata callAsyncFunction, che a sua volta chiama una funzione asincrona asyncFunction. Inspect mostra la finestra della console per visualizzare la risposta al clic del pulsante:

Finestra della console

Approfondiamo le funzioni personalizzate.

Varie funzioni per funzioni personalizzate

È possibile utilizzare funzioni personalizzate per aggiungere caratteristiche personalizzate ai moduli. Queste funzioni supportano varie funzionalità, ad esempio l’utilizzo di campi specifici, l’utilizzo di campi globali o la memorizzazione in cache. Questa flessibilità consente di personalizzare i moduli in base ai requisiti aziendali.

Oggetti di ambito Field e Global nelle funzioni personalizzate

Gli oggetti Field fanno riferimento ai singoli componenti o elementi di un modulo, ad esempio campi di testo e caselle di controllo. L'oggetto Globals contiene variabili di sola lettura quali l'istanza del modulo, l'istanza del campo di destinazione e i metodi per apportare modifiche al modulo nelle funzioni personalizzate.

NOTE

param {scope} globals deve essere l'ultimo parametro e non viene visualizzato nell'editor di regole di un modulo adattivo.

Scopri in che modo le funzioni personalizzate utilizzano gli oggetti field e global con l'aiuto di un modulo Contact Us che utilizza casi d'uso diversi.

Modulo per contattarci

Caso d'uso: mostra un pannello utilizzando la regola `SetProperty`

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 setProperty dell'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.

Imposta proprietà

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.

Imposta anteprima modulo proprietà

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.

Imposta anteprima modulo proprietà

Caso d'uso: convalidare il campo.

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);

    }

NOTE

Se nella funzione 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:

Modello di convalida indirizzo e-mail

Il passaggio successivo consiste nel creare una regola per il pulsante Next che convalida il campo contact al clic del pulsante.

Modello di convalida

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:

Modello di convalida indirizzo e-mail

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:

Modello di convalida indirizzo e-mail

Caso d'uso: reimpostare un pannello

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);

    }

NOTE

Se nella funzione 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.

Cancella pulsante

Vedere l'illustrazione seguente per mostrare che se l'utente fa clic sul pulsante clear, il pannello personaldetails viene ripristinato:

Reimposta modulo

Caso d'uso: per visualizzare un messaggio personalizzato a livello di campo e contrassegnare il campo come non valido

È 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 il 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 il 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:

Contrassegna il campo come non valido

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:

Contrassegna il campo come modulo di anteprima non valido

Se l’utente immette più di 15 caratteri nella casella di testo Commenti, il campo viene convalidato e il modulo viene inviato:

Contrassegna il campo come modulo di anteprima valido

Caso d'uso: invio dei dati modificati al server

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. È optional ed è impostato come true per impostazione predefinita.
Il terzo argomento è contentType dell'inoltro, che è anche facoltativo con il valore predefinito multipart/form-data. Gli altri valori possono essere application/json e application/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:

Invia 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:

Invia dati nella finestra della console

È inoltre possibile esaminare la finestra della console per visualizzare i dati inviati al server:

Dati Inspect nella finestra della console

Supporto della memorizzazione in cache per la funzione personalizzata

Forms adattivo implementa il caching per le funzioni personalizzate per migliorare il tempo di risposta durante il recupero dell’elenco delle funzioni personalizzate nell’editor di regole. Nel file error.log viene visualizzato il messaggio Fetched following custom functions list from cache.

funzione personalizzata con supporto cache

Se le funzioni personalizzate vengono modificate, la memorizzazione in cache viene invalidata e analizzata.

Risoluzione dei problemi

L'utente deve verificare che il componente core e la versione della specifica siano impostati sulla versione più recente. 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') con submitForm() e distribuire il progetto.
- Per i moduli esistenti, se i gestori di invio personalizzati non funzionano correttamente, l'utente deve aprire e salvare la regola submitForm sul pulsante Invia utilizzando l'editor di regole. Questa azione sostituisce la regola esistente di submitForm('custom:submitSuccess', 'custom:submitError') con submitForm() nel modulo.
Se il file JavaScript contenente il codice per le funzioni personalizzate presenta un errore, le funzioni personalizzate non sono elencate nell’editor delle regole di un modulo adattivo. Per verificare l'elenco delle funzioni personalizzate, è possibile individuare l'errore nel file error.log. In caso di errore, l’elenco delle funzioni personalizzate appare vuoto:

In caso di errore, la funzione personalizzata viene recuperata e visualizzata nel file error.log. Nel file error.log viene visualizzato il messaggio Fetched following custom functions list:

Considerazioni

parameter type e return type non supportano None.
Le funzioni non supportate nell'elenco delle funzioni personalizzate sono:
- Funzioni del generatore
- Funzioni Async/Await
- Definizioni dei metodi
- Metodi di classe
- Parametri predefiniti
- Parametri rimanenti

recommendation-more-help

Funzioni personalizzate nei componenti core di Forms adattivi

Introduzione

Utilizzo di funzioni personalizzate

Annotazioni di JavaScript supportate per la funzione personalizzata

Nome

Parametro

Tipo restituito

Privata

Linee guida per la creazione di funzioni personalizzate

Istruzione function con o senza commenti jsdoc

Funzione freccia con annotazioni o commenti JavaScript obbligatori

Espressione di funzione con annotazioni o commenti JavaScript obbligatori

Prerequisiti per creare una funzione personalizzata

Creare una funzione personalizzata

Creare una libreria client utilizzando l’archetipo di progetto AEM

Creare e distribuire funzioni personalizzate tramite CRXDE

Aggiungere una libreria client in un modulo adattivo

Utilizzo di una funzione personalizzata in un modulo adattivo

Supporto delle funzioni asincrone nelle funzioni personalizzate

Varie funzioni per funzioni personalizzate

Oggetti di ambito Field e Global nelle funzioni personalizzate

Caso d'uso: mostra un pannello utilizzando la regola SetProperty

Caso d'uso: convalidare il campo.

Caso d'uso: reimpostare un pannello

Caso d'uso: per visualizzare un messaggio personalizzato a livello di campo e contrassegnare il campo come non valido

Caso d'uso: invio dei dati modificati al server

Supporto della memorizzazione in cache per la funzione personalizzata

Risoluzione dei problemi

Considerazioni

Caso d'uso: mostra un pannello utilizzando la regola `SetProperty`