51黑料不打烊

Overview

When migrating from the old UI to the new AEM Guides UI, updates to ui_config must be converted to more flexible and modular UI configurations. This framework helps adopt changes seamlessly into the editor_toolbar and other toolbars. The process also supports modifying other views and widgets in the application.

Editing JSON for different screens

JSON files can be added to the XML Editor UI Configuration section for various screens and widgets. Below is a list of widely used widgets and their IDs:

General Structure of each JSON

Each JSON follows a consistent structure:

Example JSON Structure:

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

Understanding targetEditor properties

Below is a breakdown of each property, its purpose, and supported values.

mode

Defines the operational mode of the editor.

Supported values: author, source, preview, layout (previously toc), split

displayMode (optional)

Controls visibility or interactivity of UI components. The default value is set to show if not specified.

Supported values: show, hide, enabled, disabled

Example:

 {
        "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

Specifies the primary document type in the editor.

Supported values: ditamap, bookmap, subjectScheme, xml, css, translation, preset, pdf_preset

documentType

Indicates the primary document type.

Supported values: dita, ditamap, bookmap, subjectScheme, css, preset, ditaval, reports, baseline, translation, html, markdown, conditionPresets

Additional values may be supported for specific use cases.

Example:

 {
        "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

Further classifies the document based on documentType.

Additional values may be supported for specific use cases.

Example:

 {
        "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

Boolean indicators for document state or capabilities.

Supported values: isOutputGenerated, isTemporaryFileDownloadable, isPDFDownloadable, isLocked, isUnlocked, isDocumentOpen

Additionally, you can also create a custom flag inside extensionMap which is utilized as a flag in targetEditor. Here, extensionMap is a global variable used to add custom keys or observable values.

Example:

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

        }
      },

Examples

Below is an example of how to add, delete or replace a button in the editor toolbar.

Adding a Button

Adding a new button Insert Custom Table in editor_toolbar to add a simple table which is visible only in preview mode.

{
  "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"
        }
      }
    ]
  }
}

Deleting a Button

Deleting a button from the toolbar. Here we remove the adding Image button from the editor toolbar.

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

Replacing a Button

Replacing the Multimedia button from the toolbar with Youtube link insertion button which is only visible in author mode.

{
  "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"
        }
      }
    ]
  }
}

Adding a button in preview mode

In accordance with the design, the button visibility is managed separately for locked and unlocked (read-only) modes to maintain a clear and controlled user experience. By default, any newly added button is hidden when the interface is in read-only mode.
To make a button visible in read-only mode, you must specify a target that places it within a toolbar subsection that remains accessible even when the interface is locked.
For example, by specifying the target as Download as PDF, you can ensure the button appears in the same section as an existing visible button, thereby making it accessible in unlocked mode.

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

Adding a button Export as PDF in Preview mode which will be visible both in lock and unlock mode.

{
  "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"
          ]
        }
      }
    ]
  }
}

The following snippet shows the Export as PDF button with lock scenario.

Also, the Export as PDF button with the unlock scenario can be seen in the snippet below.

How to upload customized JSONs

How to upload customized CSS

You can also add css to customize the look and feel of custom added buttons or already existing widgets or buttons on the UI.

For a newly added custom button add an extraclass to custom button or component inside the JSON.
For an old class, you can inspect element and modify the existing classes as well.

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

Example to customize button css

Here we add a new button Insert Custom Table in editor_toolbar to add a simple table which is visible only in preview mode and apply a custom css on it.
This css modifies the background of button and font size of its title.

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

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

Steps to convert ui config to modular Jsons