Panoramica

Durante la migrazione dalla vecchia interfaccia utente alla nuova interfaccia utente di AEM Guides, gli aggiornamenti a ui_config devono essere convertiti in configurazioni dell'interfaccia utente più flessibili e modulari. Questo framework consente di adottare le modifiche direttamente nella editor_toolbar e in altre barre degli strumenti. Il processo supporta anche la modifica di altre viste e widget nell'applicazione.

Modifica di JSON per schermate diverse

I file JSON possono essere aggiunti alla sezione Configurazione dell’interfaccia utente dell’editor XML per diverse schermate e widget. Di seguito è riportato un elenco dei widget di largo utilizzo e dei relativi ID:

Struttura generale di ciascun JSON

Ogni JSON segue una struttura coerente:

Esempio di struttura JSON:

{
  "id" : "editor_toolbar",
  "view": {
    "items": [
      {
        ...,
        "targetEditor": {
          "mode": [
            "preview"
          ],
          "editor": [
            "xml"
          ]
        },
        "target": {
          "key": "label",
          "value": "Table",
          "viewState": "prepend"
        },
        ...
      },
    ]
  }
}

Informazioni sulle proprietà di targetEditor

Di seguito è riportato un raggruppamento di ogni proprietà, del suo scopo e dei valori supportati.

mode

Definisce la modalità operativa dell’editor.

Valori supportati: author, source, preview, layout (in precedenza toc), split

displayMode (facoltativo)

Controlla la visibilità o l’interattività dei componenti dell’interfaccia utente. Il valore predefinito è impostato su show se non specificato.

Valori supportati: show, hide, enabled, disabled

Esempio:

 {
        "icon": "textBulleted",
        "title": "Custom Insert Bulleted",
        "on-click": "$$AUTHOR_INSERT_REMOVE_BULLETED_LIST",
        "key": "$$AUTHOR_INSERT_REMOVE_BULLETED_LIST",
        "targetEditor": {
          "documentType": [
            "ditamap"
          ],
          "mode": [
            "author"
          ],
          "displayMode": "hide"
        }
      },

editor

Specifica il tipo di documento principale nell'editor.

Valori supportati: ditamap, bookmap, subjectScheme, xml, css, translation, preset, pdf_preset

documentType

Indica il tipo di documento principale.

Valori supportati: dita, ditamap, bookmap, subjectScheme, css, preset, ditaval, reports, baseline, translation, html, markdown, conditionPresets

Valori aggiuntivi possono essere supportati per casi d’uso specifici.

Esempio:

 {
        "icon": "textNumbered",
        "title": "Custom Numbered List",
        "on-click": "$$AUTHOR_INSERT_REMOVE_NUMBERED_LIST",
        "key": "$$AUTHOR_INSERT_REMOVE_NUMBERED_LIST",
        "targetEditor": {
          "documentType": [
            "dita",
            "ditamap"
          ],
          "mode": [
            "author",
            "source"
          ]

        }
      },

documentSubType

Classifica ulteriormente il documento in base a documentType.

Valori aggiuntivi possono essere supportati per casi d’uso specifici.

Esempio:

 {
        "icon": "rename",
        "title": "Custom Rename",
        "on-click": "$$PUBLISH_PRESETS_RENAME",
        "label": "Custom Rename",
        "key": "$$PUBLISH_PRESETS_RENAME",
        "targetEditor": {
          "documentType": [
            "preset"
          ],
          "documentSubType": [
            "nativePDF",
            "aemsite",
            "json"
          ]

        }
      },

flag

Indicatori booleani per lo stato del documento o le funzionalità.

Valori supportati: isOutputGenerated, isTemporaryFileDownloadable, isPDFDownloadable, isLocked, isUnlocked, isDocumentOpen

È inoltre possibile creare un contrassegno personalizzato all'interno di extensionMap utilizzato come contrassegno in targetEditor. extensionMap è una variabile globale utilizzata per aggiungere chiavi personalizzate o valori osservabili.

