Aggiungere un pulsante di azione personalizzato nell’interfaccia utente per la creazione di corrispondenza

Panoramica

La soluzione Gestione della corrispondenza consente di aggiungere azioni personalizzate all’interfaccia utente Crea corrispondenza.

Lo scenario di questo documento spiega come creare un pulsante nell’interfaccia utente per la creazione di corrispondenza per condividere una lettera come PDF di revisione allegato a un’e-mail.

Prerequisiti

Per completare questo scenario, è necessario disporre dei seguenti elementi:

• Conoscenza di CRX e JavaScript
• Server di LiveCycle

Scenario: creare il pulsante nell'interfaccia utente Crea corrispondenza per inviare una lettera per la revisione

L’aggiunta di un pulsante con un’azione (in questo caso, invia una lettera per la revisione) all’interfaccia utente per la creazione di corrispondenza include:

1. Aggiunta del pulsante all’interfaccia utente per la creazione di corrispondenza
2. Aggiunta della gestione delle azioni al pulsante
3. Aggiunta del processo di LiveCycle per abilitare la gestione delle azioni

Aggiungi il pulsante all’interfaccia utente Crea corrispondenza

1. Vai a https://'[server]:[port]'/[ContextPath]/crx/de e accedere come amministratore.

2. Nella cartella delle app, crea una cartella denominata defaultApp con un percorso/struttura simile alla cartella defaultApp (nella cartella di configurazione). Per creare la cartella, effettua le seguenti operazioni:

   1. Fare clic con il pulsante destro del mouse defaultApp cartella nel percorso seguente e selezionare Sovrapponi nodo:

      /libs/fd/cm/config/defaultApp/

      

   2. Assicurati che la finestra di dialogo Sovrapponi nodo abbia i seguenti valori:

      Percorso: /libs/fd/cm/config/defaultApp/

      Posizione sovrapposizione: /apps/

      Corrispondenza tipi di nodo: Selezionato

      

   3. Fai clic su OK.

   4. Clic Salva tutto.

3. Crea una copia del file acmExtensionsConfig.xml (presente nel ramo /libs) nel ramo /apps.

   1. Vai a "/libs/fd/cm/config/defaultApp/acmExtensionsConfig.xml"

   2. Fai clic con il pulsante destro del mouse sul file acmExtensionsConfig.xml e seleziona Copia.

      

   3. Fare clic con il pulsante destro del mouse defaultApp cartella in "/apps/fd/cm/config/defaultApp/" e seleziona Incolla.

   4. Clic Salva tutto.

4. Fai doppio clic sulla copia di acmExtentionsConfig.xml appena creata nella cartella delle app. Il file viene aperto per la modifica.

5. Individua il seguente codice:

   <?xml version="1.0" encoding="utf-8"?>
   <extensionsConfig>
       <modelExtensions>
           <modelExtension type="LetterInstance">
     <customAction name="Preview" label="loc.letterInstance.preview.label" tooltip="loc.letterInstance.preview.tooltip" styleName="previewButton"/>
               <customAction name="Submit" label="loc.letterInstance.submit.label" tooltip="loc.letterInstance.submit.tooltip" styleName="submitButton" permissionName="forms-users"/>
               <customAction name="SaveAsDraft" label="loc.letterInstance.saveAsDraft.label" tooltip="loc.letterInstance.saveAsDraft.tooltip" styleName="submitButton" permissionName="forms-users"/>
               <customAction name="Close" label="loc.letterInstance.close.label" tooltip="loc.letterInstance.close.tooltip" styleName="closeButton"/>
           </modelExtension>
       </modelExtensions>
   </extensionsConfig>
   

