Folders and Folder Lists

HTML templates

Basic information

An HTML template is a file containing HTML-code which WebsydianExpress uses to generate a web page in a browser.

Each HTML template contains static HTML code and a number of replacement markers for one web page. Static HTML code is information, often text and pictures, that does not change from request to request. Replacement markers are indicators which are used to specify where request specific data is to be inserted in the generated web page. This data is the data which is retrieved from the databases in the back-end system or generated for each new request. 

This document describes how WebsydianExpress handles the task of finding the templates and the options this provides for the user.

Presentations and file names

HTML templates are standard HTML files. The templates are stored in folders and has file specific names. WebsydianExpress retrieves the HTML code from the template files in order to present the web pages in the browser. For the WebsydianExpress runtime to retrieve the data you have to indicate the file name and the path for the folder in which the file is stored.

This document will focus on determining the path to the folder. But before proceeding with this, a few facts about how to determine the file name:

• The file name is determined in the program generating the page (PageGenerator function).
• The file name can be changed by defining a presentation for the content loader used for the page. A presentation is a specific layout of a page. Various pages can have various layouts, but not necessarily. The content loader is the function used to make the initial call to the business process program you have created. To change the file name you specify a suffix that will be added to the basic file name of all of the HTML templates belonging to the content loader. So if the PageGenerator refers to a basic filename of ABC.htm and the presentation defines a suffix "_1", then the file name the runtime will try to read is ABC_1.htm.

Folders

Basic information

Having all the templates files in one folder would be sufficient in some cases.

However, WebsydianExpress provides you with the possibility of presenting your site in different layouts to different users. To do this you will need a set of templates for each type of user. Therefore it is beneficial to structure the storage of the templates. As the file name is used to identify the template, different versions of the same template cannot be stored in the same folder in the file system. Therefore you can define several folders in WebsydianExpress to store the various sets of templates.

Physical folders and WebsydianExpress folders

In order for the runtime to be able to search for the template files you must first define the physical folders as WebsydianExpress folders.

To specify a WebsydianExpress folder you must indicate the path of the physical folder. You could say that a WebsydianExpress folder is an "alias" for a physical folder.

When you define a WebsydianExpress folder, there is more information you can provide that can have a significant impact on how the web page will be generated (see the section Resources for folders below). 

You can have one physical folder containing HTML templates and then define two WebsydianExpress folders using two different stylesheet files. An example where this could come into use is if you want to use your application for e.g. the Intranets of two different customers - and you want the two Intranet's layouts to be different. This means that one physical folder can be referred to by more than one WebsydianExpress folder.

Resources for folders

In addition to specifying the path of the physical folder you can provide information about where resources (e.g. image files), stylesheet files, and JavaScript files can be found.

Administration interface

The WebsydianExpress folders are created and maintained using the menu item Templates→Folders in the administration interface.

Folder lists

Basic information

As you can specify several folders for your template files, you must specify in which order the WebsydianExpress runtime must access the folders in order for the presentations to be correct.

You create this order by making a "folder list" and including the folders you want to be able to access in this folder list. The folder at the top of the list will be accessed first, then the second and so forth. 

You can define as many folder lists as you want to - and to each of these you can attach as many folders as you want to.

Determine folder list for a session

You must assign folder lists to the sessions.

You can assign a folder list to a session according to the user who has logged into the session or, if no user are logged in or the user have no folder list assigned, by using the roles assigned to the session.

Examples

During development

Most often during the development process your templates will go through different states. As an example, you could have templates in the the following states:

1. The raw templates (as generated by the DocumentTemplateGenerators/PageModeler)

2. Unstyled templates with JavaScript applied

3. Styled templates

As you will probably have templates in all states during development, it can be practical to create a WebsydianExpress folder for each of these template types, and then create a folder list that has the styled templates as the first folder, the unstyled templates as the second folder and the raw templates as the last folder.

This way you can test the site during the development and while the layouting work is ongoing. Once a template has been styled for the right look you simply move it up in the next folder, and the styled template will automatically be used.

Using special styles for groups of users

You can make your site look different to different users when they log in. It could be that you have customers from several different companies, and you want to use a special style or layout for some (maybe a simplistic layout just showing the company logo or limited or extended information to some. The options are almost limitless).

If the different layout is only a matter of looks which can be expressed in a stylesheet, you can do the following:

1. Place all of your templates in a physical folder. In this example the folder is named Default.
2. Place the templates that are influenced by the special look in another physical folder. In this example the folder is named Custom.
3. Create a WebsydianExpress folder for the Default physical folder.
4. Create a WebsydianExpress folder for each of the special looks. All of these must specify the path to the Custom physical folder and specify the stylesheet that defines the look.
5. For each special look create a folder list that has the folder containing the special templates first, and the Default folder second.
6. For each special look, create a role that has the corresponding folder list assigned and specify this role for all of the users belonging to the company for which you want to use the special look.
   Alternatively assign the folder list directly to each user.

If the different look not only relates to the stylesheet but also demands changes to the templates (e.g. removal of fields (information) for special groups of customers) - step one must be expanded to having one physical folder for each special style.

Administration interface

The Folder Lists can be created and maintained using the menu item Templates→Folder Lists in the administration menu.

Performance considerations

The WebsydianExpress folder lists provide a highly flexible way to control how the templates are found. However, this comes with a certain overhead.

Every time the runtime tries to access a template, it takes some time. This means that if a folder list has a number of folders, and almost all of the templates are placed in the last folder, a measurable overhead occurs for each request.

This does not mean that you should only define one folder for each folder list. It just means that you should not overdo the number of folders in each list - and you should try to create a situation, where the most used templates can be found in the first folder in the folder list.

Language Support

The folders and folder lists are a vital part of the language support of WebsydianExpress. The language dependent functionality becomes available in the administration interface when you define the first language for the site.

Folders and languages

For each folder, you can specify the language of the templates contained in the folder.

This means that each folder must only contain templates in one specific language.

The default value for the language of the folder is *Base (no translation). This will be specified for all folders that have been created before the first language was created. After creating the first language, you can still specify *Base as the folder language - these folders must then contain the un-translated versions of the templates.

Folder Lists and languages

When you build your folder list, you must consider the languages of the folders. For each folder you have with *Base, you must ensure that a corresponding folder containing the translated templates is included in the folder list for each language specified in the site.

It is recommended that you also keep the folders containing the *Base templates in the folder list. These will be necessary for any users who have *Base specified as language. In addition to this, if WebsydianExpress cannot find templates for the specified language e.g. if some templates remain to be translated, it will revert to *Base and thus ensure that the site is intact at all times.

When the runtime searches for a template, it looks through all of the folders in the folder list that have either the language of the current session or *Base. The folders will be searched in the order they are shown in the folder list in the administration interface.

Related information