Esempio:

 {
        "icon": "filePDF",
        "title": "Custom Export pdf",
        "on-click": "$$DOWNLOAD_TOPIC_PDF",
        "key": "$$DOWNLOAD_TOPIC_PDF",
        "targetEditor": {
          "documentType": [
            "markdown"
          ],
          "mode": [
            "preview"
          ],
          "flag": ["isPDFDownloadable"]

        }
      },

Esempi

Di seguito è riportato un esempio di come aggiungere, eliminare o sostituire un pulsante nella barra degli strumenti dell’editor.

Aggiunta di un pulsante

Aggiunta di un nuovo pulsante Inserisci tabella personalizzata in editor_toolbar per aggiungere una tabella semplice visibile solo in modalità anteprima.

{
  "id": "editor_toolbar",
  "view": {
    "items": [
      {
        "icon": "table",
        "title": "Insert Custom Table",
        "on-click": {
          "name": "$$AUTHOR_INSERT_ELEMENT",
          "args": [
            "simpletable",
            "table",
            "choicetable"
          ]
        },
        "key": "$$AUTHOR_INSERT_ELEMENT",
        "targetEditor": {
          "mode": [
            "preview"
          ],
        },
        "target": {
          "key": "label",
          "value": "Table",
          "viewState": "prepend"
        }
      }
    ]
  }
}

Eliminazione di un pulsante

Eliminazione di un pulsante dalla barra degli strumenti. Rimuove il pulsante Aggiungi immagine dalla barra degli strumenti dell’editor.

{
  "id": "editor_toolbar",
  "view": {
    "items": [
      {
        "hide": true,
        "target": {
          "key": "label",
          "value": "Image",
          "viewState": "replace"
        }
      }
    ]
  }
}

Sostituzione di un pulsante

Sostituzione del pulsante Multimedia nella barra degli strumenti con il pulsante di inserimento del collegamento YouTube visibile solo in modalità di creazione.

{
  "id": "editor_toolbar",
  "view": {
    "items": [
      {
        "icon": "s2youtube",
        "title": "Youtube",
        "on-click": {
          "name": "$$AUTHOR_INSERT_ELEMENT",
          "args": "<object data='http://youtube.com'></object>"
        },
        "targetEditor": {
          "mode": [
            "author"
          ]
        },
        "target": {
          "key": "elementId",
          "value": "toolbar-multimedia",
          "viewState": "replace"
        }
      }
    ]
  }
}

Aggiunta di un pulsante in modalità anteprima

In base alla progettazione, la visibilità dei pulsanti viene gestita separatamente per le modalità bloccate e sbloccate (sola lettura) per garantire un'esperienza utente chiara e controllata. Per impostazione predefinita, qualsiasi pulsante appena aggiunto è nascosto quando l’interfaccia è in modalità di sola lettura.
Per rendere visibile un pulsante in modalità sola lettura, è necessario specificare una destinazione che lo collochi in una sottosezione della barra degli strumenti che rimanga accessibile anche quando l'interfaccia è bloccata.
Ad esempio, specificando la destinazione come Scarica come PDF, puoi verificare che il pulsante venga visualizzato nella stessa sezione di un pulsante visibile esistente, rendendolo accessibile in modalità sbloccata.

"target": {
  "key": "label",
  "value": "Download as PDF",
  "viewState": "prepend"
}

Aggiunta di un pulsante Esporta come PDF in modalità Anteprima che sarà visibile sia in modalità blocco che in modalità sblocco.

{
  "id": "editor_toolbar",
  "view": {
    "items": [
      {
        "icon": "filePDF",
        "title": "Export as PDF",
        "on-click": "$$DOWNLOAD_TOPIC_PDF",
        "key": "$$DOWNLOAD_TOPIC_PDF",
        "targetEditor": {
          "editor": [
            "ditamap",
            "xml"
          ],
          "mode": [
            "preview"
          ]
        },
        "target": {
          "key": "label",
          "value": "Download as PDF",
          "viewState": "prepend"
        }
      },
      {
        "icon": "filePDF",
        "title": "Export as PDF",
        "on-click": "$$DOWNLOAD_TOPIC_PDF",
        "key": "$$DOWNLOAD_TOPIC_PDF",
        "targetEditor": {
          "editor": [
            "ditamap",
            "xml"
          ],
          "mode": [
            "preview"
          ]
        }
      }
    ]
  }
}

