Please Note: Before printing, you may need to adjust the Print Size within your browser to 100%.

Template - Introduction

Templates are used by Freedombase, to provide developers with absolute control over the Freedombase user interface. Templates are HTML/DHTML pages, with % tags that tell Freedombase how the page should be integrated with Freedombase and the database. Templates can be edited using any recent HTML editor.

Instead of forcing developers to use Web pages of particular styles or layouts, or that may not fully work on some browsers, Freedombase allows developers to create and implement any styles and layouts that they like, and to make the pages compatible with any browsers that they like. This is achieved by editing Freedombase templates, then telling Freedombase to implement those modified templates.

Freedombase will create default Templates, that follow a particular, default Freedombase style, that is suitable for most in-house applications. Those templates can then be modified to follow any other layout or style as required. Default templates are fully functional on all major browsers. New templates can also be created from scratch.

Generally, each Web page in the Freedombase user interface will have one template, controlling how that page works and appears. It is, however, also possible to share templates or between user interface pages.

Template - Tags

Templates will contain well know, normal html tags (starting with '<' and ending with '>') and can contain Web scripting languages such as JavaScript or Visual Basic (VB) script. Freedombase will add a small number of scripts, and some hidden fields, into the template pages to assist in integrating the pages with Freedombase.

Freedombase tags (starting and ending with '%') can also be included in the page to tell Freedombase what to do when outputting the user interface page to the user. Normal Web/HTML form submission (usually input fields) are used to submit the data from the browser back to Freedombase.

Template - Attributes - Tag

The most commonly used Freedombase tag is the %System_Class_Attribute% tag. This tag tells Freedombase to insert the value from the given Attribute, from the given Class, from the given System, into the page at this point. Please note that System means approximately the same as Application or Account; Class means approximately the same as Table; and Attribute means approximately the same Field. In most cases, these tags will contain actual application, table and field names, with any underscores ('_') removed from within the names.

This tree structure, allows Freedombase to easily output data from multiple different tables into the one page, without any confusion as to what data should be output at that point. We say tree structure, as each Application can contain many Tables, and each Table can contain many Fields, allowing this one tag type to output any data in any field from any table in any application.

Generally, object oriented terminology is used within Freedombase, so Table will normally be referred to as Class, and Field will normally be referred to as Attribute.

Template - Attributes - Multiple Records

Freedombase easily outputs data from multiple records from the same table. Freedombase achieves this by maintaining a list of records that could be output and a pointer as to what record is currently being output, and moving the pointer to the next record when appropriate.

For single valued fields, Freedombase moves the pointer to the next record, whenever it is asked to output a field again and it has already output that field for the current record. This makes outputting data for multiple records as easy as simply repeating the Attribute tags.

For example, if the page contained the following tags:

%EXAMPLES_CUSTOMER_NAME%
%EXAMPLES_CUSTOMER_ADDRESS%
%EXAMPLES_CUSTOMER_NAME%

%EXAMPLES_CUSTOMER_ADDRESS%

The following would occur (please see the explanation in brackets):

%EXAMPLES_CUSTOMER_NAME% (NAME has not yet been output for the current CUSTOMER record, so output the value of the NAME field from the current CUSTOMER record.)
%EXAMPLES_CUSTOMER_ADDRESS% (ADDRESS has not yet been output for the current CUSTOMER record, so output the value of the ADDRESS field from the current CUSTOMER record.)
%EXAMPLES_CUSTOMER_NAME% (NAME has been output for the current CUSTOMER record, so move the pointer to the next CUSTOMER record, and output the value of the NAME field from that next CUSTOMER record.)
%EXAMPLES_CUSTOMER_ADDRESS% (ADDRESS has not yet been output for the current CUSTOMER record - remember, we are now pointing at the second record, not the first record - so output the value of the ADDRESS field from the current CUSTOMER record.)

Multi valued fields are handled in a similar manner, except that the pointer moves to the next multi value within the current record, instead of moving to the next record.

Template - Attributes - Repeating Output

From time to time, it is necessary to output the data from the same field in the same record, multiple times. The method Freedombase uses to point at the next record would normally prevent this; the moment Freedombase sees the same field name referenced again, it will point at the next record.

This 'point at the next record' behaviour can be prevented, however, by appending a 'C'urrent tag to the end of the Attribute tag, in the format %System_Class_Attribute_C%. Wherever Freedombase sees the 'C'urrent flag, it output the data without moving the pointer.

