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:
-
editor_toolbar: Webeditor toolbar consisting of file and content actions.
-
editor_tab_bar: Tabbed view of open files within webeditor, has actions you can perform on opened files.
-
file_mode_switcher: It helps switching between different available modes (author, source, preview) for the opened files within webeditor.
-
map_console_navigation_bar: It is the information bar for map opened in map console. It allows changing map and provides access to settings.
-
map_console_action_bar: This is the action bar for map console items such as Output Preset, Baseline, Translation, and Reports which provides relevant information along with their respective action buttons.
-
home_navigation_bar: Header bar of Guides home page where welcome message is displayed along with selected folder profile.
General Structure of each JSON
Each JSON follows a consistent structure:
-
id: Specifies the widget where the component is being customized.
-
targetEditor: Defines when to display or hide a button using editor and mode properties:
Currently we have these editor and mode in our system.
editor: ditamap, bookmap, subjectScheme, xml, css, translation, preset, pdf_preset
mode: author, source, preview, toc, split
(Note: toc mode applies to layout view.)
-
target: Specifies where the new component will be added. This uses key-value pairs or indexes for unique identification. View states include:
-
append: Add at the end.
-
prepend: Add at the beginning.
-
replace: Replace an existing component.
-
Example JSON Structure:
{
"id" : "editor_toolbar",
"view": {
"items": [
{
...,
"targetEditor": {
"mode": [
"preview"
],
"editor": [
"xml"
]
},
"target": {
"key": "label",
"value": "Table",
"viewState": "prepend"
},
...
},
]
}
}
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"
}
}
]
}
}
How to upload customized JSONs
-
On XML Editor configuration tab click on Edit in the topbar.
-
Now in XML Editor UI configuration sub-section you will be able to see a upload button.
-
You can click and upload the modified json. (The json to be uploaded should have same name as the id of widget being customized)
-
Once uploaded, hit Save in topbar.
For each uploaded file you can also delete the json to remove its customizarion from the UI or download to view or modify it again.
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"
}
}
-
On XML Editor configuration tab click on Edit in the topbar.
-
Now in XML Editor page layout sub-section you will be able to see a upload button.
-
You can click and upload the modified css. (Only css files are supported)
-
Once uploaded, hit Save in topbar.
For each uploaded file you can also delete the css to remove its customizarion from the UI or download to view or modify it again.
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
-
From the Navigation screen, click the Tools icon.
-
Select Guides on the left panel.
-
Click the Folder Profiles tile.
-
Select a Folder Profile.
-
Click the XML Editor Configuration tab.
-
You can click on the Convert UI config to JSON button. This will generate the editor_toolbar and map_console_action_bar json which contains the changes done in ui_config.
-
You can checkout the sample generated jsons for Editor toolbar and Map console action bar