Customizing Page Authoring (Touch-Optimized UI)

AEM provides various mechanisms to enable you to customize the page authoring functionality (and the consoles) of your authoring instance (touch-optimized UI).

  • Clientlibs
    Clientlibs allow you to extend the default implementation to realise new functionality, while reusing the standard functions, objects and methods. When customizing, you can create your own clientlib under /apps; the new clientlib must:
    • depend on the authoring clientlib:
    • be part of the appropriate cq.authoring.editor.hook category;
      for example, where foo is the name of your module
  • Overlays
    Overlays are based on node definitions and allow you to overlay the standard functionality (in /libs) with your own customized functionality (in /apps). When creating an overlay a 1:1 copy of the original is not required, as the sling resource merger allows for inheritance.


  • Javascript Namespace:
  • ClientLib category hook: cq.authoring.editor.hook
  • Overlays are managed by: overlayManager
  • The Editables for the current page are in:
  • A lot of page data is in:

These can be used in many ways to extend the page authoring functionality in your AEM instance. A selection are covered below (at a high level).


For further information see:

This topic is also covered in the AEM Gems session - User interface customization for AEM 6.0.


You must not change anything in the /libs path.

This is because the content of /libs is overwritten the next time you upgrade your instance (and may well be overwritten when you apply either a hotfix or feature pack).

The recommended method for configuration and other changes is:

  1. Recreate the required item (i.e. as it exists in /libs) under /apps
  2. Make any changes within /apps

Add New Layer (Mode)

When you are editing a page, there are various modes available. These modes are implemented using layers. These allow access to differing types of functionality for the same page content; the standard layers are: edit, preview, annotate, developer, targeting.

Standard Layers

In a standard AEM installation:

  1. /libs/cq/gui/components/authoring/clientlibs/editor/js/layers/Layer.js

    This holds the base definition, all other layers inherit from this.

  2. /libs/cq/gui/components/authoring/clientlibs/editor/js/edit

    This is the definition for the edit layer. This the default layer. Your new layer should inherit from this.

    This folder contains the definitions for:

    • edit.js - edit definitions
    • edit.Layer.js - layer definitions
    • edit.actions.js - actions
    • edit.Overlay.js - layer overlay - defines the behavior/look-and-feel for the layer
                                          and therefore how you interact with the content
    • edit.Toolbar.js - toolbar

Creating a New Layer

To create a new layer definition (within your clientlib) you have to:

  1. Implement:

    • setUp
    • tearDown


    A layer must return the editor to the state it was before the layer was activated.

    It is very important that a layer must be responsible for cleaning what it introduced. This is done in the tearDown function.

  2. Register the layer (includes the constructor):

    • layerManager.registerLayer
  3. With the constructor you need to specify:

    • name
    • icon (iconClass)
    • overlay (overlayConstructor)
    • toolbar (toolbarConstructor)

Code Sample

aem-authoring-extension-layer-msm is a sample package showing how to create a new layer in page authoring. The example is using MSM data and highlights it in the layer. To try it you may use Geometrixx Outdoors or any other LiveCopy page.

Code on GitHub

You can find the code of this page on GitHub

Add New Selection Category to Asset Browser

The asset browser shows assets of various types/categories (e.g. image, documents, etc). The assets can also be filtered by these asset categories.

Standard Categories in the Asset Finder

In a standard AEM installation:

  1. /libs/cq/gui/components/authoring/clientlibs/assetfinder

    Holds definitions related to the asset finder.

  2. /libs/cq/gui/components/authoring/clientlibs/assetfinder/js

    Holds definitions for the asset categories collated and shown in the asset finder. The following are available in a standard installation:

    • document
    • image
    • video

Creating a New Asset Category

To create a new asset category to the asset finder (within your clientlib) you have to:

  1. Define the asset category:

    • loadAssets searches for appropriate assets based on mimeType (asset type)
  2. Define the handling required for actions such as drag/drop, copy/paste, etc.

Code Sample

aem-authoring-extension-assetfinder-flickr is a sample package showing how to add a new group to the asset finder. This example connects to Flickr's public stream and shows them in the sidepanel.

Code on GitHub

You can find the code of this page on GitHub

Add New Action to a Component Toolbar

Each component (usually) has a toolbar that provides access to a range of actions that can be taken on that component.

Standard Actions in a Component Toolbar

In a standard AEM installation:

  1. An action is registered with the call to:

    • editableToolbar.registerAction

    For example, as in:


Creating a New Action

To create a new action:

  1. You need to define the characteristics of the new button that will appear in the component's toolbar:

    • icon
    • text
    • condition (e.g. for toggled buttons)
    • handler

Code Sample

aem-authoring-extension-toolbar-screenshot is a sample package showing how to create a custom toolbar action to render components.

Code on GitHub

You can find the code of this page on GitHub

Add New Inplace Editor

Standard Inplace Editor

In a standard AEM installation:

  1. /libs/cq/gui/components/authoring/clientlibs/editor/js/editors

    Holds definitions of the various editors available.

  2. There is a connection between the editor and each resource type (as in component) that can use it:

    • cq:inplaceEditing
      for example, /libs/foundation/components/text/cq:editConfig
      • property: editorType
        Defines the type of inline editor that will be used when the inplace editing is triggered for that component; e.g. text, textimage, image, title.

Creating a New Inplace Editor

To implement a new inplace editor (within your clientlib):


For example, see:

  1. Implement:

    • setUp
    • tearDown
  2. Register the editor (includes the constructor):

    • editor.register
  3. Provide the connection between the editor and every resource type (as in component) that can use it.

Add a New Page Action

To add a new page action to the page toolbar, for example a Back to Sites (console) action:

  1. To achieve this you need:

    • extend the cq.authoring.editor.hook clientlib to define the functionality:
    • a header action as the means for the user to access that functionality:

Code Sample

aem-authoring-extension-header-backtosites is a sample package showing how to create a custom header bar action to jump back to the Sites console.

Code on GitHub

You can find the code of this page on GitHub