For example, if the page contained the following tags:

%EXAMPLES_CUSTOMER_NAME%
%EXAMPLES_CUSTOMER_ADDRESS_C%
%EXAMPLES_CUSTOMER_NAME_C%
%EXAMPLES_CUSTOMER_ADDRESS_C%

The following would occur (please see the explanation in brackets):

%EXAMPLES_CUSTOMER_NAME% (NAME has not yet been output for the current CUSTOMER record, so output the value of the NAME field from the current CUSTOMER record.)
%EXAMPLES_CUSTOMER_ADDRESS_C% (Output the value of ADDRESS from the Current record. Do not check if the pointer should be moved, and do not move the pointer.)
%EXAMPLES_CUSTOMER_NAME_C% (Output the value of NAME from the Current record. Do not check if the pointer should be moved, and do not move the pointer.)
%EXAMPLES_CUSTOMER_ADDRESS_C% (Output the value of ADDRESS from the Current record. Do not check if the pointer should be moved, and do not move the pointer.)

It is actually more efficient to use the 'C'urrent option wherever possible, and to only use the Attribute tag without the 'C'urrent option, when Freedombase needs to check, set and possibly move the pointer. Most default pages within Freedombase will set the 'C'urrent option on all but one or two Attribute tags, in order to take advantage of this efficiency gain.

Template - Attributes - Setting the Pointer

When Freedombase first starts loading data into a template, to get the page ready to return to a user, the pointer is not actually pointing at any record. The first Attribute on a page, without the 'C'urrent option set, causes Freedombase to set the pointer to the first record.

For this reason, the very first Attribute output onto a page must not have the 'C'urrent option set. No data will be output onto the page, until the first non 'C'urrent Attribute tag is reached on the page.

Template - Attributes - What Records?

This tutorial has referred to outputting both single and multiple records onto one page, and has introduced the pointer that Freedombase uses to control which record the data should be output from next. But how does Freedombase select which records should be in the list of records that can be output?

The command passed back in the last data from the browser into Freedombase, controls what records can be output to the page. If the command was 'New', no records will be output at all; Attribute tags will be replaced with blank or empty values. If the command was 'Go' or 'Get', then Freedombase has probably been given the key to the one record that could be output. If the command was a 'Search' command, then Freedombase will probably have a list of record keys that met the search criteria, and that list will be used to determine what records can be output to the page. And if the command was 'ViewAll', then Freedombase can output all records in the table.

Essentially, the last command that the user selected or clicked on, will control what records Freedombase will output onto the page.

These commands will be built into the default template that are created for you; normally, you do not need to set the commands up yourself. Once you are experienced with Freedombase, you may like to set up custom commands for your own purposes; however, this is an advanced topic, and should wait until you are confident with the standard commands built into Freedombase.

Template - Attributes - Multiple Tables

Freedombase will output data from any number of multiple tables, without requiring any programming, if relationships have been set between the tables in the Freedombase Designer. The relationships do not have to be direct; as long as there is a path between the tables, even if that path contains multiple inbetween steps, Freedombase will find the related data and output the related data without any effort.

Freedombase must be told, or must know, the first record to be output. From there on, Freedombase will drill to find data in the related tables, and will output the related data without any programming.

Please see the previous 'What Records?' page for information on how Freedombase knows what the first record is to be output.

Template - Expressions - Introduction

Another very useful, although less common, Freedombase tag, is the Expression tag. This takes the form of an opening Expression tag (%E%), followed by an expression, followed by the closing Expression tag (%/E%).

Freedombase Expressions are very similar to Freedombase Calculations; please see the Freedombase Calculation Help page for more details on Calculations. All commands and options are the same between Expressions and Calculations, except that Attribute and System_Class_Attribute work differently between the two.

Calculations are capable of looking up the database themselves, to find related records. Expressions cannot look up the database themselves. All data to be used within expressions must be set by the developer within the expression using the Template Attribute tag.

Expressions return a value to be inserted into the page at that point, much like a spreadsheet calculation returns a value into the spreadsheet at that point.

For example, to output different text onto a page depending on whether a customer owes money or not:

%E%(IF(%EXAMPLES_CUSTOMER_BALANCE%>0)THEN('They owe us money')ELSE('They do not owe us anything!'))%/E%

