Funzioni personalizzate nei componenti core di Forms adattivi

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

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.

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 uses-of-custom-function

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

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 js-annotations

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:

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:

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:

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 considerations

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:

Creare una funzione personalizzata create-custom-function

I passaggi per creare funzioni personalizzate sono i seguenti:

Creare una libreria client utilizzando l’archetipo di progetto AEM create-client-library-archetype

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

Aggiungi file e cartelle alla cartella Libreria client

Aggiungi quanto segue alla cartella della libreria client aggiunta:

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

Includi la nuova cartella nel file filter.xml:

Creare e distribuire funzioni personalizzate tramite CRXDE create-add-custom-function

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:

È 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 add-client-library

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

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

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 use-custom-functions

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à.

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

Supporto delle funzioni asincrone nelle funzioni personalizzate support-of-async-functions

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.

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.

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:

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 support-field-and-global-objects

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.

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.

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

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.

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

    }

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:

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

    }

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:

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:

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:

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 Commenti, il campo viene convalidato e il modulo viene inviato:

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.

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:

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.

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

Risoluzione dei problemi troubleshooting

Considerazioni