EZPORTAL.ORG

For those who are interested in building webpages using ztml by hand, this note will explain how this page was put together.

ZTML is intended to increase the speed and flexibility of your development efforts. It is possible, of course, to build a page by copying a design and putting it into a single template and then making whatever changes are needed to complete the page. However, doing so is only useful for building a particular page, or building one page at a time; when other, similar pages are needed, it may be difficult to reuse what you have already produced. ZTML is intended to simplify the process of reusing the elements of a template that you want to keep while changing those that must be unique for each page.

In order to take advantage of ZTML, the first thing you should do is think of your page in terms of sections. Thus, we will think of the design in terms of the sections need to build a page using a 3-column layout (ezportal.home.main). The sections we will use for this layout are defined below. Please note that this example assumes that certain content on our pages is relatively static and other content always changes with each page. In particular, we will assume that the center section contains the unique content for each page while the other sections remain the same.

• HTML Header - this section contains common HTML header tags such as title, meta, CSS links, and so on. This template also sets the common template markup language (TML) objects used for the all the pages that need similar layout.
• Page Header - this section displays the page header. The page section is further divided into three sections: row one, row two, and row three.
• Left Column - the left column is divided into three sections: navigation, newsletter, and login.
• Center Column - contains the main unique content for this template, such as the text you are reading now.
• Right Column - contains all other miscellaneous links for the page.
• Page Footer - contains footer information that is typically standard for each page.

As you can see with those sections, pages with different content can be created by just changing only the Center Column portion.

With the design divided into sections, now we must decide how best to create and specify the actual contents. The TML provides our method of organizing such a task. For example, you can place a big chunk of data such as the header and footer elements in a template but save all the small items such navigation links and images in separate TML object containers, which you can later place in any part of the templates. You can recognize a TML object by a keyword enclosed with a pair of curly braces ({keyword}). The TML objects can also be manipulated by TML directives, which are keywords that TML will use to perform specific desired functions.

Lets take a closer look into each section. The HTML Header has only one TML object (title), which was created by the Main Template, and one directive (use: ezportal.list.links.set). As you can see, you can create TML objects in the same or different templates. Of course, they must be created first before they can be used, otherwise they will be shown as is along with the rest of the content. So the placement of the TML directives is very important. The directive used for this template is "use," which tells TML to use the specified template at this point. So the template named ezportal.list.links.set will be called upon.

Now lets take a look at the ezportal.list.links.set and you will see that this template consists of all TML directives (set), which are used to set the various TML objects. This group of TML objects is mainly set up for navigation links. Although you could simply enter those anchor tags the way they are at any places where they are needed, they are much easier to handle when converted into TML objects first. For example, if the tags are long not only will they be difficult to read but prone to input errors as well. Most importantly, we have now created a reusable directive which will call upon the full set of tags whenever required.

After TML processes the directives in that template, all the link tags will be stored in the buffer with each item assigned with the name given by set. To place an item from the buffer into the template you simply enter the name and enclose it with a pair of curly braces. For example, enter {link.OSWD} will give you this: {link.OSWD}. As you can see, you can enter these TML objects anywhere and you will find that it is very easy to move them around too.

TML is a simplified web development language but provides enough sophistication that you can construct a complex web page with ease. Look at the left column for example, with the simple use of the switch directive, you can easily create an appropriate login input form where login is required only if the user has not been signed on. And by using a simple TML object substitution you can accomplish a task that otherwise might require using helper tools such as JavaScript. An example of this is the scheme_switcher. Also you might notice that every page has an about this template but if a page has no description then a default under construction page would be displayed instead.

Now comes the heart of TML - placing dynamic contents into a page. As you can see from the above, you can place contents into templates by entering data directly into them or by placing them in the templates using TML objects. However, data entered directly will not be changed so these are static contents, much like a regular HTML documents. TML objects, however, can be changed but they are not meant to contain a great deal of data since they are stored in the system buffer. However, you can use TML objects to store big blocks of data where needed as you will see later. So for this type of contents you must get them from the database. There are three tables that you can use to define the contents: template, document, and attachment. Although you could use the template table for general content you should not do so since its main purpose is used as formatting template. Therefore you should use document records for text contents and attachment records for binary contents such as photos, spreadsheet, etc.

Lets take a look an example of how to retrieve the data from the database table. The simplest way is to use the get directive. For example, Center Column template contains the following:

<!-- center column -->

<!-- For 1 column -->
#<div class="main1column">

<!-- For 2 column, main onleft -->
#<div class="main2column_onleft">

<!-- For 2 column, main onright -->
#<div class="main2column_onright">

<!-- For 3 column -->
<div class="main3column">

<!-- Inner Content div, for all scenerio -->
<div class="maincolumn_inner">

get: ezportal.about.main_page^zdoc
use: ezportal.doc.about.this.page
<br />

<img class="header_img" src="./icons_ezp/61+px/LionCrest-80at.gif" alt="About Ezportal" />

<h3 align="center">The ezPortal/ztml CMS Project</h3>

set: mode=html
get: ezportal.doc.about^zdoc
{tdoc}
{edit}
<div class="cleardiv" style="clear:both;"></div>
</div>
<!-- close content -->
</div>
<!-- close column -->
 

The parameters for the get above tells TML to get a record named ezportal.doc.about from the document table zdoc. This action will retrieve the data from ezportal and put them in various TML Document Objects. For example, tdoc object contains the text and edit contains a link to edit the document (the link will only show to the users that have the permission, regular users will see only the desired result).

The remaining two sections, Right Column and Page Footer provide additional navigation links and general information. One note of interest is the use of template editing. TML maintains a list of the templates used at any given point. You can use this information to display a list of links which you can click on to edit the templates. However, editing templates can only be done by the creator. So to use this TML object, switch directive is used to check for user name, which in this case the user must be admin. As you can see or or cannot see, a list of links is shown at the bottom of the page.

Create your own Template

When you start building your own templates, it is a good idea to group them using the naming conventions suggested below

• Group - the group that this template is assigned to. For example, all the ezPortal templates will be assigned with the name ezportal.
• Section - the section name for the template. This is to readily identify the section in which this template will appear. For example, header, footer, left, or right column and so on. A section may not necessarily be something that can be shown. For example, you could have a template only be used for setting up TML object data, so a section name such as list or table might be appropriate.
• Category or Theme - Your group might consist of many pages so it is a good idea to assign a name to the template so that it can be easily located. For example the guestbook is assigned with category named guestbook.
• Name - Finally a name for this template that will uniquely identify the template. If the name you want to use is already assigned to another template then you can add an extension to the name to make it unique.

Using the above naming convention this template is named ezportal.home.about.this.template.