6. Per inviare una lettera via e-mail puoi utilizzare il Forms Workflow LiveCycle. Aggiungi un tag customAction sotto il tag modelExtension in acmExtensionsConfig.xml come segue:

    <customAction name="Letter Review" label="Letter Review" tooltip="Letter Review" styleName="" permissionName="forms-users" actionHandler="CM.domain.CCRCustomActionHandler">
         <serviceName>Forms Workflow -> SendLetterForReview/SendLetterForReviewProcess</serviceName>
       </customAction>
   

   

   Il tag modelExtension dispone di un set di tag figlio customAction che configurano l’azione, le autorizzazioni e l’aspetto del pulsante di azione. Di seguito è riportato l’elenco dei tag di configurazione customAction:

   Nome	Descrizione
   nome	Nome alfanumerico dell’azione da eseguire. Il valore di questo tag è obbligatorio, deve essere univoco (all’interno del tag modelExtension) e deve iniziare con un alfabeto.
   etichetta	Etichetta da visualizzare sul pulsante di azione
   descrizione comando	Testo della descrizione del pulsante, visualizzato quando l’utente passa il puntatore sul pulsante.
   styleName	Nome dello stile personalizzato applicato al pulsante di azione.
   permissionName	L'azione corrispondente viene visualizzata solo se l'utente dispone dell'autorizzazione specificata da permissionName. Quando si specifica permissionName come forms-users, tutti gli utenti hanno accesso a questa opzione.
   actionHandler	Nome completo della classe ActionHandler chiamata quando l'utente fa clic sul pulsante.

   A parte i parametri di cui sopra, ci possono essere configurazioni aggiuntive associate a un customAction. Queste configurazioni aggiuntive vengono rese disponibili al gestore tramite l'oggetto CustomAction.

   Nome	Descrizione
   serviceName	Se un customAction contiene un tag figlio denominato serviceName, facendo clic sul pulsante o sul collegamento corrispondente viene chiamato un processo il cui nome è rappresentato dal tag serviceName. Assicurarsi che il processo abbia la stessa firma della lettera PostProcess. Aggiungi il prefisso "Forms Workflow ->" nel nome del servizio.
   Parametri contenenti il prefisso cm_ nel nome del tag	Se un customAction contiene tag figlio che iniziano con name cm_, durante la fase di post-elaborazione (che si tratti di Letter Post Process o del processo speciale rappresentato dal tag serviceName) questi parametri sono disponibili nel codice XML di input sotto il tag pertinente con il prefisso cm_ rimosso.
   actionName	Ogni volta che un processo di post è dovuto a un clic, il codice XML inviato contiene un tag speciale con un nome sotto il tag con il nome dell’azione utente.

7. Clic Salva tutto.

Creare una cartella locale con il file delle proprietà nel ramo /apps

Il file ACMExtensionsMessages.properties include etichette e messaggi di descrizione dei vari campi nell'interfaccia utente Crea corrispondenza. Affinché le azioni/i pulsanti personalizzati funzionino, crea una copia di questo file nel ramo /apps.

1. Fare clic con il pulsante destro del mouse lingua cartella nel percorso seguente e selezionare Sovrapponi nodo:

   /libs/fd/cm/config/defaultApp/locale

2. Assicurati che la finestra di dialogo Sovrapponi nodo abbia i seguenti valori:

   Percorso: /libs/fd/cm/config/defaultApp/locale

   Posizione sovrapposizione: /apps/

   Corrispondenza tipi di nodo: Selezionato

3. Fai clic su OK.

4. Clic Salva tutto.

5. Fare clic con il pulsante destro del mouse sul file seguente e selezionare Copia:

   /libs/fd/cm/config/defaultApp/locale/ACMExtensionsMessages.properties

6. Fare clic con il pulsante destro del mouse lingua cartella nel percorso seguente e selezionare Incolla:

   /apps/fd/cm/config/defaultApp/locale/

   Il file ACMExtensionsMessages.properties viene copiato nella cartella locale.

7. Per localizzare le etichette dell'azione o del pulsante personalizzato appena aggiunto, creare il file ACMExtensionsMessages.properties per le impostazioni internazionali pertinenti in /apps/fd/cm/config/defaultApp/locale/.

   Ad esempio, per localizzare l’azione/pulsante personalizzato creato in questo articolo, crea un file denominato ACMExtensionsMessages_fr.properties con la seguente voce:

   loc.letterInstance.letterreview.label=Revue De Lettre

   Allo stesso modo, in questo file è possibile aggiungere altre proprietà, ad esempio per la descrizione comando e lo stile.

8. Clic Salva tutto.

Riavvia il bundle Adobe Asset Composer Building Block

Dopo aver apportato ogni modifica lato server, riavvia il bundle Adobe Asset Composer Building Block. In questo scenario, i file acmExtensionsConfig.xml e ACMExtensionsMessages.properties sul lato server vengono modificati e pertanto il bundle Adobe Asset Composer Building Block richiede un riavvio.

