Vous consultez actuellement l'aide de la version:

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.

Attention :

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.

Remarque :

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.

Remarque :

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 IU Granite/Coral 3 au même emplacement que la boîte de dialogue d’origine dans l’arborescence de contenu. S’agissant des boîtes de dialogue IU Granite/Coral 2, elles sont copiées dans un emplacement de secours (un suffixe .coral2 est ajouté au nom du nœud de boîte de dialogue) pour empêcher tout écrasement. 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. Ouvrez la console Conversion de boîte de dialogue, accessible à partir de Navigation globale -> Outils -> Opérations :

    http://<nom_hôte>:<port>/libs/cq/dialogconversion/content/console.html

    chlimage_1
  2. Saisissez le chemin d’accès requis ; /apps/geometrixx/components, par exemple. Vous pouvez également indiquer un chemin d’accès direct vers une seule boîte de dialogue ; /apps/geometrixx/components/lead, par exemple.

    chlimage_1
  3. Sélectionnez Afficher les boîtes de dialogue pour afficher toutes les boîtes de dialogue situées sous cet emplacement.

    chlimage_1

    Le tableau répertorie toutes les boîtes de dialogue existantes situées sous le chemin d’accès saisi. Le type de chaque boîte de dialogue est répertorié. Les types sont les suivants : 

    • Classique : nœuds de type cq:Dialog dont le nom de nœud est dialog ou design_dialog
    • Coral 2 : nœuds nommés cq:dialog ou cq:design_dialog ayant le type de ressource IU Granite/Coral 2 au niveau de son nœud 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.

    Remarque :

    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. Sélectionnez une ou plusieurs boîtes de dialogue à convertir ou appuyez sur Convertir X boîte(s) de dialogue pour lancer le processus de conversion.

    chlimage_1
  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.

    chlimage_1
  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é.

    chlimage_1
  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.

    chlimage_1

    Si la boîte de dialogue a déjà été convertie, des liens permettant d’y accéder sont également fournis. 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

L’outil de conversion de boîte de dialogue repose sur le concept de réécriture de graphes qui consiste à transformer un graphe de sujet en appliquant des règles de réécriture. 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. Pour en savoir plus sur la réécriture de graphes, voir aussi http://en.wikipedia.org/wiki/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. À des fins d’optimisation, l’algorithme effectue le suivi d’un ensemble de nœuds définitifs et pour lesquels aucune nouvelle correspondance ne devra donc être recherchée dans les traversées ultérieures. 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.

Le point d’entrée de la conversion est DialogConversionServlet, lequel est enregistré sur les requêtes POST dans /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 qui doivent être converties. 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 :

Certaines d’entre elles sont prêtes à l’emploi, mais vous pouvez également définir vos propres règles personnalisées. 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.

Attention :

Les boucles de réécriture n’étant pas détectées par l’algorithme, les règles de réécriture ne doivent pas réécrire des arborescences de manière circulaire.

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 en cas de correspondance de l’un des modèles définis. 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.

Si une correspondance est trouvée, l’arborescence de remplacement se substitue à la sous-arborescence concernée (appelée arborescence d’origine). 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>}

Les propriétés qui contiennent le caractère « : » peuvent être placées entre guillemets simples afin d’éviter tout conflit lors de la saisie d’une valeur par défaut. Les propriétés booléennes sont refusées si l’expression est précédée de « ! ». Les propriétés mappées peuvent comporter plusieurs valeurs. Dans ce cas, elles se voient attribuer la valeur de la première propriété existant dans l’arborescence correspondante.

Par exemple, la propriété suivante one se verra attribuer la valeur de la propriété ./two/three de l’arborescence d’origine correspondante. 

...
  + 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 nœud de modèle pour indiquer que la présence du nœud n’est pas nécessaire pour que le modèle corresponde.

  • cq:rewriteRanking (entier)
    Définissez cette propriété sur un nœud 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é. Toutes les règles se voient attribuer, par défaut, le classement Integer.MAX_VALUE.

