Show Menu
SUJETS×

Outil de conversion de boîte de dialogue

L’outil de conversion de boîte de dialogue mis à votre disposition permet d’étendre les composants existants dont une boîte de dialogue est définie uniquement pour l’interface utilisateur classique (sur la base d’ExtJS) ou sur la base de l’interface utilisateur (IU) Granite et de Coral 2. Cet outil utilise la boîte de dialogue d’origine pour créer une boîte de dialogue en double conçue pour l’interface utilisateur standard, sur la base de l’IU Granite et de Coral 3.
L’objectif de cet outil est d’automatiser la mise à niveau (dans la mesure du possible), de garantir une efficacité accrue et de réduire les erreurs. L’outil ne peut toutefois pas couvrir tous les cas de figure. Dès lors, le processus ne peut pas être entièrement automatisé, et l’utilisateur doit examiner les boîtes de dialogue converties et peut-être y apporter des modifications supplémentaires. Cet outil est conçu pour vous aider à lancer la procédure de conversion, mais pas pour prendre le contrôle total de la conversion.
L’outil va créer la boîte de dialogue à l’aide de l’IU basée sur Coral 3 et de l’IU Granite standard, mais il ignorera les éléments qu’il ne parvient pas à convertir. Il se peut donc que la boîte de dialogue qui en résulte contienne des nœuds de la boîte de dialogue d’origine, copiés tels quels, si aucune règle ne correspondait à ce composant spécifique. En outre, un composant converti peut comporter quelques propriétés non converties, car il n’existait aucune règle appropriée pour les convertir.
L’outil n’est pas adapté à tous les scénarios, dans la mesure où ses règles de conversion ne sont pas exhaustives et fonctionnent selon le principe du meilleur effort. Il convertit les propriétés et éléments les plus souvent utilisés, mais la conversion est incomplète lorsqu’il s’agit de personnalisations ou de boîtes de dialogue très spécialisées. Les boîtes de dialogue converties peuvent nécessiter des réglages supplémentaires et toutes les conversions doivent être analysées.
L’interface utilisateur n’étant plus développée ni améliorée, Adobe conseille aux clients de passer à l’IU Granite par défaut pour bénéficier des dernières avancées technologiques.
Bien qu’il soit généralement préférable de migrer vers la plate-forme la plus récente, passer de Coral 2 à Coral 3 n’est pas indispensable. Cependant, tout nouveau projet doit être commencé dans Coral 3.

Téléchargement et installation de l’outil de conversion de boîte de dialogue

L’outil de conversion de boîte de dialogue est désormais disponible en Open Source. Vous pouvez y accéder via GitHub.
CODE SUR GITHUB
Vous pouvez trouver le code de cette page sur GitHub.
AEM n’est pas livré avec l’outil de conversion de boîte de dialogue. Vous devez le télécharger et l’installer pour pouvoir l’utiliser.
Procédez comme suit pour installer l’outil de conversion de boîte de dialogue :
  1. Téléchargez le module à partir du projet GitHub Dialog Conversion Tool .
  2. Installez le module sur votre instance. Pour plus d’informations sur la gestion des modules, voir Utilisation des modules .

Conversion d’une boîte de dialogue

