Template Examples


Registering Templates

    Template pages generally contain the HTML for the web application. Before a template can be rendered, it must be registered with the Page Manager. This allows the page manager to parse and store the template page for faster rendering. Template pages are generally registered in the constructor of Page Broker and Page Handlers. Each template registered is given a name. Generally if the template is the primary template for the page, the template will be named the same as the node itself (stored in the FQUID variable). Below are some examples from the demo site of template pages being registered.  As you can see, if you do not supply a filename, by default the template system will load "default.html", from the directory in which the class file resides.  Loading directly off disk will use the PageManager setting for the root of the template directory structure.  If the template system cannot find the file on disk (say if the servlet is stored in a JAR file), the a resource loader will be used.  If the template is located in the same directory as the class in the jar, it will be found.

Examples from demo Site:

Rendering Templates

    Rendering a template page takes the replacement hashtable and returns a rendered page. A template can be rendered into an HTTPResponse, for transmission back to the browser, or into a string for further manipulation. Below are some examples from the demo site:

Examples from demo Site:
HoldingDataBroker - Rendering to HTTPResponse
LoggedInJob - Rendering toString

Populating ReplacementTable

    Inside the actual template files are tags which are replaced with values from the replacement table. These appear in the template files in the format $$.fieldname. When the template system is rendering a template, it will replace these fields with the supplied value from the session or the replacement table.  Here's some examples from the demo site:

Examples from demo Site:
ErrorBroker - A Broker filling a replacement table for display

ErrorTemplate - The template with the display elements

HTML Form Elements

    Not only replacement tags are processed inside a template page. The template system automatically parses the name value out of form elements, and can dynamically populate the form elements during rendering. Here's some examples of each type of form element:

Radio Button - 

Insert the HTML code for a radio button in the HTML file as you normally would, naming the Radio group (with the name field) and giving each radio button a unique value (value field).  Then place into the replacement table the value of the radio button you want to be checked.  The template system will automatically locate the radio button with that value, and check it for you.  If your html file already had a radio button checked, it will be unchecked.  If you fail to supply a value for that radio button group in the replacement table, the template system will leave your radio group alone. If there was one already selected in the template file, it will still be selected.  If there was none selected, there will continue to be no radio button selected by default.  For example if this was in your template:

<input type=radio name=AmountOfSugar value=None> No Sugar please<br>
<input type=radio name=AmountOfSugar value=TwoLumps> Two Lumps please<br>
<input type=radio name=AmountOfSugar value=Extra> Extra Sugar please<br>
<input type=radio name=AmountOfSugar value=Insane> Insane Sugar please<br>
<input type=radio name=AmountOfSugar checked value=Rediculous> More sugar then any normal human would ever want<br>

And you rendered with an empty ReplacementTable, the resulting HTML would have the Rediculous radio button already selected.  If you rendered the HTML using this ReplacementTable:

    'AmountOfSugar' : 'TwoLumps'

The resulting HTML would have the TwoLumps radio button selected.

Checkboxes -

Checkboxes are either On, or Off.  Simply pass a Boolean object to the Name of the checkbox, and the template system will automatically check or uncheck the box for you.  If you do not supply a value, the checkbox will be unmodified.

Text/Password/Textarea - 

Text, Passwords and textareas all work the same.  Simply pass in a value for the name of the element, and it's value will be modified.

<input type=text name=TypeOfCoffee>

If the replacement table is:

    'TypeOfCoffee': 'Hazelnut'

The resulting html would be:

<input type=text name=TypeOfCoffee value="Hazelnut">

Selectboxes (Pulldown boxes) -

Pulldown boxes are a little bit more complex then the above datatypes.  Generally if you are doing a completely dynamic pulldown box you would just have a blank select box (with name) in your html code:

<select name="CoffeHouse">

Then you would build a SelectObject to describe what goes into that object.  Check the javadocs for the SelectObject for the available methods.  You will create a list of choies for that pulldown, and the value you want to be sent back to the web application if that select is chosen.  For example:

SelectObject so = new SelectObject();
so.addOption("Dunkin' Donuts",true); //True for default selected!

//Or do something like this:
for (Enumeration e = coffeeHouses.elements(); e.hasMoreElements();) {
    CoffeeHouse ch = (CoffeeHouse) e.nextElement();
    so.addOption(ch.getHouseName(), ch.getHouseID());

As you can see, you add elements into this select object in sequenced order, optionally passing in an ID which will be sent back to you (value) if that option is selected.  If you do not supply an ID, the name of the option is sent back.  Then simply put the SelectObject into the replacement table under the name of the select element you wish to replace in the template file.

Optional Display Areas

    On certain pages you might want sections of it to be hidden in some cases, and visible in others. If you've been through the demo site, you know there is a GZIP page which you can upload files into, and it will give show a bar graph on how much that file could be compressed. It makes no sense for that page to show a compression graph, if there is has been no file uploaded to compress.  We could use two template pages, one with the graph and one without, or we could simply hide the compression graph under certain circumstances.  Simply make the html for the compression bar graph optional.  The template page uses a special sequence to mark the beginning of an optional block of text.  
$$./FieldName. Appears if FieldName is true $$.FieldName/.
$$./!FieldName. Appears if FieldName is false $$.!FieldName/.
The ! character inverts the logical value.  Simply pass in a boolean object into the ReplacementTable to define the status of the optional block.  If you do not supply a value for the optional block, the default choice, as defined in the TemplatePage constructor, is used.

Examples from demo Site:
GzipBroker Template - Shows Compression Bar
GzipBroker - Show hiding the Compression Bar

Special Tags

    The template systems has certain tags which hold a special meaning. 
Linking to a Node on the PageTree:

Two sequences can be used for making a hyperlink to a page on the page tree.  When these special sequences are used, the sessionID is automatically added to the hyperlinks:

<a href="$$.!DLink:MainMenu.">Click Here</a>
<a href="$$.!DLink:MainMenu,AddUser.">Click Here</a>
<a href="$$.!RLink:AddUser.">Click Here</a>

DLink makes a direct link to a Page, so you must full qualify your request.  A RLink makes a link relative to the current page, if the template is being rendered by MainMenu, and you RLink to AddUser, you are really linking to MainMenu.AddUser.  Relative links are important if you will be regrafting Nodes to a new depth on the tree.  For RLink and DLink to function, you must properly hand a valid session object to the template system, so it can extract the session ID.  For RLink to function, you must have properly passed in a PageHandler to the template constructor (as you must also do for a Resource load of the template file). 

Hidden Form SessionID 
    The sequence $$.SessionHidden. Will be replaced with the hidden form element including the SessionID:
                <input type="hidden" name="SessionID" value="WhateverTheSessionIDIs">
Hidden Form FQUID

The sequence $$.!FQUIDHidden. will be replaced with a hidden variable storing the FQUID of the rendering page (if available).

<input type="hidden" name="FQUID" value="Admin.MainMenu">

Nested pages

You can include a subordinate Template page inside of a template page.  This page will be rendered, and replace the nested template sequence.  For example:


    Would be replaced with rendering the template page registered as "SomeTemplatePage" (in the page manager).  The replacement table used for this rendering would be stored in the parent ReplacementTable as "SomeTemplatePage".