Strumento di conversione finestra

Lo strumento di conversione della finestra di dialogo consente di estendere i componenti esistenti che dispongono solo di una finestra di dialogo definita per l’interfaccia classica (in base a ExtJS) o in base all’interfaccia Granite e al Coral 2. Lo strumento utilizza la finestra di dialogo originale per creare una finestra di dialogo duplicata progettata per l’interfaccia standard, in base all’interfaccia Granite e al Corallo 3.

L'obiettivo di questo strumento è automatizzare l'aggiornamento per quanto possibile, aumentare l'efficienza e ridurre gli errori. Tuttavia, poiché lo strumento non è in grado di coprire ogni scenario, il processo non può essere completamente automatizzato e l'utente deve rivedere le finestre di dialogo convertite ed eventualmente apportare ulteriori modifiche. Lo strumento è inteso come aiuto per avviare il processo di conversione, ma non per prendere il controllo completo della conversione.

Lo strumento crea la nuova finestra di dialogo utilizzando l’interfaccia standard Granite e l’interfaccia utente basata su Coral 3, ma ignora ciò che non può convertire. Pertanto, la finestra di dialogo risultante potrebbe contenere nodi della finestra di dialogo originale copiati così com'è, se nessuna regola corrispondeva a quel componente specifico. Inoltre, un componente convertito potrebbe avere alcune proprietà non convertite, perché non esisteva una regola appropriata per convertirle.

Download e installazione dello strumento di conversione finestra di dialogo

Lo strumento di conversione della finestra di dialogo è stato reso open source e può essere utilizzato tramite GitHub.

CODICE SU GITHUB

Puoi trovare il codice di questa pagina su GitHub

• Apri progetto di conversione aem-dialog su GitHub
• Scarica il progetto come un file ZIP

Per installare lo strumento di conversione della finestra di dialogo, effettuate le seguenti operazioni.

1. Scaricate il pacchetto dal progetto Dialog Conversion Tool GitHub project.
2. Installate il pacchetto nell’istanza. Per informazioni dettagliate sulla gestione dei pacchetti, vedere Come lavorare con i pacchetti.

Conversione di una finestra di dialogo

Lo strumento converte le finestre di dialogo creando una corrispondente finestra di dialogo Granite UI / Corallo 3 nella stessa posizione della finestra di dialogo originale nella struttura del contenuto. Nel caso delle finestre di dialogo Granite UI/Coral 2, queste vengono copiate in una posizione di backup (il suffisso .coral2 viene aggiunto al nome del nodo di dialogo) per non essere ignorato. Lo strumento consente di convertire finestre di dialogo di progettazione e di modifica.

Per convertire una o più finestre di dialogo, effettuate le seguenti operazioni:

1. Aprire la console di conversione finestra di dialogo accessibile da Navigazione globale -> Strumenti -> Operazioni :

   https://<hostname>:<port>/libs/cq/dialogconversion/content/console.html

   

2. Immettere il percorso richiesto, ad esempio /apps/geometrixx/components. Potete anche inserire un percorso diretto a una singola finestra di dialogo, ad esempio /apps/geometrixx/components/lead.

   

3. Selezionare Mostra finestre di dialogo per visualizzare tutte le finestre di dialogo al di sotto di tale posizione.

   

   Nella tabella sono elencate tutte le finestre di dialogo precedenti esistenti sotto il percorso immesso. Ogni finestra di dialogo ha il relativo tipo elencato. I tipi includono:

   • Classic: nodi di tipo cq:Dialog con nome nodo dialog o design_dialog
   • Corallo 2: Nodi denominati cq:dialog o cq:design_dialog con un tipo di risorsa Granite UI/Corallo 2 nel nodo di contenuto figlio

   Ogni riga contiene un collegamento per visualizzare la finestra di dialogo e un collegamento al CRXDE Lite per visualizzarne la struttura del nodo.

   NOTA

   Non sono elencati i componenti che non dispongono di alcuna finestra di dialogo per l’interfaccia classica o per il Corallo 2 (ovvero progettati con l’interfaccia Granite / Coral 3).

4. Selezionare una o più finestre di dialogo per la conversione e fare clic o toccare Converti finestre di dialogo X per avviare il processo di conversione.

   

5. Le finestre di dialogo selezionate sono elencate con i risultati delle conversioni. Se la conversione ha avuto esito positivo, la riga contiene collegamenti per visualizzare la finestra di dialogo convertita o per aprirla in CRXDE Lite.

   Tocca o fai clic su Indietro per tornare allo strumento di conversione finestra di dialogo.

   

