Ein Layout-Overlay erlaubt es einer Anwendung, ein Layout zu verändern, das von einem TopLogic-Modul ausgeliefert wird, ohne die betroffene Layout-Datei zu kopieren. Die Anpassung bleibt dadurch von der Weiterentwicklung des Originals getrennt: Ändert sich das Layout im Modul, greift die eigene Anpassung weiterhin. Typische Anwendungsfälle sind das Ergänzen eines Tabs in der Administration und das Hinzufügen einer Funktion zu einer bestehenden Administrationssicht.

Ein Overlay ist eine inkrementelle Konfiguration: Die Datei beschreibt nur die Unterschiede zum Original, also geänderte Attribute und zusätzliche Einträge in Listen. Alles, was nicht erwähnt wird, bleibt unverändert.

Ablage und Dateiname

Ein Overlay wird ausschließlich über seinen Dateinamen dem Ziel-Layout zugeordnet: Der Pfad des Overlays relativ zu WEB-INF/layouts muss dem Pfad des Ziel-Layouts entsprechen, wobei die Endung .layout.xml durch .layout.overlay.xml ersetzt wird. Im Inhalt der Datei steht keine Referenz auf das Ziel. Der Pfad ist dabei Groß-/Kleinschreibung-sensitiv.

Um beispielsweise das Layout com.top_logic.contact/admin/personContacts/personContactView.layout.xml aus dem Modul Contact anzupassen, legt die Anwendung die Datei WEB-INF/layouts/com.top_logic.contact/admin/personContacts/personContactView.layout.overlay.xml an. Das Overlay liegt also im Verzeichnisbaum der eigenen Anwendung, spiegelt darin aber den Pfad des fremden Layouts.

Argument-Overlay

Ist das Ziel-Layout ein Aufruf eines Layout-Templates (Root-Tag config:template-call), so kann das Overlay die Argumente dieses Template-Aufrufs verändern. Ein solches Overlay hat das Root-Tag arguments und wird mit dem arguments-Abschnitt des Ziel-Layouts verschmolzen.

Das Layout admin/studio/index.layout.xml definiert die Tabs der Entwickleroptionen als Argument components seines Template-Aufrufs. Ein Overlay kann dieser Liste einen weiteren Tab hinzufügen:

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

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

Ein layout-reference verweist auf ein eigenes Layout, das dadurch als zusätzlicher Tab erscheint. Attribute, die im Overlay angegeben werden, überschreiben das entsprechende Argument des Template-Aufrufs.

Komponenten-Overlay

Ein Komponenten-Overlay verändert einzelne Komponenten des Ziel-Layouts. Es hat das Root-Tag components und enthält darunter je Komponente einen Eintrag, der die Komponente über ihr Attribut name adressiert. Die Adressierung erfolgt allein über diesen Namen: Es ist unerheblich, wie tief die Komponente im Layout verschachtelt ist und über welche Include- oder Template-Aufrufe sie in das Layout gelangt ist. Diese Form ist auch dann nutzbar, wenn das Ziel-Layout kein Template-Aufruf ist.

Das folgende Overlay ergänzt die Sicht auf die Personenkontakte um einen Import-Dialog. Adressiert wird die Komponente personContactEdit, die im Ziel-Layout nicht direkt, sondern über ein Include enthalten ist:

<?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>

Eine bestehende Komponente kann ein Komponenten-Overlay auch entfernen, indem es den Eintrag mit config:operation="remove" markiert. Was es nicht kann, ist eine neue Komponente auf oberster Ebene ergänzen: Enthält das Overlay einen Namen, der im Ziel-Layout nicht vorkommt, wird die Konfiguration mit dem Fehler "Unable to add components ... Don't know where to set it." abgewiesen. Eine zusätzliche Komponente wird stattdessen immer innerhalb einer bereits vorhandenen Komponente angelegt, wie im Beispiel oben im Abschnitt dialogs.

Positionierung in Listen

Einträge, die ein Overlay zu einer Liste beiträgt, werden standardmäßig am Ende angefügt. Über das Attribut config:position aus dem Namensraum http://www.top-logic.com/ns/config/6.0 kann die Position gesteuert werden. Möglich sind begin, end, before und after; bei before und after benennt config:reference den Eintrag, relativ zu dem eingefügt wird. Damit erscheint der neue Tab an einer definierten Stelle statt hinten:

<?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>

Mehrere Overlays zum selben Layout

Zu einem Layout-Key können mehrere Module gleichzeitig ein Overlay beitragen. Alle diese Overlays werden angewendet, und zwar von der unspezifischsten zur spezifischsten Quelle. Die Anwendung selbst kommt damit zuletzt und kann die Angaben der Module überschreiben.

Zu beachten ist dabei eine Einschränkung: Argument-Overlays können nur angewendet werden, solange noch kein Komponenten-Overlay angewendet wurde. Trägt ein unspezifischeres Modul ein Komponenten-Overlay bei und ein spezifischeres ein Argument-Overlay, so wird letzteres wirkungslos verworfen und im Log mit "Argument overlay ... could not be applied after a component overlay." vermerkt. In diesem Fall ist auch die spezifischere Anpassung als Komponenten-Overlay zu formulieren.