1. Passa a https://[host]:'port'/system/console/bundles. Se necessario, accedi come amministratore.

2. Individua il bundle Adobe Asset Composer Building Block. Riavvia il bundle: fai clic su Interrompi, quindi fai clic su Avvia.

   

Dopo aver riavviato il bundle Adobe Asset Composer Building Block, il pulsante personalizzato viene visualizzato nell’interfaccia utente per la creazione di corrispondenza. È possibile aprire una lettera nell’interfaccia utente Crea corrispondenza per visualizzare in anteprima il pulsante personalizzato.

Aggiungi gestione azioni al pulsante

Per impostazione predefinita, l’interfaccia utente per la creazione di corrispondenza presenta l’implementazione di ActionHandler nel file cm.domain.js nel percorso seguente:

/libs/fd/cm/ccr/gui/components/admin/clientlibs/ccr/js/cm.domain.js

Per la gestione delle azioni personalizzate, crea una sovrapposizione del file cm.domain.js nel ramo /apps di CRX.

La gestione dell’azione/pulsante al momento del clic sull’azione/pulsante include la logica per:

• Rendere visibile/invisibile l’azione appena aggiunta: operazione eseguita escludendo la funzione actionVisible().
• Abilitazione/disabilitazione dell’azione appena aggiunta: operazione eseguita escludendo la funzione actionEnabled().
• Gestione effettiva dell’azione quando l’utente fa clic sul pulsante: eseguita escludendo l’implementazione della funzione handleAction().

1. Passa a https://'[server]:[port]'/[ContextPath]/crx/de. Se necessario, accedi come amministratore.

2. Nella cartella delle app, crea una cartella denominata js nel ramo /apps di CRX con una struttura simile alla seguente cartella:

   /libs/fd/cm/ccr/gui/components/admin/clientlibs/ccrui/js

   Per creare la cartella, effettua le seguenti operazioni:

   1. Fare clic con il pulsante destro del mouse js cartella nel percorso seguente e selezionare Sovrapponi nodo:

      /libs/fd/cm/ccr/gui/components/admin/clientlibs/ccrui/js

   2. Assicurati che la finestra di dialogo Sovrapponi nodo abbia i seguenti valori:

      Percorso: /libs/fd/cm/ccr/gui/components/admin/clientlibs/ccrui/js

      Posizione sovrapposizione: /apps/

      Corrispondenza tipi di nodo: Selezionato

   3. Fai clic su OK.

   4. Clic Salva tutto.

