OpenWGA 7.0 - OpenWGA Concepts and Features

The main process in creating a customizable design is to divide up all design resources into base resources, which should not be customizable and overlay resources which should be, and then glueing both together to a working design.

You make a resource an overlay resource simply by creating an "overlay" directory at one of the places mentioned above and placing your resource in there or into a subfolder of it.

Imagine the following minimal design directory with the following WebTML modules:

The file "outer_standard.tml" is a base resource while the file "layout.tml" is an overlay resource. It may be used to define a general layout of the application which the customizing user may want to modify. When using this design with an overlay directory OpenWGA will copy the module to this location inside this overlay directory:

Now in most situations you will need to refer overlay resources from your base resources. For example "outer_standard.tml" needs to include "overlay/layout.tml".  You do this straight forwardly just by specifying its "real" design name:

In the case of a customized design this will automatically fetch the resource from the overlay directory. If your design is customizable, but your user chose to not customize it (possible with OverlaySupport="optional"), then OpenWGA will directly fetch it from your base design, as usual.

Now that is one part of the trick. The real question is: How to reference other resources from your overlay resource. Remember, you are now in a module which will behave like it was in a separate design directory. There it is a module directly at root of "/tml/html".

One possible situation would be if you wanted to include another WebTML module inside the "overlay" folder from your "layout.tml". For example:

Both, "header.tml" and "layout.tml" are "root modules" from the perspective of an overlay directory. So you could just reference the header like that from "layout.tml":

You of course also could use a local reference, which actually would also work if "overlay" was a normal subdirectory:

But that would be misleading here.

This not only occurs to WebTML modules. Imagine a TMLScript module "/scripts/tmlscript/overlay/createpage.tmlscript". You could call this as action just like it was in root of your "virtual" overlay directory:

The same applies when addressing other types of script modules, like JavaScript, or file containers.

The behaviour is straight-forward if the addressed resource is in some subfolder of "overlay". You could build an URL to a JavaScript module under "/scripts/js/homepage/rtf.js" like this:

So basically you are just leaving out the "overlay" prefix directory in any case.

A special word about WebTML labels in overlays: This works the same as with all other resources. Using a WebTML label inside an overlay resource will automatically use labels defined in your overlay directory. These however then must be in file container folders "files/overlay/labels_en", "files/overlay/labels_de" and the such. You may instead want to keep your labels non-customizable in the base design. More on how to use that in the next chapter.

The case is a bit different if you want to include resources of your base design (outside the "overlay" folders) from an overlay resource. As overlay resources behave like they were in a separate design directory there is no straight-forward way to "go back" to the base design just by specifying a design name.

Imagine we have the following WebTML modules that form parts of the layout to be customized:

The overlay resource "layout.tml" should include these, so the user can customize their positions, but they themselves should not be customizable.

The trick to address those from the overlay is to use their normal design name but append the suffix "@base" to the design name:

And that's about all. You can use this suffix everywhere a design resource is addressed to denote, you want back into your base design. 

In your included base design resource now everything works again as expected. You may as well include back into your overlay resources there using the same methodology already learned.

Again some special word about WebTML labels: If you want to reference WebTML labels from your base design in your overlay design (or in other words: Your designs should be customizable, your labels should not), then you again here must append "@base" to the design resource: The label container "labels" in that case:

But as it is rather uncommon to specify the label container when using labels - since "labels" is the default and something different is seldomly used - you can also use the "@base" suffix on the label key here as a special comfort function:

The effect will be the same. This also applies to all other label-fetching functionalities.