Lo snippet seguente mostra il pulsante Esporta come PDF con uno scenario di blocco.

Inoltre, il pulsante Esporta come PDF con lo scenario di sblocco è visibile nello snippet seguente.

Personalizzare le opzioni visualizzate nel menu a discesa della barra degli strumenti dell’editor

Puoi aggiungere, nascondere, sostituire e aggiungere opzioni personalizzate nel menu a discesa utilizzando gli esempi seguenti.

Aggiunta

Aggiunta di un’opzione nel menu a discesa Menu. Qui aggiungiamo Pulsante Menu personalizzato nelle opzioni Menu

{
        "icon": "specialCharacter",
        "title": "Custom menu button",
        "on-click": "$$AUTHOR_INSERT_SYMBOL",
        "targetEditor": {
          "editor": [
            "ditamap"
          ],
          "mode": [
            "author"
          ]
        },
        "target": {
          "key": "label",
          "value": "Version label",
          "viewState": "append"
        }
      }

Sostituzione

Sostituzione di un'opzione visualizzata nel menu a discesa Menu. Stiamo sostituendo Crea attività di revisione con Pulsante del menu personalizzato 3.

{
        "icon": "specialCharacter",
        "title": "Custom menu button 3",
        "on-click": "$$AUTHOR_INSERT_SYMBOL",
        "target": {
          "key": "label",
          "value": "Create review task",
          "viewState": "replace"
        }

      }

Nascondi

Nasconde un’opzione visualizzata nel menu a discesa Menu. Stiamo nascondendo l'opzione Trova e sostituisci dal menu.

{
        "hide": true,
        "target": {
          "key": "label",
          "value": "Find and replace",
          "viewState": "replace"
        }
      }

Aggiunta di un’opzione personalizzata nel sottomenu

Aggiunta di un'opzione nel sottomenu nel menu a discesa Menu.

{
        "icon": "viewAllTags",
        "title": "Toggle Tags View Goziamasu",
        "key": "AUTHOR_TOGGLE_TAG_VIEW",
        "target": {
          "key": "label",
          "value": "Track changes",
          "viewState": "replace"
        },
        "targetEditor": {
          "documentType": [
            "dita"
          ],
          "mode": [
            "author"
          ]
        }

      }

Come caricare JSON personalizzati

Come caricare file CSS personalizzati

Puoi anche aggiungere CSS per personalizzare l’aspetto dei pulsanti aggiunti personalizzati o dei widget o pulsanti già esistenti nell’interfaccia utente.

Per un pulsante personalizzato appena aggiunto, aggiungi extraclass al pulsante o al componente personalizzato nel JSON.
Per una vecchia classe, puoi ispezionare l’elemento e modificare anche le classi esistenti.

{
  "icon": "table",
  "title": "Insert Custom Table",
  "extraclass": "custom-css",
  "key": "$$AUTHOR_INSERT_ELEMENT",
  "targetEditor": {
    "mode": [
      "preview"
    ],
  },
  "target": {
    "key": "label",
    "value": "Table",
    "viewState": "prepend"
  }
}

Esempio di personalizzazione dei css dei pulsanti

In questo caso viene aggiunto un nuovo pulsante Inserisci tabella personalizzata in editor_toolbar per aggiungere una tabella semplice visibile solo in modalità anteprima e applicare un CSS personalizzato.
Questo CSS modifica lo sfondo del pulsante e la dimensione font del titolo.

#editor_toolbar {
  .custom-css {
    background-color: burlywood;
    font-size: 2rem;
  }
}

{
  "id": "editor_toolbar",
  "view": {
    "items": [
      {
        "icon": "table",
        "title": "Insert Custom Table",
        "extraclass": "custom-css",
        ...
      }
    ]
  }
}

Passaggi per convertire la configurazione UI in Json modulari