3. Nella cartella js, crea un file denominato crcustomization.js con il codice per la gestione delle azioni del pulsante, seguendo la procedura riportata di seguito:

   1. Fare clic con il pulsante destro del mouse js cartella nel percorso seguente e selezionare Crea > Crea file:

      /apps/fd/cm/ccr/gui/components/admin/clientlibs/ccrui/js

      Denomina il file come customization.js.

   2. Fai doppio clic sul file customization.js per aprirlo in CRX.

   3. Nel file, incolla il seguente codice e fai clic su Salva tutto:

      /* for adding and handling custom actions in Extensible Toolbar.
        * One instance of handler will be created for each action.
        * CM.domain.CCRCustomActionHandler is actionHandler class.
        */
      var CCRCustomActionHandler;
          CCRCustomActionHandler = CM.domain.CCRCustomActionHandler = new Class({
              className: 'CCRCustomActionHandler',
              extend: CCRDefaultActionHandler,
              construct : function(action,model){
              }
          });
          /**
           * Called when user user click an action
           * @param extraParams additional arguments that may be passed to handler (For future use)
           */
          CCRCustomActionHandler.prototype.handleAction = function(extraParams){
              if (this.action.name == CCRCustomActionHandler.SEND_FOR_REVIEW) {
                  var sendForReview = function(){
                      var serviceName = this.action.actionConfig["serviceName"];
                      var inputParams = {};
                      inputParams["dataXML"] = this.model.iccData.data;
                      inputParams["letterId"] = this.letterVO.id;
                      inputParams["letterName"] = this.letterVO.name;
                      inputParams["mailId"] = $('#email').val();
                      /*function to invoke the LivecyleService */
                      ServiceDelegate.callJSONService(this,"lc.icc.renderlib.serviceInvoker.json","invokeProcess",[serviceName,inputParams],this.onProcessInvokeComplete,this.onProcessInvokeFail);
                      $('#ccraction').modal("hide");
                  }
                  if($('#ccraction').length == 0){
                      /*For first click adding popup & setting letterName.*/
                      $("body").append(popUp);
                      $("input[id*='letterName']").val(this.letterVO.name);
                      $(document).on('click',"#submitLetter",$.proxy( sendForReview, this ));
                  }
                  $('#ccraction').modal("show");
              }
          };
          /**
           * Should the action be enabled in toolbar
           * @param extraParams additional arguements that may be passed to handler (For future use)
           * @return flag indicating whether the action should be enabled
           */
         CCRCustomActionHandler.prototype.actionEnabled = function(extraParams){
                  /*can be customized as per user requirement*/
                  return true;
          };
          /**
           * Should the action be visible in toolbar
           * @param extraParams additional arguments that may be passed to handler (For future use)
           * @return flag indicating whether the action should be enabled
           */
          CCRCustomActionHandler.prototype.actionVisible = function(extraParams){
              /*Check can be enabled for Non-Preview Mode.*/
              return true;
          };
          /*SuccessHandler*/
          CCRCustomActionHandler.prototype.onProcessInvokeComplete = function(response) {
              ErrorHandler.showSuccess("Letter Sent for Review");
          };
          /*FaultHandler*/
          CCRCustomActionHandler.prototype.onProcessInvokeFail = function(event) {
              ErrorHandler.showError(event.message);
          };
          CCRCustomActionHandler.SEND_FOR_REVIEW  = "Letter Review";
      /*For PopUp*/
          var popUp = '<div class="modal fade" id="ccraction" tabindex="-1" role="dialog" aria-hidden="true">'+
          '<div class="modal-dialog modal-sm">'+
              '<div class="modal-content">' +
                  '<div class="modal-header">'+
                      '<button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</code></button>'+
                      '<h4 class="modal-title"> Send Review </h4>'+
                  '</div>'+
                  '<div class="modal-body">'+
                      '<form>'+
                          '<div class="form-group">'+
                              '<label class="control-label">Email Id</label>'+
                              '<input type="text" class="form-control" id="email">'+
                          '</div>'+
                          '<div class="form-group">'+
                              '<label  class="control-label">Letter Name</label>'+
                              '<input id="letterName" type="text" class="form-control" readonly>'+
                          '</div>'+
                          '<div class="form-group">'+
                              '<input id="letterData" type="text" class="form-control hide" readonly>'+
                          '</div>'+
                      '</form>'+
                  '</div>'+
                  '<div class="modal-footer">'+
                     '<button type="button" class="btn btn-default" data-dismiss="modal"> Cancel </button>'+
                     '<button type="button" class="btn btn-primary" id="submitLetter"> Submit </button>'+
                  '</div>'+
              '</div>'+
          '</div>'+
      '</div>';
      

Aggiungi il processo di LiveCycle per abilitare l’azione gestione

In questo scenario, abilita i seguenti componenti, che fanno parte del file components.zip allegato:

• JAR del componente DSC (DSCSample.jar)
• Invia lettera per processo di revisione LCA (SendLetterForReview.lca)

Scarica e decomprimi il file components.zip per ottenere i file DSCSample.jar e SendLetterForReview.lca. Utilizzare questi file come specificato nelle procedure seguenti.
Ottieni file

Configurare il server di LiveCycle per eseguire il processo LCA

Il processo LCA viene eseguito sul server di LiveCycle e richiede l'indirizzo del server e le credenziali di accesso.

1. Vai a https://'[server]:[port]'/system/console/configMgr e accedere come amministratore.

2. Individua la configurazione Adobe LiveCycle Client SDK e fai clic su Modifica (icona di modifica). Viene visualizzato il pannello Configurazioni.

3. Immetti i seguenti dettagli e fai clic su Salva:

   • URL server: URL del server LC di cui il codice del gestore azioni utilizza il servizio Send For Review.
   • Nome utente: nome utente amministratore del server LC
   • Password: password del nome utente amministratore

   

Installa archivio LiveCycle (LCA)

Processo di LiveCycle richiesto che abilita il processo del servizio e-mail.

