Introduzione alle funzioni personalizzate per Forms adattivo basato su componenti core

Versione
Collegamento articolo
AEM 6.5
Fai clic qui
AEM as a Cloud Service
Questo articolo

AEM Forms supporta funzioni personalizzate che consentono agli utenti di definire funzioni JavaScript per l’implementazione di regole aziendali complesse. Queste funzioni personalizzate estendono le funzionalità dei moduli facilitando la manipolazione e l’elaborazione dei dati immessi per soddisfare requisiti specifici. Consentono di modificare dinamicamente il comportamento delle forme in base a criteri predefiniti. Le funzioni personalizzate consentono inoltre agli sviluppatori di applicare logiche di convalida complesse, eseguire calcoli dinamici e controllare la visualizzazione o il comportamento degli elementi del modulo in base alle interazioni dell'utente o a criteri predefiniti.

NOTE
Verificare che il componente core sia impostato sulla versione più recente per utilizzare le funzionalità più recenti.

Utilizzo di funzioni personalizzate uses-of-custom-function

L’utilizzo di funzioni personalizzate in Adaptive Forms offre i seguenti vantaggi:

  • 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, una 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 JavaScript vengono utilizzate per fornire 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

Il nome 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>.
    functionName è il nome della funzione. Gli spazi non sono consentiti.
    <Function Name> è il nome visualizzato della funzione nell'editor di regole di un modulo adattivo.
    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 all'interno di funzioni personalizzate. Viene dichiarato come ultimo parametro nelle annotazioni di JavaScript e non è visibile nell’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 non fa 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.

Parametri facoltativi

Per impostazione predefinita, tutti i parametri sono obbligatori. È possibile definire un parametro come facoltativo aggiungendo = dopo il tipo di parametro o racchiudendo il nome del parametro in []. I parametri definiti come facoltativi nelle annotazioni di JavaScript vengono visualizzati come facoltativi nell’editor di regole.
Per definire una variabile come parametro facoltativo, è possibile utilizzare una delle sintassi seguenti:

  • @param {type=} Input1

Nella riga di codice precedente, Input1 è un parametro facoltativo senza alcun valore predefinito. Per dichiarare un parametro facoltativo con valore predefinito:
@param {string=<value>} input1

input1 come parametro facoltativo con il valore predefinito impostato su value.

  • @param {type} [Input1]

Nella riga di codice precedente, Input1 è un parametro facoltativo senza alcun valore predefinito. Per dichiarare un parametro facoltativo con valore predefinito:
@param {array} [input1=<value>]
input1 è un parametro facoltativo di tipo array con il valore predefinito impostato su value.
Assicurarsi che il tipo di parametro sia racchiuso tra parentesi graffe {} e che il nome del parametro sia racchiuso tra parentesi quadre.

Considera il seguente frammento di codice, in cui input2 è definito come parametro opzionale:

        /**
         * optional parameter function
         * @name OptionalParameterFunction
         * @param {string} input1
         * @param {string=} input2
         * @return {string}
        */
        function OptionalParameterFunction(input1, input2) {
        let result = "Result: ";
        result += input1;
        if (input2 !== null) {
            result += " " + input2;
        }
        return result;
        }

Nell'illustrazione seguente viene visualizzato l'utilizzo della funzione personalizzata OptionalParameterFunction nell'editor di regole:

Parametri facoltativi o obbligatori

Puoi salvare la regola senza specificare un valore per i parametri richiesti, ma la regola non viene eseguita e visualizza un messaggio di avviso come:

avviso regola incompleto

Quando l’utente lascia vuoto il parametro opzionale, il valore "Undefined" (Non definito) viene passato alla funzione personalizzata per il parametro opzionale.

Per ulteriori informazioni su come definire parametri facoltativi in JSDocs, fai clic qui.

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.

Passaggio successivo

Per creare e utilizzare una funzione personalizzata nel modulo adattivo, consulta l'articolo Creare una funzione personalizzata per un modulo adattivo basato su componenti core.

Consulta anche

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab