Templates - Catalog

Templates are one of the huge benefits to using the UltraCart Catalog system. A template driven site can have 80,000 products that have over 100,000 pages, yet the look and feel might be controlled by a dozen or so templates. If a merchant wants to update the look and feel or functionality of the site they simply edit the templates for the site and it instantly updates. By removing the hand edited nature of every single page on a website, a massive reduction in the amount of man power required to maintain a large e-commerce site is instantly achieved.

In the UltraCart Catalog system a template is simply HTML code that contains Velocity scripting embedded into it. The template is "rendered" by the Velocity engine which merges the template with the appropriate data for the page. The Velocity script on the page has an opportunity to process and manipulate the data and ultimately output additional HTML code such as the item description, navigation links, etc. Rendering can be viewed as a simple math equation:

Template + Data => Rendered HTML

Templates are managed under the "Manage Catalog Templates" link on the catalog menu.



After clicking on the Manage Catalog Templates link a list of all the configured templates is displayed.



To create new templates simply click the "new" bottom. There is also a handy search feature that allows you to filter the list of templates to only those that contain specific text. The search is a very handy feature. At this point the list contains only "template_group" and "template_item" from our the Hello World sample that has been adapted since Chapter 2. Clicking edit on one of the templates will display the template editor shown below:



At the top of the template editor is the name of the template. The name should be short and descriptive to allow any developer to quickly identify the purpose of the template. We recommend using the prefix of "template_" at the beginning of any template that is directly assigned to a group. Any template that is going to be included by other templates we recommend using the prefix "snip_". Sometimes the name of the template is not descriptive enough. There is a free form description field that can be used to describe the purpose of the template. It is a good idea to give every template a description for documentation purposes.

Below the description of the template are two check boxes for the type of template: "Group" and "Item". These boxes are used to help identify which type of template it is. When editing a catalog group only the templates with the proper group or item boxes check will appear in the drop down lists to select from. This means leaving both of the boxes unchecked for an included template (usually prefixed with "snip_") will keep it from appearing in the drop down boxes.

Finally there is the template text area where the actual HTML and velocity code is entered. It is important to point out that reference documentation is available in a popup window by clicking the "Documentation" link just below the template text area title as shown below.



Now that the basics of navigation and the template editor have been explained, it is important to cover the actual mechanics of the templates being used. There are two types of templates used within the UltraCart catalog system: group and item. A group template is used to render a directory style URL on your website whereas the item template is used to render the page for a specific item.

In Chapter 5 the demonstration store had a series of additional groups added to it and then reassignment of items. Below are two valid URLs for the store:
/products/tvs/bluray_and_dvd_players/
/products/tvs/bluray_and_dvd_players/index.html/products/tvs/bluray_and_dvd_players/SONY-DVD.html

The first two URLS access the group of the catalog using the group template view. The group template will show all the items that are assigned to the "Blu-ray and DVD players" group.

When a template is rendered the Velocity code within the template can take advantage of various objects that are already in the context. The most basic context variable is the group object for whatever group is currently being accessed by the customer. If an item page is accessed by the customer then the "item" object will also be present in the rendering context. To see a list of all the objects available in the context click on the "Documentation" link. A list of all the objects available is shown below.

The second tab of the documentation window will also show you all the objects and the various methods that can be called on each object. Below is an example of one of the methods on the Group object used to fetch the child groups.



In the Hello World example we started out with two templates "template_group" and "template_item" that performed very basic rendering actions. After the enhancements in the prior page, the group template learned how to render navigations to other child groups. These very simple templates though share nothing in common. The reality is that group pages and item pages share many navigational and page elements in common. As with any good programming language it would be nice to extract the shared contents into a single location and reference it. For example it would be nice if there was a header across the top of the demo store that said the store name, provided a home navigation, and provided a menu across the top to all the major categories.

The first thing to do is create a new template called "snip_topnav" with the following template code:

## Fetch the root group of the site.
#set($rootGroup = $group.getRoot())

## Output a table with the link to our home page and 
## then another row with links to each high level group
<table>
  <tr>
    <td colspan="$rootGroup.getChildren().size()">
      <a href="${baseUrl}${menuGroup.getPath()}">$rootGroup.getTitle()</a>
    </td>
   </tr>
   <tr>
     #foreach($menuGroup in $rootGroup.getChildren())
       <td>      
          <a 
href="${baseUrl}${menuGroup.getPath()}">$menuGroup.getTitle()</a>
       </td>
     #end
   </tr>
</table><br><br>

Next go back to each of the other two existing templates and edit "template_group" and "template_item". At the top of each of the templates enter the text #ucTemplate("snip_topnav") as shown below:



The text #ucTemplate("snip_topnav") is a custom velocity directive that causes the snippet to be included exactly at the location of the #ucTemplate directive. Make sure that no additional spaces are introduced between the directive, parenthesis, and quotes on an include directive or it will not work. Now the sample store has a consistent top navigation for group and item pages as shown below:

It is permissible for one template to include another template that in turn includes additional templates. UltraCart will automatically expand the templates before passing the expanded template through the Velocity rendering engine. A good rule of thumb is to utilize an included snippet whenever any piece of HTML/Velocity code can be shared between two high level group or item templates. Good candidates for snippet templates are the HTML head section, top navigation, side navigation, footer, custom tracking code, paging navigation, etc. Reuse is not the only compelling reason to use templates. The other is manageability of the code. It is often easier to work on a 50 line snippet of HTML code than a 1000 line single template.

The most basic catalog sites will have three templates that are users: template_home, template_group, and template_item. The template_home would be the home page template and would typically have a more sophisticated look and functionality than a standard group template. In reality there will be additional high level templates within a catalog each time a page renders data in a different fashion. For instance an electronics store may have different a different group template for the cell phone product category than other items in order to display additional information or have an alternate format.