L’outil convertit les boîtes de dialogue en créant une boîte de dialogue correspondante dans l’interface Granite / Coral 3 au même emplacement que la boîte de dialogue d’origine dans l’arborescence de contenu. In the case of Granite UI / Coral 2 dialogs, these are copied to a backup location (a .coral2 suffix is appended to the dialog node name) so as not to be overridden. L’outil peut convertir aussi bien des boîtes de dialogue de conception que des boîtes de dialogue de modification.
Procédez comme suit pour convertir une ou plusieurs boîtes de dialogue :
  1. Open the Dialog Conversion console, accessible from Global Navigation -> Tools -> Operations :
    https://<hostname>:<port>/libs/cq/dialogconversion/content/console.html
  2. Enter the required path such as /apps/geometrixx/components . You can also enter a direct path to a single dialog such as /apps/geometrixx/components/lead .
  3. Sélectionnez Afficher les boîtes de dialogue pour afficher toutes les boîtes de dialogue situées sous cet emplacement.
    Le tableau répertorie toutes les boîtes de dialogue héritées existantes sous le chemin saisi. Chaque boîte de dialogue a son type répertorié. Les types sont les suivants :
    • Classique : Noeuds de type cq:Dialog qui ont un nom de noeud dialog ou design_dialog
    • Corail 2 : Noeuds nommés cq:dialog ou cq:design_dialog dont le type de ressource Interface utilisateur Granite / Coral 2 se trouve sur leur noeud de contenu enfant Chaque ligne contient un lien pour afficher la boîte de dialogue et un autre lien vers CRXD Lite pour afficher la structure de son nœud.
    Les composants qui ne possèdent pas de boîte de dialogue pour l’IU classique ou Coral 2 (en d’autres termes, l’IU Granite/Coral 3 a été utilisée pour la conception) ne sont pas répertoriés.
  4. Select one or more dialogs for conversion and click or tap Convert X dialog(s) to start the conversion process.
  5. Les boîtes de dialogue sélectionnées sont répertoriées avec les résultats de leurs conversions. Si la conversion a réussi, la ligne contient des liens pour afficher la boîte de dialogue convertie ou pour l’ouvrir dans CRXDE Lite.
    Cliquez ou appuyez sur Précédent pour revenir à l’outil conversion de boîte de dialogue.
  6. De retour dans l’outil de conversion de boîte de dialogue, les boîtes de dialogue converties ne figurent plus dans la liste. Notez toutefois que le nombre total de boîtes de dialogue trouvées est toujours indiqué, y compris celles qui sont déjà converties ; en d’autres termes, le nombre de lignes du tableau ne correspond pas nécessairement au nombre trouvé.
  7. Cochez l’option Afficher les boîtes de dialogue converties pour afficher les boîtes de dialogue situées à l’emplacement spécifié et qui ont déjà été converties.
    Si la boîte de dialogue est déjà convertie, des liens sont également fournis à la boîte de dialogue convertie. Une boîte de dialogue est considérée comme convertie si une boîte de dialogue IU Granite/Coral 3 est déjà disponible.

Règles de réécriture des boîtes de dialogue

The dialog conversion tool is based on the concept of graph rewriting , consisting of transforming a subject graph by applying rewrite rules. Une règle de réécriture consiste à coupler un motif à un graphe de remplacement. La règle fait correspondre les occurrences d’un sous-graphe donné dans le graphe de sujet, puis les remplace. See also https://en.wikipedia.org/wiki/Graph_rewriting for details on graph rewriting.
L’outil de conversion de boîte de dialogue applique cette méthode pour réécrire une arborescence héritée donnée (IU classique ou Granite/Coral 2) dans l’arborescence IU Granite/Coral 3 équivalente. Grâce à cette méthode, la conversion se révèle extrêmement souple et peut même tenir compte de composants complexes, étant donné que la correspondance est effectuée sur des sous-arborescences réelles et pas seulement sur des nœuds ou des propriétés uniques.

Algorithme

L’algorithme de réécriture accepte comme paramètre l’arborescence à réécrire et un ensemble de règles de réécriture. Il·effectue·un·parcours préfixe de l’arborescence et, pour chaque nœud, il vérifie si une règle s’applique à la sous-arborescence dont la racine se situe au niveau de ce nœud. La première règle qui correspond est appliquée à cette sous-arborescence afin de la réécrire. La traversée redémarre ensuite depuis la racine. L’algorithme s’arrête dès que toute l’arborescence a été parcourue et que plus aucune règle ne correspond à une sous-arborescence. En tant que mesure d’optimisation, l’algorithme effectue le suivi d’un ensemble de noeuds qui sont définitifs et ne doivent donc pas être revus pour les correspondances lors des traversées suivantes. Il appartient aux règles de réécriture de déterminer quels sont les nœuds définitifs dans l’arborescence réécrite et lesquels devront faire l’objet d’une nouvelle visite lors des prochains passages de l’algorithme.
The entry point for the conversion is the DialogConversionServlet , which is registered on POST requests to /libs/cq/dialogconversion/content/convert.json . Il accepte un paramètre de requête de chemin, qui est un tableau contenant les chemins d’accès aux boîtes de dialogue à convertir. Pour chaque boîte de dialogue, le servlet réécrit ensuite l’arborescence correspondante en appliquant toutes les règles de réécriture des boîtes de dialogue définies.

Types de règles de réécriture

