Woof! - Locating Templates

Web Oriented Object Framework

User Guide (Version 0.4)

Directly Generated Page Sections The pagevar Object

Locating Templates

When the page object needs to locate a template to use as a layout or page section, it locates the template using a search path that allows for sharing and inheritance of templates as well as specialization for a specific controller or action.

When Woof! needs to retrieve a page section with name SECTION for responding to a client request with a URL that is mapped to a controller CONTROLLER and action ACTION, it follows the search procedure below. (When looking for a page layout template, SECTION will be layout.)

Woof! will first check for the existence of the file CONTROLLER-ACTION-SECTION.wtf in the views subdirectory of the directory where the controller module is located. This would correspond to a case where the layout or section was specific to that particular action for that particular controller.
If the file does not exist, it then looks for the file CONTROLLER-SECTION.wtf in that same views subdirectory. This corresponds to a layout or section that is shared among all actions of the controller that do not themselves have an action-specific template.
If neither is found, Woof! looks for a file SECTION.wtf in that same views subdirectory. This corresponds to a layout or section shared by all controllers within a module that do not themselves have a controller-specific template.
Finally, Woof! searches for a file SECTION.wtf in all views subdirectories working upwards through all parent module directories of the controller. The first file found is used as the template. This corresponds to the inheritance of a template from parent modules or the application itself. Note that in this last case, the controller name and action are not used in the search as it makes no sense to propagate controller and action specific names further up the module hierarchy.

The above algorithm is slightly modified when the client indicates a preferred language. Details are given in Language-Specific Page Templates.

Example: Sharing templates

The above search mechanism for templates allows layouts and page sections to be easily shared and inherited as illustrated by the examples below.

The examples assume the following layout is being used by the application:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
<html>
  <head>
    <title>Example Layout</title>
  </head>
  <body>
% if {[page fetch header content]} {
     $content
     <hr/>
% }
% if {[page fetch main content]} {
     $content
% }
% if {[page exists footer content]} {
     <hr/>
     $content
% }
  </body>
</html>

Assuming the above layout, a common header page section for the entire site can be defined by the contents of the file app/controllers/views/header.wtf. All URL's for the site will automatically show its content wherever the layout file inserts the page section named header. A different header section can be defined for a particular controller, say blogs, by creating the file app/controllers/views/blogs-header.wtf. The command

page fetch header content

in the layout will then fetch the header section content from this file for all URL's for the blogs controller and from app/controllers/views/header.wtf for all other controllers.

Example: Inheriting templates

As another example, imagine the website has a separate module, site::admin, that is used for managing the website itself. So the URL http://www.mywebsite.com/site/admin/user/show (for example) would be mapped to the show action method in the controller user (implemented in class UserController) in the site::admin module. To render the header page section, Woof! will look for templates in the following order:

app/controllers/site/admin/views/user-show-header.wtf
→ app/controllers/site/admin/views/user-header.wtf
→ app/controllers/site/admin/views/header.wtf
→ app/controllers/site/views/header.wtf
→ app/controllers/views/header.wtf

Note that when searching up the directory hierarchy, Woof! only uses the section name and does not look for the controller and action specific templates (such as user-show-header.wtf or user-header.wtf). This is by design as it does not make sense for a file specific for a controller and/or action to show up outside the controller content directory.