6. Nello strumento di conversione finestra di dialogo, le finestre di dialogo convertite non vengono più visualizzate nell’elenco. Si noti tuttavia che il numero totale di finestre di dialogo trovate è ancora elencato, comprese quelle già convertite, ovvero il numero di righe nella tabella non corrisponde necessariamente a quello del numero trovato.

   

7. Selezionare l'opzione Mostra finestre di dialogo convertite per visualizzare le finestre di dialogo che si trovano nel percorso specificato e che sono già state convertite.

   

   Se la finestra di dialogo è già stata convertita, vengono forniti anche i collegamenti alla finestra di dialogo convertita. Una finestra di dialogo viene considerata convertita se è già disponibile un'interfaccia Granite di pari livello / Corallo 3.

Regole di riscrittura finestra di dialogo

Lo strumento di conversione della finestra di dialogo si basa sul concetto di riscrittura del grafico a, consistente nella trasformazione di un grafico a oggetti mediante l'applicazione di regole di riscrittura. Una regola di riscrittura è l'accoppiamento di un pattern con un grafico di sostituzione. La regola corrisponde alle occorrenze di un determinato sottografico nel grafico dell'oggetto e le sostituisce successivamente. Per informazioni dettagliate sulla riscrittura del grafico, vedere anche https://en.wikipedia.org/wiki/Graph_rewriting.

Lo strumento di conversione della finestra di dialogo utilizza questo approccio per riscrivere una determinata struttura di dialogo precedente (interfaccia classica o granita / Corallo 2) nell’interfaccia Granite / Corallo 3 corrispondente. Questo ha il vantaggio che la conversione è altamente flessibile e può prendere in considerazione anche componenti complessi, poiché la corrispondenza viene fatta su sottostrutture reali e non solo nodi o proprietà singoli.

Algoritmo

L'algoritmo di riscrittura utilizza come parametro la struttura ad albero da riscrittare e un insieme di regole di riscrittura. Attraversa la struttura ad albero in pre-ordine e per ogni nodo verifica se è applicata una regola per la sottostruttura ad albero radicata in quel nodo. La prima regola che corrisponde viene applicata alla sottostruttura per riscriverla. Il traversal quindi si riavvia dalla radice. L'algoritmo si arresta non appena l'intero albero è stato attraversato e nessuna regola ha trovato corrispondenza in alcuna sottostruttura. Come misura di ottimizzazione, l'algoritmo tiene traccia di un insieme di nodi che sono finali e quindi non devono essere ricontrollati per le corrispondenze nei successivi traversaggi. È compito delle regole di riscrittura definire quali nodi della struttura riscritta sono finali e quali dovrebbero essere rivisitati da passaggi futuri dell'algoritmo.

Il punto di ingresso per la conversione è il DialogConversionServlet, che viene registrato sulle richieste POST a /libs/cq/dialogconversion/content/convert.json. Accetta un parametro di richiesta del percorso, ovvero un array contenente i percorsi delle finestre di dialogo da convertire. Per ogni finestra di dialogo, il servlet riscrive quindi la struttura di dialogo corrispondente applicando tutte le regole di riscrittura di finestra di dialogo definite.

Riscrittura tipi di regole

Le regole di riscrittura possono essere definite in due modi diversi:

• Strutture nodo JCR - Regole di riscrittura basate su nodo

• Classi Java che implementano un'interfaccia specifica - Regole di riscrittura basate su Java

Alcuni sono forniti out-of-the-box, ma è anche possibile definire regole personalizzate. Sono disponibili anche regole di riscrittura di esempio.

In genere, una singola regola di riscrittura finestra di dialogo è responsabile della riscrittura di un singolo elemento di dialogo, ad esempio il campo di immissione del browser percorso.

Regole di riscrittura basate su nodo

Una regola di riscrittura finestra di dialogo può essere definita in termini di nodi e proprietà.

rule
  - jcr:primaryType = nt:unstructured
  - cq:rewriteRanking = 4
  + patterns
    - jcr:primaryType = nt:unstructured
    + foo
      - ...
      + ...
    + foo1
      - ...
      + ...
  + replacement
    + bar
      - ...
      + ...