Les règles de réécriture peuvent être définies de deux manières :
Some are provided out-of-the-box , but you can also define your own customized rules. Des exemples de règles de réécriture sont également disponibles.
En règle générale, une seule règle de réécriture de boîte de dialogue est chargée de réécrire un seul élément ; le champ de saisie pathbrowser, par exemple.
Rewrite loops are not detected by the algorithm, therefore rewrite rules must not rewrite trees in a circular fashion .

Règles de réécriture basées sur des nœuds

Une règle de réécriture de boîtes de dialogue peut être définie en termes de nœuds et de propriétés :
rule
  - jcr:primaryType = nt:unstructured
  - cq:rewriteRanking = 4
  + patterns
    - jcr:primaryType = nt:unstructured
    + foo
      - ...
      + ...
    + foo1
      - ...
      + ...
  + replacement
    + bar
      - ...
      + ...

Cet exemple définit une règle contenant deux modèles (arborescences dont les racines sont foo et foo1 ) et un remplacement (arborescence dont la racine est bar ). Les arborescences modèles et de remplacement sont des arborescences arbitraires contenant des nœuds et des propriétés. La règle correspond à une sous-arborescence si l’un des modèles définis correspond. Pour qu’un modèle corresponde, l’arborescence en question doit contenir les mêmes nœuds (correspondance de noms). De plus, toutes les propriétés définies dans le modèle doivent correspondre à celles de l’arborescence.
Dans le cas d’une correspondance, la sous-arborescence correspondante (appelée arbre d’origine) sera remplacée par le remplacement. L’arborescence de remplacement peut définir des propriétés mappées qui hériteront de la valeur d’une propriété de l’arborescence d’origine. Elles doivent être du type String et présenter le format suivant :
${<path>}
Si la propriété référencée n’existe pas dans l’arborescence d’origine, la propriété est omise. Une valeur par défaut peut également être spécifiée dans ce cas de figure (cela n’est possible que pour les propriétés String) :
${<path>:<default>}
Properties that contain ' : ' characters can be single quoted to avoid conflict with providing a default value. Boolean properties are negated if the expression is prefixed with ' ! '. Les propriétés mappées peuvent être à plusieurs valeurs, auquel cas la valeur de la première propriété qui existe dans l’arborescence correspondante leur sera affectée.
Par exemple, la valeur de la propriété one ./two/three de l’arborescence d’origine correspondante est affectée à la propriété suivante.
...
  + replacement
    + bar
      - one = ${./two/three}
      - negated = !${./some/boolean/prop}
      - default = ${./some/prop:default}
      - multi = [${./prop1}, ${./prop2}]

Les règles prennent également en charge les propriétés facultatives suivantes.
  • cq:rewriteOptional (booléen)
    Définissez cette propriété sur un noeud de modèle pour indiquer que le noeud n’a pas besoin d’être présent pour que le modèle corresponde
  • cq:rewriteRanking (integer)
    Définissez cette propriété sur le noeud de règle pour affecter l’ordre d’application des règles. Cela peut s’avérer utile pour faire en sorte que les règles génériques n’écrasent pas des règles qui gèrent des structures plus spécifiques. Les règles de classement inférieur sont prioritaires sur celles de classement plus élevé. All rules by default receive Integer.MAX_VALUE as their ranking.
L’arborescence de remplacement prend également en charge les propriétés spéciales suivantes (commençant par cq:rewrite ) :
  • cq:rewriteMapChildren (chaîne)
    The node containing this property will receive a copy of the children of the node in the original tree referenced by the property value (e.g. cq:rewriteMapChildren=./items ).
  • cq:rewriteFinal (booléen)
    Il s’agit d’une mesure d’optimisation qui indique à l’algorithme que le noeud contenant cette propriété est final et qu’il n’est pas nécessaire de le vérifier à nouveau pour rechercher des règles de réécriture correspondantes. Lorsqu’il est placé sur le noeud de remplacement lui-même, l’arborescence de remplacement est considérée comme définitive.
  • cq:rewriteCommonAttrs (booléen)
    Set this property on the replacement node ( rule / replacement ) to map relevant properties of the original root node to Granite common attribute equivalents in the copy root. It will handle data attributes by copying/creating the granite:data subnode on the target and writing data-* properties there.
  • cq:rewriteRenderCondition (booléen)
    Set this property on the replacement node ( rule / replacement ) to copy any Granite render condition ( rendercondition or granite:rendercondition ) child node from the original root node to a granite:rendercondition child of the copy root.