Another example, one used more frequently with Freedombase, is setting the 'selected' or 'checked' text within a select/drop down, or a checkbox or radio input field:

<option value="C" %E%(IF('%EXAMPLES_CUSTOMER_TYPE%'='C')THEN('selected'))%/E%>Corporate</Option>

Or:

<input type="radio" value="C" %E%(IF('%EXAMPLES_CUSTOMER_TYPE%'='C')THEN('checked'))%/E%> Corporate

Template - Include/Insert - Introduction

You can create includes for templates. These are 'chunks' of HTML code, scripts, or anything else, that are be included in the template at compile time.

Includes are very useful for sharing common HTML or scripts between multiple templates. Menus, for example, are often held within includes. To change the menu on all pages, you can then change just the include, then rebuild the templates that use the include.

Includes can include other includes, to any number of levels, but includes cannot be recursive.

Includes are treated the same as templates, are stored in the Template directory, and can be created and edited through either the Template directory, or through the Template page in the Designer. Includes do not need to be (re)built when they are changed.

To tell Freedombase to insert an include in the page, use the %I IncludeName% tag at the appropriate point.

For example: %I MainMenu%

Template - Security - Introduction

You can control what users see what on each page, using Security tags.

Each user can have a list of security settings or values held for them, in the User page in the Designer. Security tags within templates check against that list, and only include anything between the security opening and closing tags if there is an appropriate match.

Security tags are in the format %S Relationship Value [Relationship Value]% the conditional HTML or tags %/S%

Relationship will usually be =, but it can be NE, >, etc. Please note, however, that if you want to use relationships other than =, you must ensure that every user has at least one security value set. = is the only relationship that works correctly if any users do not have security values set.

For example:

<input name="EXAMPLES_CUSTOMER_NAME" value="%EXAMPLES_CUSTOMERS_NAME%">
%S = CreditLimit = Administrator%
<input name="EXAMPLES_CUSTOMER_CREDITLIMIT" value="%EXAMPLES_CUSTOMERS_CREDITLIMIT%">
%/S%
<input name="EXAMPLES_CUSTOMER_BALANCE" value="%EXAMPLES_CUSTOMERS_BALANCE%" readonly>

In the above example, only users with security settings of CreditLimit or Administrator will be able to see or set a customer's credit limit. The page will actually display differently for these users; these users will see the Credit Limit information, whereas the same page, for other users, will not contain the Credit Limit information at all.

Template - Repeat/Loop - Introduction

It is often necessary to output the same HTML, or the same portion of a template, multiple times. The number of times may vary, as well.

Generally, repeat is used to repeatedly output rows within a table.

For example, if you want to list all the records in a table, so the user can select from the records in that table, you cannot know when creating the template, how many times you should repeat the HTML that actually lists each record. Instead, you would define that HTML once, then use a repeat to loop through that HTML as many times as was necessary.

The primary parameters for the Repeat tag are: %R [System_Class] [NumberOfRepeats]%. Please note that there are other parameters as well. Only the most important parameters are listed here. Either or both System_Class and NumberOfRepeats can be set. If only System_Class is set, then the repeat will loop until all appropriate data within that System_Class has been output. If only NumberOfRepeats is set, then the repeat will loop that number of times. If both are set, then the repeat will loop while both are true - as soon as all appropriate data has been output from the class, OR as soon as the NumberOfRepeats has been met, the repeat will stop looping.

We say 'appropriate' data in the previous paragraph, as the last command executed will determine what records within the table will be output. If the last command was view all, then all records will be 'appropriate'. If the last command was a Search command, then only the records matching the search criteria will be 'appropriate'.

For example:

<table>
 <tr>
  <td>Customer Name</td>
  <td>Customer Address</td>
 </tr>
%R EXAMPLES_CUSTOMERS 15%
 <tr>
  <td>%EXAMPLES_CUSTOMERS_NAME%</td>
  <td>%EXAMPLES_CUSTOMERS_ADDRESS%</td>
 </tr>
%/R%
</table>

In the above example, the table row outputting the customer name and address, will be repeated a maximum of 15 times, or until there are no more 'appropriate' Customer records left to be output. Freedombase will move the pointer forward from one Customer record to the next, every time %EXAMPLES_CUSTOMERS_NAME% is reached, making this a simple way to output multiple records on the page.

Template - Command - Introduction

