Show Menu
ARGOMENTI×

Creare un aspetto personalizzato per i campi modulo adattivi

Introduzione

I moduli adattivi sfruttano il framework Struttura di aspetto per moduli adattivi e HTML5 degli aspetti per consentire all'utente di creare aspetto personalizzati per i campi dei moduli adattivi e offrire un'esperienza diversa. Ad esempio, sostituire pulsanti di scelta e caselle di controllo con pulsanti di attivazione/disattivazione oppure utilizzare i plug-in jQuery personalizzati per limitare gli input degli utenti in campi quali numeri di telefono o ID e-mail.
Questo documento spiega come utilizzare un plug-in jQuery per creare queste esperienze alternative per i campi modulo adattivi. Inoltre, mostra un esempio per creare un aspetto personalizzato per il componente Campo numerico affinché venga visualizzato come un passo o un cursore numerico.
Vediamo innanzitutto i termini e i concetti chiave utilizzati in questo articolo.
Aspetto Si riferisce allo stile, all’aspetto e all’organizzazione di vari elementi di un campo modulo adattivo. In genere include un'etichetta, un'area interattiva per fornire gli input, un'icona della guida e descrizioni brevi e lunghe del campo. La personalizzazione dell'aspetto descritta in questo articolo è applicabile all'aspetto dell'area di input del campo.
plugin jQuery Fornisce un meccanismo standard, basato sul framework di widget jQuery, per implementare un aspetto alternativo.
ClientLib Un sistema di librerie lato client nell'elaborazione lato client AEM basata su codice JavaScript e CSS complessi. Per ulteriori informazioni, consultate Utilizzo delle librerie lato client.
Archetype Un progetto Maven che modella toolkit definito come modello o modello originale per i progetti Maven. Per ulteriori informazioni, vedere Introduzione ai tipi di archivio.
Controllo utente Si riferisce all'elemento principale di un widget che contiene il valore del campo ed è utilizzato dal framework di aspetto per il binding dell'interfaccia utente dei widget personalizzata con il modello di modulo adattivo.

Passaggi per creare un aspetto personalizzato

Per creare un aspetto personalizzato, ad alto livello effettuate le seguenti operazioni:
  1. Crea un progetto : Create un progetto Maven che genera un pacchetto di contenuti da distribuire su AEM.
  2. Estendi una classe widget esistente: Estendete una classe di widget esistente e ignorate le classi richieste.
  3. Creare una libreria client: Create una clientLib: af.customwidget libreria e aggiungete i file JavaScript e CSS richiesti.
  4. Create e installate il progetto : Create il progetto Maven e installate il pacchetto di contenuti generato in AEM.
  5. Aggiornare il modulo adattivo: Aggiornare le proprietà dei campi modulo adattivi per utilizzare l'aspetto personalizzato.

Creazione di un progetto

Un archetipo di cielo è un punto di partenza per la creazione di un aspetto personalizzato. I dettagli dell'archetipo da utilizzare sono i seguenti:
  • Repository : https://repo.adobe.com/nexus/content/groups/public/
  • Id Artifact: custom-appearance-archetype
  • ID gruppo: com.adobe.aemforms
  • Versione : 1.0.4
Esegui il comando seguente per creare un progetto locale basato su archetype:
mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
Il comando scarica i plug-in Maven e le informazioni archetype dalla directory archivio e genera un progetto basato sulle seguenti informazioni:
  • groupId : ID gruppo utilizzato dal progetto Maven generato
  • artifactId : ID artefatto utilizzato dal progetto Maven generato.
  • versione : Versione per il progetto Maven generato.
  • pacchetto : Pacchetto utilizzato per la struttura del file.
  • artifactName : Nome dell'artefatto del pacchetto AEM generato.
  • packageGroup : Gruppo di pacchetti del pacchetto AEM generato.
  • widgetName : Nome dell'aspetto usato come riferimento.