In addition, a cq:rewriteProperties node can be added to a replacement node to define string rewrites for mapped properties in the result. Le nœud est supprimé du remplacement. The properties of the cq:rewriteProperties node must be named the same as those which they are rewriting and accept a string array with two parameters:
  • pattern : Regex à comparer, par ex. "(?:coral-Icon-)(.+)"
  • replacement : Fourni à la replaceAll fonction de correspondance, p. ex. "$1"
Voici un exemple de réécriture des propriétés d’icône Coral 2 sur les propriétés Coral 3 équivalentes :
...
  + replacement
    + bar
      - icon = ${./icon}
      + cq:rewriteProperties
       - icon = [(?:coral-Icon--)(.+), $1]

Définition de vos propres règles de réécriture basées sur des nœuds

Les règles de réécriture fournies sont définies à l’emplacement suivant :
/libs/cq/dialogconversion/rules
Les règles y sont subdivisées dans deux dossiers pour les règles de réécriture classiques et les règles de réécriture Coral 2 :
/libs/cq/dialogconversion/rules/classic
/libs/cq/dialogconversion/rules/coral2
Ces règles peuvent être écrasées en fournissant un ensemble de règles à l’adresse suivante :
/apps/cq/dialogconversion/rules
You can copy /libs/cq/dialogconversion/rules to /apps then modify existing and/or add new rules to this new instance ``.

Règles de réécriture Java

Des règles de réécriture plus complexes peuvent être définies sous la forme de classes Java qui exposent un service OSGi de l’interface : com.adobe.cq.dialogconversion.DialogRewriteRule .
Une classe de ce type doit mettre en œuvre les méthodes suivantes :
boolean matches(Node root) throws RepositoryException;
Node applyTo(Node root, Set<Node> finalNodes) throws DialogRewriteException, RepositoryException;
int getRanking();

The matches method must return true if the rule matches the subtree rooted at the supplied root node. If the rule matches, the tree rewriting algorithm will subsequently call the applyTo method, which must rewrite the subtree rooted at the specified root node. En règle générale, cette méthode renomme temporairement l’arborescence d’origine, crée l’arborescence en tant que nouvel enfant de son nœud parent (à l’aide de ses nœuds et propriétés) et, pour terminer, supprime l’arborescence d’origine. More detailed information can be found in the Javadoc of the com.adobe.cq.dialogconversion.DialogRewriteRule interface.

Informations supplémentaires – Javadocs

Pour plus d’informations, voir Javadocs pour com.adobe.cq.dialogconversion .

Définition de vos propres règles de réécriture Java

The following class shows an example of a custom rewrite rule implementing the com.adobe.cq.dialogconversion.DialogRewriteRule interface.
@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() {
        // ...
    }

}

Alternatively, you can extend com.adobe.cq.dialogconversion.AbstractDialogRewriteRule as below. The abstract class implements the getRanking method and uses the service.ranking OSGi property of the service to determine the ranking of the rule.
@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 {
        // ...
    }

}

Règles de réécriture fournies

The cq-dialog-conversion-content package contains several predefined rewrite rules. For classic UI widgets see Using xtypes for more information).
Règle Composant hérité Interface utilisateur granitique / Remplacement du corail 3
com.adobe.cq.dialogconversion.rules.CqDialogRewriteRule Noeud de type cq:Dialog , gère différentes sous-structures
Une granite/ui/components/foundation/container utilisation d’une fixedcolumns ou d’une tabs mise en page
Les composants réels de la boîte de dialogue sont copiés et réécrits dans les passages suivants de l’algorithme.
com.adobe.cq.dialogconversion.rules.IncludeRule xtype = cqinclude Le noeud référencé est copié dans la boîte de dialogue Granite UI / Coral 3 et (éventuellement) réécrit par la suite par l’algorithme.
com.adobe.cq.dialogconversion.rules.MultifieldRewriteRule xtype = multifield
A granite/ui/components/coral/foundation/form/multifield
Le noeud fieldConfig enfant (le cas échéant) est réécrit séparément, ce qui ne limite pas les composants pris en charge.
/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

Exemples de règles de réécriture

CODE SUR GITHUB
Vous pouvez trouver le code de cette page sur GitHub.