A layout overlay allows an application to modify a layout that is delivered by a TopLogic module, without copying the layout file in question. This keeps the customization separate from the further development of the original: if the layout changes within the module, the customization still applies. Typical use cases are adding a tab to the administration and adding a function to an existing administration view.

An overlay is an incremental configuration: the file only describes the differences from the original, i.e. changed attributes and additional entries in lists. Everything that is not mentioned remains unchanged.

Location and file name

An overlay is assigned to its target layout solely by its file name: the path of the overlay relative to WEB-INF/layouts must match the path of the target layout, with the suffix .layout.xml replaced by .layout.overlay.xml. The content of the file does not contain any reference to the target. Note that the path is case-sensitive.

To customize the layout com.top_logic.contact/admin/personContacts/personContactView.layout.xml from the Contact module, for example, the application creates the file WEB-INF/layouts/com.top_logic.contact/admin/personContacts/personContactView.layout.overlay.xml. The overlay therefore resides in the directory tree of the application itself, but mirrors the path of the foreign layout within it.

Argument overlay

If the target layout is a call of a layout template (root tag config:template-call), the overlay can modify the arguments of that template call. Such an overlay has the root tag arguments and is merged with the arguments section of the target layout.

The layout admin/studio/index.layout.xml defines the tabs of the developer options as the argument components of its template call. An overlay can add another tab to this list:

<?xml version="1.0" encoding="utf-8" ?>

<arguments>
  <components>
    <layout-reference resource="myapp/admin/myAdminTab.layout.xml"/>
  </components>
</arguments>

A layout-reference points to a layout of your own, which thereby appears as an additional tab. Attributes given in the overlay override the corresponding argument of the template call.

Component overlay

A component overlay modifies individual components of the target layout. It has the root tag components and contains one entry per component below it, addressing the component by its name attribute. Addressing works by this name alone: it does not matter how deeply the component is nested within the layout, nor through which include or template calls it got there. This form can also be used when the target layout is not a template call.

The following overlay adds an import dialog to the view of the person contacts. It addresses the component personContactEdit, which the target layout does not contain directly but through an include:

<?xml version="1.0" encoding="utf-8" ?>

<components>
  <component name="personContactEdit">
    <dialogs>
      <include name="commons/dispatchingImportEVA_dialog.xml"
        importerNames="personExcel, personCSV"
        masterComponent="personContactFilterTable"
        namePrefix="MyPersonImport"
        securityObject="securityRoot"
      />
    </dialogs>
  </component>
</components>

A component overlay can also remove an existing component by marking its entry with config:operation="remove". What it cannot do is add a new component at the top level: if the overlay contains a name that does not occur in the target layout, the configuration is rejected with the error "Unable to add components ... Don't know where to set it." An additional component is therefore always created inside a component that already exists, as in the dialogs section of the example above.

Positioning within lists

Entries that an overlay contributes to a list are appended at the end by default. The position can be controlled through the attribute config:position from the namespace http://www.top-logic.com/ns/config/6.0. The possible values are begin, end, before and after; for before and after, config:reference names the entry relative to which the insertion happens. This makes the new tab appear at a defined place instead of at the end:

<?xml version="1.0" encoding="utf-8" ?>

<arguments xmlns:config="http://www.top-logic.com/ns/config/6.0">
  <components>
    <layout-reference
      config:position="begin"
      resource="myapp/admin/myAdminTab.layout.xml"
    />
  </components>
</arguments>

Several overlays for the same layout

Multiple modules can contribute an overlay for the same layout key at the same time. All of these overlays are applied, from the least specific to the most specific source. The application itself therefore comes last and can override what the modules specify.

One restriction has to be observed here: argument overlays can only be applied as long as no component overlay has been applied yet. If a less specific module contributes a component overlay and a more specific one contributes an argument overlay, the latter is discarded without effect and noted in the log as "Argument overlay ... could not be applied after a component overlay." In this case the more specific customization has to be formulated as a component overlay as well.