Il progetto generato ha la struttura seguente:
─<artifactId>

 └───src

     └───main

         └───content

             └───jcr_root

                 └───etc

                     └───clientlibs

                         └───custom

                             └───<widgetName>

                                 ├───common [client library - af.customwidgets which encapsulates below clientLibs]

                                 ├───integration [client library - af.customwidgets.<widgetName>_widget which contains template files for integrating a third-party plugin with Adaptive Forms]

                                 │   ├───css

                                 │   └───javascript

                                 └───jqueryplugin [client library - af.customwidgets.<widgetName>_plugin which holds the third-party plugins and related dependencies]

                                     ├───css

                                     └───javascript

Estendi una classe widget esistente

Dopo aver creato il modello di progetto, effettuate le seguenti modifiche, come necessario:
  1. Includete la dipendenza del plug-in di terze parti nel progetto.
    1. Inserite i plug-in jQuery di terze parti o personalizzati nella jqueryplugin/javascript cartella e nei relativi file CSS nella jqueryplugin/css cartella. Per ulteriori dettagli, consultate i file JS e CSS nella jqueryplugin/javascript and jqueryplugin/css cartella.
    2. Modificate i file js.txt e css.txt i file in modo da includere eventuali file JavaScript e CSS aggiuntivi del plug-in jQuery.
  2. Integrate il plug-in di terze parti con il framework per consentire l'interazione tra il framework di aspetto personalizzato e il plug-in jQuery. Il nuovo widget funzionerà solo dopo l’estensione o l’esclusione delle seguenti funzioni.
