PurpleWiki: Templates

PurpleWiki Templates (N2)

Beginning with v0.93, PurpleWiki allows you to customize look-and-feel using Templates. By default, PurpleWiki uses TemplateToolkit for template support. However, it can be customized to use other template libraries as well. (N3)

Every function on PurpleWiki has an associated template. For example, viewPage.tt is called whenever someone views a page. editPage.tt is called whenever someone edits a page. (N4)

By default, templates are stored in wikidb/templates (configurable in the config file under TemplateDir), which uses the following directory structure: (N5)

templates (N6): Each of these templates map to some PurpleWiki function (N7)
templates/errors (N8): Each of these map to a PurpleWiki error (N9)
templates/common (NA): These are the common elements that appear on every PurpleWiki page, such as the header and footer. Most people will be able to get the look-and-feel that they want by only modifying these files. (NB)
templates/lib (NC): Some of the more complicated look-and-feel elements, such as recentChanges.tt, are encapsulated here. Most people will most likely not edit these, although they are there if you want to do so. (ND)

Most of the files in the templates directory take the form: {nid NE} [news paper ads design] [news paper ad design] [pamphlet design] [post card design] [stickers design] (7V8)

  [% INCLUDE common/header.tt
             title = "Some title"
  %]    (NF)

  Some text relevant to the functionality of the page.  For example,
  in viewPage.tt, this contains a reference to the body variable.  In
  editPage.tt, this contains an HTML form for editing the content of a
  page.    (NG)

  [% INCLUDE common/footer.tt %]    (NH)

As you can see from this example, most people will be able to customize the entire look-and-feel of their site just by editing the common/header.tt and common/footer.tt templates. (NI)

Template Variables (NJ)

The variables that are available for each template should be self-explanatory. This section lists some of the common and noteworthy variables. (NK)

The following variables are available to all templates: (NL)

siteName (NM): Name of the site. Corresponds to SiteName in wikidb/config. (NN)
baseUrl (NO): Base URL used for constructing URLs for accessing Wiki pages, actions, etc. Corresponds to ScriptName in wikidb/config. (NP)
homePage (NQ): Name of the Wiki home page. Corresponds to HomePage in wikidb/config. (NR)
userName (NS): Username. If user is not logged in, this variable is undefined. (NT)
preferencesUrl (NU): URL for editing preferences. (NV)

The view and edit templates all use pageName, which corresponds to the name of the page being viewed or edited. The edit templates also use id, which corresponds to the internal page name. The only time the internal page name is different from the displayed page name is when the name has spaces in it. For example, [[Hello World]] would link to a page of id "Hello_World" and of pageName "Hello World". (NW)

Both the view and edit templates also have access to visitedPages, which is a list of hashes containing the pageName and id of recently visited pages: (NX)

  visitedPages = [
      {
           id => ...,
           pageName => ...
      },
      ...
  ]    (NY)

viewPage.tt and viewRecentChanges.tt have access to expandedPageName, which adds spaces to page names that are WikiWords. By default, this is used in the HTML <title> attribute so that search engines do a more accurate job of indexing Wiki pages. You could easily use it for the page headline as well. (NZ)

lib/pageHistory.tt displays the pageHistory variable, a list of metadata associated with each version of a page: (O0)

  pageHistory = [
      {
          revision => ...,
          pageUrl => ...,
          diffUrl => ...,
          dateTime => ...,
          user => ...,
          host => ...,
          summary => ...
      },
      ...
  ]    (O1)

lib/recentChanges.tt displays the recentChanges variable, which consists of a list of dates. Each date has a date field (a displayable string) and a list of pages. (O2)

  recentChanges = [
      {
          date => ...,
          pages => [
              {
                  id => ...,
                  pageName => ...,
                  time => ...,
                  diffUrl => ...,
                  numChanges => ...,
                  changeUrl => ...,
                  summary => ...,
                  userName => ...,
                  userId => ...,
                  host => ...
              },
              ...
          ]
      },
      ...
  ]    (O3)

lib/searchResults.tt displays search results from each installed search module. The two important variables are modules, which contains the names of the installed modules, and results, which uses the module name as a hash key and returns a list of results: (O4)

  results = {
      Wiki => {
          url => ...,
          title => ...,
          lastModified => ...,
          summary => ...
      },
      ...
  }    (O5)

Writing Template Drivers (O6)

In order to use other template libraries with PurpleWiki, you will need to write a Template driver. All you have to do is inherit PurpleWiki::Template::Base and overload the process method. (O7)

We take advantage of TemplateToolkit's support for sophisticated data structures, but we also realize that not all template libraries have the same capabilities. As the need arises, we will consider modifying some of the data structures passed to the templates in order to better support other libraries. (O8)

Views Versus Templates (O9)

PurpleWiki has the notion of both Views and Templates. Views correspond to how a page is expressed, be it XHTML, plain text, or some other format. Templates correspond to the overall site's look-and-feel. (OA)

Templates