Define a Custom Document Editor Layout

Overview

This page explains how to define a custom layout for document types in the document editor. Custom layouts allow you to control how fields are arranged and presented to authors when editing documents.

When to Use

Use a custom document editor layout when the default layouts do not meet your requirements for field arrangement or visual structure. Custom layouts are selectable when creating new document types.

Background

In the Document Type Editor, you can create and modify document types. Each document type defines:

The fields, their types, and their order
The layout used to present those fields in the document editor

When you create a new document type, you select a layout. The default options include '2 Column', '2 Column mirrored'* , '3 Column'*, '1 Column', and 'Horizontal List'.

This page describes how to add a custom layout to the available options.

* The '2 Column mirrored' and '3 Column' layouts are available starting in brXM 13.2.0.

Example: Custom Three Column Layout

This example demonstrates how to create a 'Custom 3 Column' layout. After implementation, this layout will be available when creating a new document type:

New document type dialog with Custom 3 Column layout highlighted

Note: The 'Custom 3 Column' layout is functionally identical to the default '3 Column' layout introduced in version 13.2.0. This example demonstrates the process for adding a custom layout. You can modify the column widths or structure as needed.

Prerequisites

Access to the cms module in your project
Ability to rebuild and restart your Bloomreach Content project

Implementation Steps

1. Create the Layout Index File

Add a layout index file in the cms module. Name the layout as required, for example: example.CustomThreeColumn.

File: cms/src/main/resources/hippoecm-layouts.xml

<?xml version="1.0" encoding="UTF-8"?>
<layouts>
  <layout>
    <plugin>example.CustomThreeColumn</plugin>
  </layout>
</layouts>

2. Define the Layout Descriptor

Create a layout descriptor in the example package within the CMS resources.

File: cms/src/main/resources/example/CustomThreeColumn.layout.xml

<?xml version="1.0" encoding="UTF-8"?>
<layout>
  <pad name="left" orientation="vertical" />
  <pad name="middle" orientation="vertical" />
  <pad name="right" orientation="vertical" />
  <transition name="left-middle right" source="left" target="middle" />
  <transition name="middle-left left" source="middle" target="left" />
  <transition name="middle-right right" source="middle" target="right" />
  <transition name="right-middle left" source="right" target="middle" />
</layout>

The <pad> elements define three areas (left, middle, right) where fields can be placed.
The <transition> elements specify how fields can be moved between pads. Each transition must have a unique name. The transition names are also used as CSS classes for the icons that trigger the transitions. Including 'left', 'right', 'up', or 'down' in the name ensures the correct arrow icon is displayed.

3. Add the Layout Markup

Place the layout markup file next to the descriptor.

File: cms/src/main/resources/example/CustomThreeColumn.html

<html xmlns:wicket="http://wicket.apache.org/">
<wicket:head>
  <link rel="stylesheet" type="text/css" href="skin/CustomThreeColumn.css" />
</wicket:head>
<wicket:panel>
  <div class="column-wrapper">
    <div class="col40" wicket:id="extension.left">left column</div>
    <div class="col40" wicket:id="extension.middle">middle column</div>
    <div class="col20" wicket:id="extension.right">right column</div>
  </div>
</wicket:panel>
</html>

This markup references a CSS file that defines the column layout.

Create the CSS file in the skin directory:

File: cms/src/main/resources/skin/CustomThreeColumn.css

.hippo-editor .col20 {
  padding-left: 0;
}

Place the CSS file in the skin folder. Files in this folder are served by the SkinResourceServlet defined in the CMS web.xml file, which allows you to reference the CSS from your HTML markup.

4. Add a Layout Icon and Display Name

Provide an icon for the layout:

File: cms/src/main/resources/example/CustomThreeColumn.png

[![Three-column layout icon with three vertical panels](https://xmdocumentation.bloomreach.com/binaries/original/content/gallery/connect/library/concepts/document-types/10.0/threecolumn.png)](/binaries/content/gallery/connect/library/concepts/document-types/10.0/threecolumn.png)

Add a resource bundle to define the display name for the layout:

File: cms/src/main/resources/example/CustomThreeColumn.properties

CustomThreeColumn=Custom 3 Column

5. Use the New Layout

Rebuild and restart your project. Log in as admin, navigate to Content > Document Types, and create a new document type. The dialog will now include the "Custom 3 Column" layout as an option. Select it to use your custom layout.

Verification

After restarting, verify that the "Custom 3 Column" layout appears in the document type creation dialog and that it arranges fields in three columns as defined.