Back to Search Back to Search Results

Custom Pages

The /pages/custom folder contains full-page templates that can be used to extend the functionality of a Portal by adding new pages.

Custom pages can be linked to via <a href=<@harp.pageUrl page="path/to/custom/page.ftl" />>Link Text</a>. The path must be relative to the /pages/custom/ directory.

Page Variables

In addition to the common variables, all custom pages have access to the following:

multiValueParams
A hash of the URL request parameters, with all values for each parameter in a string array.
params
A hash of the URL request parameters, holding a single value for each parameter. (Do not use for multi-value parameters.)
requestBody
An HttpEntityContent object representing the HTTP request body (if any).
UUID
A generated UUID that can be used to identify individual page views for analytics recording purposes.

Specifying Content Type via File Extension

By default, the Content-Type header for custom pages is text/html. However, if the base name of the file has an extension with a known file type, the system will automatically select the appropriate value for the Content-Type header. For example, the custom page template /pages/custom/example.css.ftl would be served with a Content-Type header of text/css.

Here are some common file extensions and the resulting content type.

Note: If a file extension is not recognized, the Content-Type header will be text/html.
Extension Content Type
*.css.ftl text/css
*.js.ftl application/javascript
*.xml.ftl application/xml
*.dita.ftl and *.ditamap.ftl application/dita+xml
*.txt.ftl text/plain
*.csv.ftl text/csv

HTTP Headers for Custom Pages

By default, Titania Delivery serves custom pages with a minimum of HTTP headers, and a Content-Type header determined as described above. You can customize the HTTP headers sent for a given custom page by specifying those headers in metadata with keys beginning with _td.header.. For example, specifying _td.header.Content-Type=application/xml on a page's metadata will cause it to be served as an XML document.

Example Usage

A new custom page can be created with the following steps:

  1. Create a file named test.ftl somewhere on your computer. Paste in the following code:

    <!DOCTYPE html>
<html lang="en-US">
 <head>
  <meta charset="utf-8" />
  <title>Hello, Titania!</title>
 </head>
 <body>
  <h1>Hello, Titania!</h1>
  <p>Welcome to the ${portal.name?html} portal</p>
 </body>
</html>
  2. In your Portal Theme, select the pages/custom/ directory
  3. Click the Upload tab then click "Select a file..." to upload your file or drag your file to the location specified. You should now be able to see, and edit, test.ftl from within the browser.

  4. In portal-home.ftl, add the following in the first line after <div class="container">

    <a href=<@harp.pageUrl page="test.ftl" />>Test Page</a>
  5. Navigate to the Portal homepage and click the link to be taken to the new custom page.

One common use of custom pages is to render non-DITA content such as Microsoft Office, PDF, or graphic files. Using the above steps, create a new custom template called pngViewer.ftl. Paste in the following code:

<#assign td=JspTaglibs['http://www.titaniasoftware.com/harp/taglib']>
<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="utf-8" />
  <title>${portal.displayName?html}</title>
</head>
<body>
  
  <#if params['projectKey']?? && params['itemKey']??>
    <@td.fileProperties 
          var="itemData" 
          projectKey="${params['projectKey']}" 
          itemKey="${params['itemKey']}"/>
  </#if>
  
  <#if itemData??>
    <h1>${itemData.properties.specifiedDetails.title?html}</h1>
    <img src="<@td.viewerUrl item=itemData.item/>"/>
  <#else>
    <h1>No such file.</h1>
    <a href="javascript:history.back()">Go back.</a>
  </#if>
  
</body>
</html>

Then, set the contents of searchResults.ftl to:

<#assign td=JspTaglibs['http://www.titaniasoftware.com/harp/taglib']>
<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="utf-8" />
  <title>${portal.displayName?html}</title>
</head>
<body>
  
  <h1>
    Search Results:
    ${term?html}
  </h1>
  
  <#if result.content?size == 0>
    <h2>No Results</h2>
  
  <#else>
    <ul>
      <#list result.content as group>
        
        <#assign filename>
          ${group.firstResult.filename?lower_case?trim}
        </#assign>
        
        <#assign extension>
          ${filename?substring(filename?last_index_of('.') + 1)}
        </#assign>
        
        <#assign url>
          <#if extension?trim == "png">
            <@td.pageUrl page="graphic.ftl">
              <@td.urlParam name="projectKey" value="${group.firstResult.projectKey}" />
              <@td.urlParam name="itemKey" value="${group.firstResult.itemKey}" />
            </@td.pageUrl>
          <#else>
            <@td.viewerUrl searchResult=group.firstResult />
          </#if>
        </#assign>
        
        <li><a href="${url}">${group.firstResult.title?html}</a></li>
        
      </#list>
    </ul>
  </#if>
  
  </body>
</html>

Ensure that there is at least one file available to the Portal that has a .png extension. Then, navigate to the URL path /portalUrlPath/search?term=<filename> where filename is the name of one of the png files in your project. That file should come up as a search result and clicking on the link should redirect to the page generated by pngViewer.ftl. Any files returned by the search that do not have a .png extension will link to the regular viewer pages.

Parent topic: Portal Theme Pages