Funzione Descrizione
render La funzione di rendering restituisce l'oggetto jQuery per l'elemento HTML predefinito del widget. L'elemento HTML predefinito deve essere di tipo attivabile. Ad esempio <a> , <input> , e <li> . L'elemento restituito viene utilizzato come $userControl . Se $userControl specifica il vincolo di cui sopra, le funzioni della AbstractWidget classe funzionano come previsto, altrimenti alcune delle API comuni (attivazione, clic) richiedono modifiche.
getEventMap Restituisce una mappa per convertire gli eventi HTML in eventi XFA. { blur: XFA_EXIT_EVENT, } Questo esempio mostra che blur si tratta di un evento HTML e XFA_EXIT_EVENT che corrisponde all'evento XFA corrispondente.
getOptionsMap Restituisce una mappa che fornisce informazioni dettagliate sull'azione da eseguire al cambio di un'opzione. Le chiavi sono le opzioni fornite al widget e i valori sono funzioni che vengono chiamate ogni volta che viene rilevata una modifica nell'opzione. Il widget fornisce gestori per tutte le opzioni comuni (tranne value e displayValue ).
getCommitValue Il framework di widget jQuery carica la funzione ogni volta che il valore del widget jQuery viene salvato nel modello XFA (ad esempio, in corrispondenza dell'evento exit di un campo di testo). L’implementazione deve restituire il valore salvato nel widget. Al gestore viene fornito il nuovo valore per l'opzione.
showValue Per impostazione predefinita, in XFA all'evento enter, viene visualizzato il rawValue nome del campo. Questa funzione viene chiamata per mostrare l' rawValue utente.
showDisplayValue Per impostazione predefinita, in XFA all'uscita l'evento formattedValue del campo viene visualizzato. Questa funzione viene chiamata per mostrare l' formattedValue utente.
  1. Aggiornate il file JavaScript nella integration/javascript cartella, come necessario.
    • Sostituite il testo __widgetName__ con il nome effettivo del widget.
    • Estendete il widget da una classe di widget out-of-the-box adeguata. Nella maggior parte dei casi, Si tratta della classe widget corrispondente al widget esistente che viene sostituito. Il nome della classe principale viene utilizzato in più posizioni, pertanto si consiglia di cercare tutte le istanze della stringa xfaWidget.textField nel file e sostituirle con la classe padre effettiva utilizzata.
    • Estende il render metodo per fornire un’interfaccia utente alternativa. Si tratta del percorso dal quale verrà richiamato il plug-in jQuery per aggiornare l'interfaccia utente o il comportamento di interazione. Il render metodo deve restituire un elemento controllo utente.
    • Estendi il getOptionsMap metodo per ignorare qualsiasi impostazione di opzione interessata da una modifica nel widget. La funzione restituisce una mappatura che fornisce i dettagli dell'azione da eseguire in caso di modifica di un'opzione. Le chiavi sono le opzioni fornite al widget e i valori sono le funzioni richiamate ogni volta che viene rilevata una modifica nell'opzione.
    • Il getEventMap metodo mappa gli eventi attivati dal widget, con gli eventi richiesti dal modello di modulo adattivo. Il valore predefinito mappa gli eventi HTML standard per il widget predefinito e deve essere aggiornato se viene attivato un evento alternativo.
    • La clausola showDisplayValue e showValue l'applicazione di visualizzazione e modifica dell'immagine possono essere ignorate per avere un comportamento alternativo.
    • Il getCommitValue metodo viene chiamato dal framework di moduli adattivi quando si verifica l' commit evento. Generalmente si tratta dell'evento exit, ad eccezione degli elementi a discesa, pulsante di scelta e casella di controllo in cui si verifica al momento della modifica. Per ulteriori informazioni, vedere Espressioni per moduli adattivi .
    • Il file modello fornisce un esempio di implementazione per vari metodi. Rimuovere metodi che non devono essere estesi.

Creare una libreria client

Il progetto di esempio generato dall'archetipo Maven crea automaticamente le librerie client necessarie e le racchiude in una libreria client con una categoria af.customwidgets . I file JavaScript e CSS disponibili in af.customwidgets vengono inclusi automaticamente in fase di esecuzione.

Creare e installare

Per creare il progetto, eseguite il comando seguente sulla shell per generare un pacchetto CRX da installare nel server AEM.
mvn clean install
Il progetto maven si riferisce a un repository remoto all'interno del file POM. Questo è solo a scopo di riferimento, e secondo gli standard di Maven, le informazioni del repository vengono acquisite nel settings.xml file.

Aggiornare il modulo adattivo

Per applicare l'aspetto personalizzato a un campo modulo adattivo:
  1. Aprire il modulo adattivo in modalità di modifica.
  2. Aprire la finestra di dialogo Proprietà relativa al campo in cui si desidera applicare l'aspetto personalizzato.
  3. Nella scheda Stile , aggiornare la CSS class proprietà per aggiungere il nome dell'aspetto nel widget_<widgetName> formato. Ad esempio: widget_numericstepper

Esempio: Creare un aspetto personalizzato

Esaminiamo ora un esempio per creare un aspetto personalizzato per un campo numerico che verrà visualizzato come un passo o un cursore numerico. Effettuate le seguenti operazioni:
  1. Esegui il comando seguente per creare un progetto locale basato su Maven archetype:
    mvn archetype:generate -DarchetypeRepository=https://repo.adobe.com/nexus/content/groups/public/ -DarchetypeGroupId=com.adobe.aemforms -DarchetypeArtifactId=custom-appearance-archetype -DarchetypeVersion=1.0.4
    Viene richiesto di specificare i valori per i seguenti parametri. I valori utilizzati in questo esempio sono evidenziati in grassetto .
    Define value for property 'groupId': com.adobe.afwidgets
    Define value for property 'artifactId': customWidgets
    Define value for property 'version': 1.0.1-SNAPSHOT
    Define value for property 'package': com.adobe.afwidgets
    Define value for property 'artifactName': customWidgets
    Define value for property 'packageGroup': adobe/customWidgets
    Define value for property 'widgetName': numericStepper
  2. Andate alla directory customWidgets (valore specificato per la artifactID proprietà) ed eseguite il comando seguente per generare un progetto Eclipse:
    mvn eclipse:eclipse
  3. Aprite lo strumento Eclipse ed effettuate le seguenti operazioni per importare il progetto Eclipse:
    1. Selezionare File > Importa > Progetti esistenti in Workspace .
    2. Individuate e selezionate la cartella in cui è stato eseguito il archetype:generate comando.
    3. Click Finish .
  4. Selezionate il widget da usare per l’aspetto personalizzato. Questo esempio utilizza il seguente widget per passo numerico:
    Nel progetto Eclipse, controlla il codice plug-in nel plugin.js file per assicurarsi che corrisponda ai requisiti per l'aspetto. In questo esempio, l'aspetto soddisfa i seguenti requisiti:
    • Lo stepper numerico deve estendersi da - $.xfaWidget.numericInput .
    • Il set value metodo del widget imposta il valore dopo che lo stato attivo è sul campo. È un requisito obbligatorio per un widget modulo adattivo.
    • Per richiamare il render bootstrapNumber metodo è necessario sostituire il metodo.
    • Non esiste alcuna dipendenza aggiuntiva per il plug-in diversa dal codice sorgente principale del plug-in.
    • L'esempio non esegue alcuno stile sullo stepper, pertanto non è necessario alcun CSS aggiuntivo.
    • L' $userControl oggetto deve essere disponibile per il render metodo. È un campo del text tipo che viene clonato con il codice del plugin.
    • Se il campo è disabilitato, i + e i pulsanti devono essere disattivati.
  5. Sostituite il contenuto del bootstrap-number-input.js (plug-in jQuery) con il contenuto del numericStepper-plugin.js file.
  6. Nel numericStepper-widget.js file, aggiungete il seguente codice per ignorare il metodo di rendering per richiamare il plug-in e restituire l' $userControl oggetto:
    render : function() {
         var control = $.xfaWidget.numericInput.prototype.render.apply(this, arguments);
         var $control = $(control);
         var controlObject;
         try{
             if($control){
             $control.bootstrapNumber();
             var id = $control.attr("id");
             controlObject = $("#"+id);
             }
         }catch (exc){
              console.log(exc);
         }
         return controlObject;
    }
    
    
  7. Nel numericStepper-widget.js file, ignorare la getOptionsMap proprietà per ignorare l'opzione di accesso e nascondere i pulsanti + e - in modalità disattivata.
    getOptionsMap: function(){
        var parentOptionsMap = $.xfaWidget.numericInput.prototype.getOptionsMap.apply(this,arguments),
    
        newMap = $.extend({},parentOptionsMap,
    
         {
    
               "access": function(val) {
               switch(val) {
                  case "open" :
                    this.$userControl.removeAttr("readOnly");
                    this.$userControl.removeAttr("aria-readonly");
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
                  case "nonInteractive" :
                  case "protected" :
                    this.$userControl.attr("disabled", "disabled");
                    this.$userControl.attr("aria-disabled", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                 case "readOnly" :
                    this.$userControl.attr("readOnly", "readOnly");
                    this.$userControl.attr("aria-readonly", "true");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',true);
                    break;
                default :
                    this.$userControl.removeAttr("disabled");
                    this.$userControl.removeAttr("aria-disabled");
                    this.$userControl.parent().find(".input-group-btn button").prop('disabled',false);
                    break;
              }
           },
       });
       return newMap;
     }
    
    
  8. Salvate le modifiche, individuate la cartella che contiene il pom.xml file ed eseguite il seguente comando Maven per creare il progetto:
    mvn clean install
  9. Installate il pacchetto utilizzando AEM Package Manager.
  10. Aprite il modulo adattivo in modalità di modifica in cui desiderate applicare l’aspetto personalizzato ed effettuate le seguenti operazioni:
    1. Fare clic con il pulsante destro del mouse sul campo in cui si desidera applicare l'aspetto e scegliere Modifica per aprire la finestra di dialogo Modifica componente.
    2. Nella scheda Stile, aggiornare la proprietà della classe ​CSS da aggiungere widget_numericStepper .
Il nuovo aspetto appena creato è ora disponibile per l’uso.