In questo esempio viene definita una regola contenente due pattern (gli alberi radicati in foo e foo1) e una sostituzione (l'albero radice in bar). Le strutture e gli alberi di sostituzione sono strutture arbitrarie contenenti nodi e proprietà. La regola corrisponde a una sottostruttura se uno dei pattern definiti corrisponde. Affinché un pattern corrisponda, la struttura ad albero dell'oggetto deve contenere gli stessi nodi del pattern (nomi corrispondenti) e tutte le proprietà definite nel pattern devono corrispondere alle proprietà della struttura.

Nel caso di una corrispondenza, la sottostruttura associata (denominata albero originale) verrà sostituita dalla sostituzione. La struttura di sostituzione può definire proprietà mappate che erediteranno il valore di una proprietà nella struttura originale. Devono essere di tipo String e avere il formato seguente:

${<path>}

Se la proprietà di riferimento non esiste nella struttura originale, la proprietà viene omessa. In alternativa, è possibile specificare un valore predefinito per tale caso (solo per le proprietà stringa):

${<path>:<default>}

Le proprietà che contengono caratteri ' :' possono essere virgolette singole per evitare conflitti con la fornitura di un valore predefinito. Le proprietà booleane vengono negate se l'espressione ha il prefisso " !". Le proprietà mappate possono essere multivalore, nel qual caso gli verrà assegnato il valore della prima proprietà esistente nella struttura ad albero corrispondente.

Ad esempio, alla seguente proprietà one verrà assegnato il valore della proprietà ./two/three della struttura originale corrispondente.

...
  + replacement
    + bar
      - one = ${./two/three}
      - negated = !${./some/boolean/prop}
      - default = ${./some/prop:default}
      - multi = [${./prop1}, ${./prop2}]

Le regole supportano anche le seguenti proprietà facoltative.

• cq:rewriteOptional (booleano)

  Impostare questa proprietà su un nodo di pattern per indicare che il nodo non deve essere presente affinché il pattern corrisponda

• cq:rewriteRanking (numero intero)

  Impostate questa proprietà sul nodo della regola per influenzare l'ordine in base al quale vengono applicate le regole. Ciò può essere utile per garantire che le regole che gestiscono strutture più specifiche non vengano sovrascritte da quelle più generali. Le regole con una classificazione inferiore hanno la precedenza su quelle con una classificazione superiore. Per impostazione predefinita, tutte le regole ricevono Integer.MAX_VALUE come classifica.

La struttura di sostituzione supporta anche le seguenti proprietà speciali (denominate a partire da cq:rewrite):

• cq:rewriteMapChildren (stringa)

  Il nodo contenente questa proprietà riceverà una copia degli elementi secondari del nodo nella struttura originale a cui fa riferimento il valore della proprietà (ad es. cq:rewriteMapChildren=./items).

• cq:rewriteFinal (booleano)

  Questa è una misura di ottimizzazione che indica all'algoritmo che il nodo contenente questa proprietà è definitivo e non deve essere ricontrollato per cercare regole di riscrittura corrispondenti. Quando viene posizionato sul nodo di sostituzione stesso, l'intero albero di sostituzione è considerato finale.

• cq:rewriteCommonAttrs (booleano)

  Impostate questa proprietà sul nodo di sostituzione ( rule/ replacement) per mappare le proprietà rilevanti del nodo principale originale sugli equivalenti di attributi comuni Granite nella radice della copia. Gestisce gli attributi dei dati copiando/creando il nodo secondario granite:data sulla destinazione e scrivendo le proprietà data-*.

• cq:rewriteRenderCondition (booleano)

  Impostate questa proprietà sul nodo di sostituzione ( rule/ replacement) per copiare qualsiasi condizione di rendering Granite ( rendercondition o granite:rendercondition) nodo secondario dal nodo principale originale a un nodo secondario granite:rendercondition della radice di copia.

Inoltre, un nodo cq:rewriteProperties può essere aggiunto a un nodo di sostituzione per definire le riscritture delle stringhe per le proprietà mappate nel risultato. Il nodo viene rimosso dalla sostituzione. Le proprietà del nodo cq:rewriteProperties devono essere denominate come quelle che stanno riscrivendo e accettano una matrice di stringhe con due parametri:

• pattern: Regex per la corrispondenza, ad esempio "(?:coral-Icon-)(.+)"

• replacement: Fornita alla replaceAll funzione matcher, ad esempio "$1"

Di seguito è riportato un esempio di riscrittura delle proprietà dell'icona Coral 2 negli equivalenti Coral 3:

...
  + replacement
    + bar
      - icon = ${./icon}
      + cq:rewriteProperties
       - icon = [(?:coral-Icon--)(.+), $1]

Definizione delle regole di riscrittura basate su nodo

Le regole di riscrittura fornite sono definite in:

/libs/cq/dialogconversion/rules

Le regole sono ulteriormente divise in questa posizione in cartelle per le regole di riscrittura classiche e le regole di riscrittura Coral 2:

/libs/cq/dialogconversion/rules/classic

/libs/cq/dialogconversion/rules/coral2

Tali norme possono essere sovrascritte fornendo una serie di norme al seguente indirizzo:

/apps/cq/dialogconversion/rules

È possibile copiare /libs/cq/dialogconversion/rules in /apps e quindi modificare le regole esistenti e/o aggiungere nuove regole a questa nuova istanza ".

Regole di riscrittura basate su Java

Regole di riscrittura più complesse possono essere definite come classi Java che espongono un servizio OSGi dell'interfaccia com.adobe.cq.dialogconversion.DialogRewriteRule.

Tale classe deve implementare i seguenti metodi:

boolean matches(Node root) throws RepositoryException;
Node applyTo(Node root, Set<Node> finalNodes) throws DialogRewriteException, RepositoryException;
int getRanking();

Il metodo matches deve restituire true se la regola corrisponde alla struttura ad albero secondaria radicata nel nodo principale fornito. Se la regola corrisponde, l'algoritmo di riscrittura della struttura chiamerà in seguito il metodo applyTo, che deve riscrivere la sottostruttura ad albero radicata nel nodo principale specificato. Solitamente, questo metodo rinominerà temporaneamente la struttura originale, genererà la nuova struttura come nuovo nodo secondario del nodo padre della struttura originale (utilizzando i relativi nodi e proprietà) e infine rimuoverà la struttura ad albero originale. Informazioni più dettagliate sono reperibili nel Javadoc dell'interfaccia com.adobe.cq.dialogconversion.DialogRewriteRule.

Ulteriori informazioni - Javadocs

Per ulteriori informazioni, vedere le Javadocs per com.adobe.cq.dialogconversion.

Definizione delle proprie regole di riscrittura basate su Java

La classe seguente mostra un esempio di regola di riscrittura personalizzata che implementa l'interfaccia com.adobe.cq.dialogconversion.DialogRewriteRule.

@Component
@Service
public class CustomDialogRewriteRule implements DialogRewriteRule {

    public boolean matches(Node root) throws RepositoryException {
        // ...
    }

    public Node applyTo(Node root, Set<Node> finalNodes) throws DialogRewriteException, RepositoryException {
        // ...
    }

    int getRanking() {
        // ...
    }

}

In alternativa, è possibile estendere com.adobe.cq.dialogconversion.AbstractDialogRewriteRule come segue. La classe astratta implementa il metodo getRanking e utilizza la proprietà OSGi service.ranking del servizio per determinare la classificazione della regola.

@Component
@Service
@Properties({
        @Property(name="service.ranking", intValue = 10)
})
public class CustomDialogRewriteRule extends AbstractDialogRewriteRule {

    public boolean matches(Node root) throws RepositoryException {
        // ...
    }

    public Node applyTo(Node root, Set<Node> finalNodes) throws RewriteException, RepositoryException {
        // ...
    }

}

Regole di riscrittura fornite

Il pacchetto cq-dialog-conversion-content contiene diverse regole di riscrittura predefinite. Per i widget dell'interfaccia classica, consultate Utilizzo di xtype per ulteriori informazioni).

Regola	Componente legacy	Interfaccia utente Granite / Sostituzione Corallo 3
com.adobe.cq.dialogconversion.rules.CqDialogRewriteRule	Nodo di tipo cq:Dialog, gestisce sottostrutture diverse	A granite/ui/components/foundation/container utilizzando un layout fixedcolumns o tabs I componenti effettivi della finestra di dialogo vengono copiati e riscritti in passaggi successivi dell’algoritmo.
com.adobe.cq.dialogconversion.rules.IncludeRule	xtype = cqinclude	Il nodo a cui si fa riferimento viene copiato nella finestra di dialogo Granite UI / Corallo 3 e (eventualmente) riscritto dall'algoritmo.
com.adobe.cq.dialogconversion.rules.MultifieldRewriteRule	xtype = multifield	A granite/ui/components/coral/foundation/form/multifield Il nodo secondario fieldConfig (se presente) viene riscritto separatamente, senza limitare i componenti supportati.
/libs/cq/dialogconversion/rules/classic	button checkbox colorfield combobox componentselector datetime fieldset fileupload hidden numberfield panel password pathfield radio radiogroup select sizefield tabpanel tags textarea textfield
/libs/cq/dialogconversion/rules/coral2	actionfield autocomplete button checkbox collapsible colorpicker container datepicker fieldset fileupload fixedcolumns heading hidden hyperlink include multifield nestedcheckboxlist nestedcheckboxlist-checkbox numberfield password pathbrowser radio radiogroup reset select submit switch tabs tags text textarea textfield userpicker well

Regole di riscrittura di esempio

CODICE SU GITHUB

Puoi trovare il codice di questa pagina su GitHub

• Open aem-touch-dialogconversion-samples project on GitHub
• Scarica il progetto come un file ZIP