When data is passed from the page back to the server, Freedombase decides what to do with that data based on the value of the Freedombase_Interface_Command field returned with the data.

The primary commands are 'Save', 'Delete', and 'New'. Other command commands are 'Search New', Search Shrink', 'Search Expand', 'Search Invert', 'ViewSearch' and 'View All'.

Please see the Template Command Help for more information on these are other commands.

Template - Creating - Defaults

You can create default Templates for any class or table defined within Freedombase.

Default templates are created using the (Re)create Templates utility, on the Class page within the Designer. To use this utility, bring up the class or table you want to create the default templates for, and then select the (Re)create Templates utility option from the menu. You will be warned that creating default templates may overwrite existing templates. If you choose to continue, the default templates will be created, overwriting any existing templates for that class or table.

Template - Creating - Porting Forms

It is possible to port OpenInsight forms and popups to the Web. This will create Freedombase templates that look substantially like those forms and popups, and that integrate with the database and with Freedombase.

Porting forms and popups allows developers to very quickly perform a large portion of the work of Web enabling existing OpenInsight applications, in very little time, and with very little effort. Please note that some business logic will still need to be added to the interface and the database, once the forms and popups themselves have been ported.

At the time of writing, forms could be ported to the Web using the command line function FBTEMPLATEOIFORM, and popups could be ported to the Web using the command line function FBTEMPLATEOIPOPUP. Both functions require two arguments. The first argument is the Application name that the form or popup is held within, and the second argument is the actual form or popup name. Please note that any tables referenced by the forms or popups must be attached to the account that Freedombase is running within, before these functions will run successfully.

In the very near future, access to these functions will be provided via an OpenInsight form, to make these functions easier to use.

The templates created from each form and popup, will be named ApplcationName_FormOrPopupName.htm.

For example, to port the form DEMO_FORM from the DEMO application:

FBTEMPLATEOIFORM "DEMO","DEMO_FORM"

Template - Creating - Manually

Generally, if you want to manually create a template, you should copy an existing template, then make appropriate changes to that copy. Although you can literally create templates from scratch, it is usually quicker to not have to.

Template - Edit - Introduction

Templates exist in the Template directory, in the directory that Freedombase was installed within.

Templates can be edited within that directory, using any recent HTML editor, or any text editor if you prefer to work in the raw HTML.

Templates can also be edited - in raw HTML format only - through the Template page of the Freedombase Designer.

As a general rule, we recommend editing the templates directly within the Template directory, when working locally; and editing the templates through the Designer Template page, when working remotely. Of course, you need to choose whichever method works best for you according to your circumstances.

Once a template has been modified, you need to rebuild it, before the new version of the template will be accessible via the user interface. You can select the '(Re)build Template' utility in the Designer Template page, with the template on display, or you can run the FBTEMPLATE "TemplateName.htm" command line function to rebuilt the template.

Please note that rebuilding the template is different to recreating the template. Rebuilding the template turns the template into a program, but does not change the template itself; whereas recreating the template overwrites the template with a new, default version.

Template - Update - Introduction

At some stage, information on the browser needs to come back to the database and Freedombase, to be updated into or deleted from the database, to be searched for, or for many other purposes. Freedombase uses standard HTTP Post form submission to pass this data from the page back to Freedombase.

One of the pieces of data passed back is a Command field, telling Freedombase what action to take.

The same Attribute naming convention of System_Class_Attribute, is used when submitting data from the page back to server. This is the same naming convention as is used when outputting data from the database into the page, but without any % signs.

For example, the following HTML will cause data from the NAME field on the CUSTOMER table to be set as the value of the input field on the page; and then the name of the input field, will cause the data to be returned to the NAME field on the CUSTOMER table when the form is submitted:

<input type="text" name="EXAMPLES_CUSTOMER_NAME" value="%EXAMPLES_CUSTOMER_NAME%">

Template - Custom Code - Introduction

Custom BASIC code can be added to templates at three fundamental points; Before; During; and After.

Before and After custom code shares the same parameter list, and can be created for a template using the Create option, next to the Before or After code prompt, in the Designer Template page, with the appropriate template on display. Although Before and After code shares the same parameter list, the usage is usually different.

During code, using the X (Execute Subroutine) tag, can be integrated anywhere into the page, any number of times.

Please see the Custom Code tutorial for more information on Before, During and After code for Templates.