OpenWGA 7.5 - OpenWGA Concepts and Features
Design and development » WebTML » Basic conceptsDesign References
When a design resource like a file container, a WebTML module or a script module gets addressed in WebTML and TMLScript then design references are used to address them. Examples where design references are used are attribute ref on <tml:include>, attribute doc on <tml:url> or the argument "actionID" on WGA.callAction() in TMLScript.
The general syntax of design references is:
[dbkey/] design-name
Each design reference may optionally take a database key prefix, divided by a slash "/". This takes precedence over other individual functionalities to determine the target application, like "db" attributes.
The design name given is the internal name of the resource. This is not directly the file path where the container or module is stored. The reason for this is that the design actually may come from different types of design sources, like design directories, plugins or even from documents in the OpenWGA content store. So the design name needs some "intermediate" form that matches all possible sources. Its syntax is:
[[...folder:]folder:]localname
The design name is built from local name plus optional parent folders. Design names use colons ":" as folder dividers instead of slashes.
As a WebTML designer it is essential for your to find out how you find out the design name for a given design directory file. This is done by the following rules:
- The local name is simply the file name without any file suffix
- The folders for your design name are the folders where your file is contained, but only those below their mandatory base folders. These are folder "files" for file containers, "tml/<mediakey>" for WebTML modules and "scripts/<scripttype>" for script modules. A file directly located directly inside those folders will have no folder in its design name.
- Remember: For file containers the directory is actually the resource addressed by design references, not the files themselves. So you take the name of the directory (whose files you want to access) to build the design name.
For example, some file resources and their respective internal design name:
Resource file | Design name |
/tml/html/outer_standard.tml | outer_standard |
/tml/html/settings/standard.tml | settings:standard |
/files/images | images |
/files/overlay/resources/zip | overlay:resources:zip |
/scripts/js/basic.js | basic |
/scripts/tmlscript/actions/homepage/createcomment.tmlscript | actions:homepage:createcomment |
Local references
Local references are a way to address design resources that are stored in the same folder as the calling resource.
Design resources in OpenWGA can be organized in subfolders. It is good programming practice to store design resources that belong to the same functionality in the same folder. For example: The WebTML module "projects:portlet" may have accompanying modules which define its code for different portlet modes like "view", "new" and "edit". These may get stored under "projects:mode-view", "projects:mode-new" and "projects:mode-edit".
Local references are an easy and safe way to address these other design resources that belong to the same functionality without specifying the folder.
A local reference starts with a double colon "::". This double colon represents the folder that the current design resource is contained in. After the double colon the name of the addressed design may be specified. So specifying the following include inside WebTML module "projects:portlet":
<tml:include ref="::mode-view"/>
Would indeed perform the following:
<tml:include ref="projects:mode-view"/>
This also works across different resource types, even if they are stored under differing base folders. So creating the following action link inside WebTML module "projects:portlet":
<tml:button clickaction="::createproject">Create project</tml:button>
Would indeed equal the following:
<tml:button clickaction="projects:createproject">Create project</tml:button>
This calls the code of TMLScript module "projects:createproject", even though the WebTML module may be stored in file "/tml/html/projects/portlet.tml" while the script module resides under "/scripts/tmlscript/projects/createproject.tmlscript". So the "projects" folders are not actually the same, but the structure below the base folders is equal.
In special cases you may actually just want to specify the double colon without any following design name, if you want to address a resource whose name equals your current folder name. For example this inside "projects:portlet":
<tml:url doc="::" file="icon.png"/>
Will retrieve a file "icon.png" from a file container simply named "projects:
<tml:url doc="projects" file="icon.png"/>
A selection of other places in WebTML where local references are allowed:
<tml:include ref="::module" linkaction="::action"/>
<tml:url type="css/js" name="::script" doc="::script"/>
<tml:url type="tml/content" layout="::module"/>
<tml:url type="action" action="::action"/>
<tml:action ref="::action"/>
<tml:button clickaction="::action"/>
Some places in TMLScript allowing local references:
WGA.callAction("::scriptmodule");
WGA.createObject("::scriptmodule");
WGA.design().loadObjectDefinition("::scriptmodule")
Going up folders
The double point symbol "..", known from regular file systems, may also be used to address parent folders of the current resource.
Imagine a WebTML module "home:info:portlet" which wants to include another WebTML module "home:panels:actions". To adress the latter from the former a local reference cannot be used as both modules are not in the same folder, just somewhere inside the same root folder "home".
You could of course include the "actions" module by simply specifying the whole reference. But you could also do:
<tml:include ref="..:panel:actions"/>
You can also use multiple ".." symbols divided by a semicolon to go up an unlimited number of parent folders. For example, this would address the same module:
<tml:include ref="..:..:home:panel:actions"/>
The ".." symbol also may be be practical when introspecting designs from TMLScript using the resolve() method on the Design object.
Imagine you want to retrieve the names of all WebTML modules in folder "home:panel" so you could serve them for some setting. You could do the following, still from the "home:info:portlet" module:
WGA.design().resolve("..:panel").getTMLModuleNames("html")
Why would you prefer to address resources relatively instead of always specifying the whole resource reference? It keeps you independent from future reorganisations of your design folders. In the examples above you could move the "home" folder to some other location without breaking any of these relative references. However the places where this is reasonable may be a matter of individual taste.
Going down below the current base reference
Sometimes in WebTML development you may have a folder as base reference, for example when using the resolve functionality in TMLScript. Imagine a folder "layouts" in your design where multiple WebTML modules and subfolders are available. You could get a Design object referencing this folder the following way:
var layoutFolder = WGA.design().resolve("layouts");
If your current base reference is a folder instead of a module then you might want to reference the modules it contains or its subfolders. To do this in a relative manner you need something to represent the current base reference in its completeness. The single dot "." can be used for this as it represents the current base reference. So this here goes down to to the subfolder (or design resource) "layouts:small":
var small = layoutFolder.resolve(".:small");
The @base suffix
This suffix is used inside designs which are overlays to customizable designs. It tells WebTML/TMLScript to not load the resource from the current design but rather from the base design which is customized. It is not used as part of the design name.
For example, this includes as WebTML module "modules:comments" from the base design:
<tml:include ref="modules:comments@base"/>
For obvious reasons the @base suffix cannot be be used in combination with the database key prefix or local references.