L’arborescence de remplacement prend également en charge les propriétés spéciales suivantes (commençant par cq:rewrite) :

  • cq:rewriteMapChildren (chaîne)
    Le nœud contenant cette propriété reçoit une copie des enfants du nœud de l’arborescence d’origine référencé par la valeur de propriété (par exemple, cq:rewriteMapChildren=./items).

  • cq:rewriteFinal (booléen)
    Il s’agit d’une mesure d’optimisation qui indique à l’algorithme que le nœud qui contient cette propriété est définitif et qu’il ne doit pas faire l’objet d’une nouvelle recherche de règles de réécriture correspondantes. L’intégralité de l’arborescence de remplacement est considérée comme finale lorsqu’elle est placée sur le nœud de remplacement proprement dit.

  • cq:rewriteCommonAttrs (booléen)
    Définissez cette propriété sur le nœud de remplacement (règle/remplacement) pour mapper les propriétés appropriées du nœud racine d’origine sur les attributs communs équivalents dans la racine de copie. Cette propriété gère les attributs de données en copiant/créant le sous-nœud granite:data sur la cible et en y écrivant les propriétés data-*.

  • cq:rewriteRenderCondition (booléen)
    Définissez cette propriété sur le nœud de remplacement (règle/remplacement) pour copier tout nœud enfant Condition de rendu Granite (rendercondition ou granite:rendercondition) depuis le nœud racine d’origine vers un enfant granite:rendercondition de la racine de copie.

Un nœud cq:rewriteProperties peut, en outre, être ajouté à un nœud de remplacement afin de définir des réécritures de chaînes pour les propriétés mappées dans le résultat. Le nœud est supprimé du remplacement. Les propriétés du nœud cq:rewriteProperties doivent porter le même nom que celles qu’elles réécrivent et accepter un tableau de chaînes doté de deux paramètres :

  • pattern : expression régulière avec laquelle la correspondance doit être établie ; par exemple, "(?:coral-Icon–)(.+)"
  • replacement : fourni à la fonction replaceAll de l’outil de correspondance ; par exemple, "$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

Vous pouvez copier /libs/cq/dialogconversion/rules dans /apps, puis modifier les règles existantes et/ou en ajouter de nouvelles à cette nouvelle 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();

La méthode matches doit renvoyer la valeur true si la règle correspond à la sous-arborescence dont la racine est située au niveau du nœud racine fourni. En cas de correspondance de la règle, l’algorithme de réécriture de l’arborescence appelle ensuite la méthode applyTo, laquelle doit réécrire la sous-arborescence dont la racine est située au niveau du nœud racine spécifié. 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. Pour de plus amples informations à ce sujet, consultez le Javadoc de l’interface com.adobe.cq.dialogconversion.DialogRewriteRule.

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

La classe suivante affiche un exemple d’une règle de réécriture personnalisée qui met en œuvre l’interface 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() {
        // ...
    }

}

Vous pouvez également étendre com.adobe.cq.dialogconversion.AbstractDialogRewriteRule comme indiqué ci-dessous. La classe abstraite met en œuvre la méthode getRanking et utilise la propriété OSGi service.ranking du service pour déterminer le classement de la règle.

@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

Le module cq-dialog-conversion-content contient plusieurs règles de réécriture prédéfinies. Pour plus d’informations sur les widgets de l’interface utilisateur classique, voir Utilisation de xtypes.

Règle Composant hérité Remplacement IU Granite/Coral 3
com.adobe.cq.dialogconversion.rules.CqDialogRewriteRule Le nœud de type cq:Dialog gère différentes sous-structures

granite/ui/components/foundation/container utilisant une disposition fixedcolumns ou tabs

Les composants réels de la boîte de dialogue sont copiés et réécrits lors des exécutions ultérieures de l’algorithme.

com.adobe.cq.dialogconversion.rules.IncludeRule xtype = cqinclude Le nœud référencé est copié dans la boîte de dialogue IU Granite/Coral 3 et (éventuellement) réécrit ensuite par l’algorithme.
com.adobe.cq.dialogconversion.rules.MultifieldRewriteRule xtype = multifield

granite/ui/components/coral/foundation/form/multifield

Le nœud enfant fieldConfig (le cas échéant) est réécrit séparément, ce qui ne limite donc 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.

Ce produit est distribué sous licence Creative Commons Attribution - Pas d’utilisation commerciale - Partage à l’identique 3.0 non transposé  Les publications Twitter™ et Facebook ne sont pas couvertes par les dispositions Creative Commons.

Mentions légales   |   Politique de confidentialité en ligne