The WebSite Sample

The target of this tutorial is to explain in detail the basic principles of an OpenWGA CMS template based on the sample website delivered with the OpenWGA Developer Studio.

If not already done create a new WGA web application inside your OpenWGA Developer Studio using "website-sample" as design template as described here.

The sample website looks like this:

Outer Layout

Introduced TML-Tags: <tml:include>, <tml:innerlayout>, <tml:url>, <tml:htmlhead>

As described in "OpenWGA Templates" OpenWGA CMS uses the concept of "outer layout" and "inner layout" defined in each content type to render a site page.

The outer layout CMS template in responsible for the global, content type independent part of the website. It typically "includes" the inner layout of a specific content type using the WebTML tag <tml:innerlayout>.

The outer layout CMS template of the sample website is found in file /designs/[your-project-name]/tml/html/outer/standard.tml in your OpenWGA CMS Runtime.

Here is the template code:

<html>
   
    <head>   
        <tml:htmlhead/>
        <link rel="stylesheet" href="<tml:url type="css" name="basic"/>">
        <link rel="stylesheet" href="<tml:url type="css" name="rtf"/>">
    </head>
   
    <body>   
        <tml:include ref="::body"/>       
    </body>
   
</html>

The tag <tml:htmlhead/> set some basic html meta tags and includes some JavaScripts used by OpenWGA. Even if it is not necessary in every situation we advice to add this tag to the html <head>-area of each outer layout template.

<tml:url type="css" name="..."> generates the URL to the specified CSS resource.

<tml:include ref="::body"/> includes the template code "outer:body" at the position of the <tml:include> tag.

Before we continue, lets have some information about addressing WebTML modules in WebTML:

As you will have noted there is quite a difference between the file name of the module /tml/html/outer/body.tml and the internally used name "outer:body". That is because:

a) The name of the WebTML module begins after the directory that determines the output medium of it, in this case "html". So the relevant path is "outer/body.tml".

b) Instead of "/" we use the colon ":" as a folder divider inside WebTML as long as design resources are concerned. (That is because module names may be used in URLs and should not break the OpenWGA URL scheme where only one path part is reserved for it)

c) The suffix ".tml" is ignored internally. It just identifies the file as WebTML module which is unnecessary to include in the name.

So the internal name of the module file outer/body.tml is "outer:body". But we instead referred to it as "::body". Why is that?

The part :: before the template name specifies that the template is searched in the same folder as the template that includes it. In the example above the template /designs/<your-design-name>/tml/html/outer/body.tml will be included. Using relative references makes it easier to structure and maintain your template code. For e.g. you can move or rename the folder "outer" without the need to change the references in you template code.

Note:

In the OpenWGA Developer Studio you can easily walk through the tml code by holding "CTRL" (or "CMD" on MacOS) and click on the tag ref-attribute value:


The Developer Studio will open the referenced TML-Module in a new editor tab.

Lets have a look at the TML-code of "outer:body":

<div id="page" class="rounded-box">

    <div id="header"><tml:include ref="::header"/></div>
    <div id="mainnav"><tml:include ref="::mainnav"/></div>

    <div id="childnav">
        <tml:include ref="::childnav"/>
    </div>
           
    <div id="content-wrapper">
        <div id="content">
            <tml:level from="3">
                <div id="pathnav"><tml:include ref="::pathnav"/></div>                       
            </tml:level>
            <tml:innerlayout/>
            <tml:case isdefined="tml"><tml:include ref="{tml}"/></tml:case>
        </div>
        <div id="teaser" class="rounded-box"><tml:include ref="::teaser"/></div>
        <div class="clear"></div>
    </div>
           
    <div id="footer"><tml:include ref="::footer"/></div>
   
</div>

The Code consists of some html <div>'s to define the html layout of the page. The body of the <div>'s again contains a <tml:include> TML-tag to include TML-Modules referenced by the ref attributes.

There is one special usage of <tml:include> in this module: <tml:include ref="{tml}"/>. The syntax attribute="{value}" tells the OpenWGA template engine, that the value of the attribute is calculated during the template processing. In this case the name of the referenced TML module is contained in a content item with name "tml". The item value is edited by an author. This special <tml:include> lets the author (instead of the template designer) specify what TML module should be included when this content document in rendered.

Another important new tag in this module is <tml:innerlayout/>. <tml:innerlayout> is a special kind of "dynamic" <tml:include> where the name of the included module is calculated based on the "inner layout" reference of the content type of the rendered page. Thats where the "inner layout" comes into the game.

Inner Layout

Introduced TML-Tags: <tml:item>

You find the inner layout TML modules of the sample website in folder designs/[your-project]/tml/html/inner.

Lets have a look at the inner layout of content type "standard" (designs/[your-project]/tml/html/inner/standard.tml):

<div class="rtf">
    <h1><tml:item name="headline" editor="textblock"/></h1>
    <tml:item name="body" editor="rtf"/>   
</div>

We see one of the most important TML-tags in this module: <tml:item>

<tml:item name="..."> looks up the named item in the content repository and returns its content. The attribute "editor" is used by the OpenWGA Content Manager to present the requested editor for this item.

Supported editors are:

  • textblock (free unformatted text, linebreaks allowed)
  • rtf (formatted text)
  • date (a date value)
  • text (a simple text value, no linebreaks)
  • number (a number)

to name just the most relevant.

Navigation and TML-Tag Context

Intoduced TML-Tags: <tml:navigator>, <tml:case>, <tml:link>, <tml:createpage>

The sample website contains two site navigations: a horizontal main navigation an a vertical sub navigation.

The horizontal navigation is defined in the TML-Module designs/[your-project]/tml/html/outer/mainav.tml and the sub navigation is defined in module childnav.tml.

Lets have a look at those. We start with mainnav.tml:

<tml:navigator type="children" context="name:home">   
    <div class="link<tml:case isselected="true"> selected</tml:case>">
        <tml:link/>
    </div>
</tml:navigator>
<div class="link">
    <tml:createpage message="new root document" context="name:home"/>
</div>
<div class="clear"></div>

The first new tag we want to discuss in this section is <tml:navigator>. Before doing this we have to talk about the OpenWGA concept of a "context":

Each TML-Tag is executed "in context" of a content document. This means that all references used inside a tag reference a defined content document. The outer layout template is rendered in the context of the content document specified in the request URL. The context of any TML tag can be implicit (like the context of the outer layout) or explicit defined by the TML designer. In addition some TML tags (like <tml:navigator>) implicitly change the context for the tags contained in its tag-body.

Back to the navigation tag of the sample website:

In <tml:navigator type="children" context="name:home"> the context is explicitly set to a document with unique name "home". The tag <tml:navigator type="children"> iterates over all "children" of the document specified by the context attribute - in this case the document with unique name "home".

The body of the navigator-tag is rendered for each child document in the context of the child document. The <tml:navigator> tag in the sample therefore creates a list of <div>...</div> blocks containing a link to that document- one for each child document.

Other tags used in this TML module:

  • <tml:link/>:
    creates a link (<a href="...">[title]</a>) to the document referenced by the "context" of the tag
  • <tml:case>:
    the tag-body is only rendered if the condition of the case-tag condition calculates to "true".
  • <tml:createpage>:
    The OpenWGA Content Manager uses this tag to display a "create-area" when the user clicks "create => new page"