Portal Themes

The Titania Default Theme

When the Titania platform is initially configured, a portal theme named "Titania Default Theme" is created in the root user's organizataion. This theme is available for use by all portals.

Titania Delivery releases may include updates to the default theme. Changes to the default theme are not automatically added to the existing Titania Default Theme. However, the current default theme is available on any TD platform (version 4.5.0 and above) at the URL /resources/td-default-theme. This theme may be used to update the platform default theme, or as a source for updating custom themes.

The pages Folder

The pages folder contains the Freemarker templates used to draw the application pages required for all Titania Delivery portals to function. Within this folder, the following template files are required:

• portal-home.ftl - The portal homepage template.
• searchResults.ftl - The search results template.
• viewer.ftl - The page displaying a topic in the context of a DITA map.
• mapViewer.ftl - The page displaying a map or standalone topic.
• filtered.ftl - The page to display when a user attempts to access content that does not match the portal's metadata filters.

You're free to use the Freemarker <#include> tag to break these pages down into smaller reusable components, but these are the minimum templates required for the Titania Delivery portal to function.

The Freemarker template language allows the use of JSP tag libraries, of which Titania Delivery allows two:

• The JSP Standard Tag Library (JSTL).
• The Titania Delivery Portal tag library. Documented in the Developer’s guide.

To use a tag library, include code like the following at the top of the template file:

<#assign harp=JspTaglibs['http://www.titaniasoftware.com/harp/taglib'] />
<#assign c=JspTaglibs['http://java.sun.com/jsp/jstl/core'] />

The static Folder

The static folder contains files, such as images, Javascript file, and CSS or LESS stylesheets.

Titania Delivery natively supports CSS stylesheets written in LESS, which is a CSS-like language that provides many convenience features, such as variables and reusable style sets, that make it much easier to author and manage than traditional CSS. Any file with a .less extension will automatically be converted to CSS when it is requested by a page using the <@harp.themeFileUrl> tag.

Files in the `static` folder can be accessed from pages using the themeFileUrl tag from the Titania Delivery JSP tag library. For example, the following tag can be used to address the file /static/images/myImage.png:

<img src="<@harp.themeFileUrl value="/images/myImage.png" />">

If using a config.xml and portal parameters to store paths to theme files, it's recommended to place theme files in specific subfolders within the static folder. This will reduce the number of choices to only relevant files when modifying theme file parameters.

The xsl Folder

The Titania Delivery tag library includes a <@harp.content> tag, which renders XML content from a Titania Delivery project into a portal webpage, optionally transforming it with an XSLT stylesheet from the portal theme's xsl folder.

The full functionality of the <@harp.content> tag is outside the scope of this document, but for now an example should suffice.

<@harp.content url=itemUrl contextUrl=contextHarpUrl
  xsl="/topic/topic.xsl" />

This content tag will render the topic identified by the url attribute, as it exists as a member of the map identified by the given contextUrl attribute, and transform it to HTML using the /xsl/topic/topic.xsl file from the portal's theme.

Using config.xml

The config.xml file introduces parameters which are associated with the portal object. Parameters may be of the following types:

• <string> - Used for a one-line string of text
• <text> - Used for larger amounts of text, with three possible formats
  • type="html" - Text is interpreted as entered
  • type="markdown" - Text is converted to valid markdown
  • type="text" - Any HTML characters are escaped
• <number> - Used to represent a numerical value
• <checkbox> - Used to represent a boolean value
• <select> - Used to select options from a group
  • multi="true" - Select an array of options (including order) from a set
  • multi="false" - Select a single option from a set (the same effect can be achieved by omitting the @mutli attribute)
• <themeFile> - Used to represent the location of a file used in the theme
• <linkList> - Used to represent a list of links that are used in the theme

If included at the root level of a portal theme, the config.xml file will be used to generate a form in the Details tab of a portal the theme is associated with. The data in this form can be modified to change the value of the parameters associated with that portal, the defaults for the theme are not changed.

All parameters require a @name attribute which is used to access them from the portal theme's page templates. The @labelattribute is also recommended and supplies an external label for the parameter, while authors can hide a parameter (and force each portal to use its default value) by setting the @hidden attribute to true.

@default is used to define default values for the parameters (excluding those of type text, select, and linkList). Defaults for select elements are define by setting the @default attribute on the options desired within the select tag. Defaults for text elements are defined by a separate <default> tag within the <text> tag. The @default attribute should be included if possible when writing your config.xml, but is not required.

These parameters must be defined in config.xml, but may be used anywhere in the portal theme's page templates. Access to these parameters is gained by using the parameters collection on the portal object. For example, if using a parameter named "stylesheet", it would be accessed as portal.parameters.stylesheet.

<link rel="stylesheet"¬·href="<@td.themeFileUrl value="${portal.parameters.stylesheet}" />"/>

See the Developer's Guide for more information on portal theme parameterization.