1. Accedi come amministratore all’interfaccia utente di LiveCycle® Server all’indirizzo https:/[lc server]/:[lc port]/adminui.

2. Accedi a Home > Servizi > Applicazioni e servizi > Gestione delle applicazioni.

3. Se l'applicazione SendLetterForReview è già presente, ignorare i passaggi rimanenti di questa procedura, altrimenti continuare con i passaggi successivi.

   

4. Clic Importa.

5. Clic Scegli file e selezionare SendLetterForReview.lca.

   

6. Clic Anteprima.

7. Seleziona Distribuire le risorse in fase di esecuzione al termine dell’importazione.

8. Clic Importa.

Aggiunta di ServiceName all'elenco dei servizi di Inserisce nell'elenco Consentiti di in corso

Nel server di Experience Manager, indicare i servizi di LiveCycle che si desidera accedere al server di Experience Manager.

1. Accedi come amministratore a https:/[host]:'port'/system/console/configMgr.

2. Individua e fai clic su Adobe configurazione dell’SDK del client del LiveCycle. Viene visualizzato il pannello Configurazione di Adobe LiveCycle Client SDK.

3. Nell'elenco Nome servizio fare clic sull'icona + e aggiungere un nome servizio SendLetterForReview/SendLetterForReviewProcess.

4. Fai clic su Salva.

Configurare il servizio e-mail

In questo scenario, affinché Gestione della corrispondenza possa inviare un messaggio e-mail, configura il servizio e-mail nel server di LiveCycle.

1. Accedi con le credenziali amministratore all’interfaccia utente di LiveCycle Server all’indirizzo https:/[lc server]:[lc port]/adminui.

2. Accedi a Home > Servizi > Applicazioni e servizi > Gestione dei servizi.

3. Individua e fai clic su EmailService.

4. In entrata Host SMTP, configura il servizio e-mail.

5. Fai clic su Salva.

Configurare il servizio DSC

Per utilizzare l’API di gestione della corrispondenza, scarica DSCSample.jar (allegato in questo documento come parte di components.zip) e caricalo sul server di LiveCycle. Dopo il caricamento del file DSCSample.jar nel server di LiveCycle, il server di Experience Manager utilizza il file DSCSample.jar per accedere all’API renderLetter.

Per ulteriori informazioni, consulta Collegamento di AEM Forms con Adobe LiveCycle.

1. Aggiorna l’URL del server di Experience Manager in cmsa.properties in DSCSample.jar, che si trova nella seguente posizione:

   DSCSample.jar\com\adobe\livecycle\cmsa.properties

2. Fornisci i seguenti parametri nel file di configurazione:

   • crx.serverUrl=https:/host:port/[percorso di contesto]/[URL AEM]
   • crx.username= nome utente Experience Manager
   • crx.password= password Experience Manager
   • crx.appRoot=/content/apps/cm
   NOTA

   Ogni volta che si apportano modifiche sul lato server, riavviare il server di LiveCycle.

   Il file DSCSample.jar utilizza l’API renderLetter. Per ulteriori informazioni sull’API renderLetter, consulta LetterRenderService dell'interfaccia.

Importa DSC in LiveCycle

Il file DSCSample.jar utilizza l'API renderLetter per eseguire il rendering della lettera come byte PDF dai dati XML forniti da DSC come input. Per ulteriori informazioni su renderLetter e altre API, consulta Servizio di rendering delle lettere.

1. Avvia Workbench e accedi.

2. Seleziona Finestra > Mostra viste > Componenti. La vista Componenti viene aggiunta a Workbench ES2.

3. Clic con il pulsante destro Componenti e seleziona Installa componente.

4. Seleziona la DSCSample.jar dal browser dei file e fai clic su Apri.

5. Clic con il pulsante destro RenderWrapper e seleziona Avvia componente. Se il componente viene avviato, accanto al nome del componente viene visualizzata una freccia verde.

Invia lettera per revisione

Dopo aver configurato l’azione e il pulsante per l’invio della lettera per la revisione:

1. Cancella la cache del browser.

2. Nell’interfaccia utente Crea corrispondenza, fai clic su Revisione lettera e specifica l’ID e-mail del revisore.

3. Fai clic su Invia.

Il revisore riceve un'e-mail dal sistema con la lettera come allegato PDF.