Titania Delivery - Oberon Customer Support and Documentation

1 The `/pages` Directory Structure

The /pages directory contains the templates that are used to render the Portal. Some templates are complete pages while many others are smaller modules meant to be included into a page.

The /pages directory contains the following:

`/`	The root directory contains most of the minimum required pages for the Portal to work properly.
`components/`	The `components/` sub-directory contains templates that are reused among several pages or are used as module on a single page. These components are meant to be "stand-alone", though they may not work properly unless certain other script files or macros are declared in the `<head>` of the containing template. These components can be included on any page by adding `<#include "path/to/component.ftl" />`.
`custom/`	The `custom/` sub-directory contains full-page templates that can be used to extend the functionality of a Portal by adding new pages.
`errors/`	The `errors/` sub-directory contains the required 404 and 500 error pages.
`header/`	The `header/` sub-directory contains templates that can be inserted into the `<head>` of any page. Usually these are convenience templates that group related CSS and JavaScript files together for easy inclusion in other pages.

2 Component Templates

The /pages/components/ directory contains templates that are reused among several pages or are used as module on a single page. These components are meant to be "stand-alone", though they may not work properly unless certain other script files or macros are declared in the <head> of the containing template. These components can be included on any page by adding

<#include
                     "path/to/component.ftl" />

.

comments/

The comments/ sub-directory contains the templates that provide comment functionality on a page. documentCommentThread.ftl will enable commenting on an entire document or page. elementLevelComments.ftl enables commenting on a specific element on a page.

Any page that includes either of these templates must also include the /pages/header/titaniaAnnotator.ftl template.

feedback/

The feedback/ sub-directory contains feedback.ftl. Including this template on a page adds a "Thumbs Up/Thumbs Down" widget to that page. This template is included in viewer.ftl, mapViewer.ftl , and several Custom Templates by default.

This template works seamlessly with the viewer pages listed above. To use this template to collect feedback on other Portal content such as graphics or static html in the page, the page must meet this templates' assumptions. Those assumptions include:

There must be a data-pageId attribute on the <html> element. This value should be universally unique. Default Portal Theme pages accomplish this by setting the value to ${UUID} .
The feedback will be associated with an element that has the id attribute with a value of viewerContent. When including this template on a new page, make sure to specify exactly one element with that ID that will be the target of the feedback.
The feedback target must have an attribute called data-portalKey with the value ${portal.key?html}
The feedback target must have an attribute called data-itemKey. For content in a viewer page, this is set to be that content's key from within its Project. For use on any other Portal content, this value should be set to something unique and descriptive of the element.

footer.ftl

This template contains any information that should be included in the "footer" of the page, such as graphics and copyright information. The footer also contains a QR code that will link to the current page.

genericHeader.ftl

This template is the generic version of header.ftl and is intended for use only on error pages, such as 404.ftl and 500.ftl, or any other page where a full header that includes log-in information, a search bar, and other widgets may not be apporpriate.

header.ftl

This is the header bar for most Portal pages. It inludes the name of the portal and several links. If it is a secured portal it will contain a "log-in" link, a user dropdown (when logged in) and a search bar on all pages except portal-home.ftl.

macros.ftl

This template contains Freemarker macros that simplify the use of some portal tags. See Macros for more information.

qr.ftl

This template places a QR code into the page that will link back to the containing page. It is #includeed into footer.ftl.

searchForm.ftl

This template only appears in searchResults.ftl. It adds a search box to the page which includes all of the search facets available and relevant to the current search results.

watermarks.ftl

This template adds a "Draft" watermark to the background of any page containing content with the metadata draft=true. Additional watermarks can easily be added. For example, add the following to watermarks.ftl:

<#if metadata?? && metadata['test']?? && metadata['test']?seq_contains('true')>
  <div id="watermark">DRAFT</div>
</#if>

Then, add the metadata rule test=true to any content exposed to that Portal. You should now see the "test" watermark in the background.

3 Header Templates

The /pages/header/ directory contains templates that can be inserted into the <head> of any page. Usually these are convenience templates that group related CSS and JavaScript files together, allowing for easy inclusion in other pages.

analytics.ftl: This template allows for connecting a Portal to Google Analytics. A Portal Theme developer could replace the embedded variables to values that would allow them to connect their Portals to their own Google Analytics account.
bootstrap.ftl: This template brings in the Portal Theme's Compiled CSS, as well as the Bootstrap JavaScript libraries.
favicon.ftl: This template brings in the favicon.
harp-sdk.ftl: This template brings in the Harp SDK that provides useful functions for interfacing a Portal with Titania Delivery.

Note: HARP is an internal legacy name for Titania Delivery. As such, some of the APIs referenced in this documentation still use the name HARP in place of Titania Delivery.
jquery.ftl: This template brings in the jQuery JavaScript library that several other Portal Theme .js files depend on.
mobile-meta.ftl: A template that helps mobile browsers display content in a mobile-friendly manner.
titaniaAnnotator.ftl: This template brings in the CSS and JavaScript files required for the Comment Manager.

4 The `/static` Directory Structure

The /pages/static/ directory contains static files available to the website, such as graphics, .less or .css files, JavaScript, and others.

The only file in the top level of the static/ directory is favicon.ico. This file is a graphic that will be displayed in the browser tab of the Portal and will be associated with any bookmarked pages in the portal.

fonts/: This directory contains graphics and other files referenced by CSS and Less. By default, it contains files specific to Bootstrap.
images/: This directory contains graphics and other images placed in a Portal.
scripts/: This directory includes JavaScript files that can be included in portal pages. By default, it only contains bootstrap.min.js, the script file required for Bootstrap plugins to work properly. However, other files can be added.

Note: JavaScript files are not editable from within the browser in version 2.0d and must be edited locally, then uploaded. The ability to edit Javascript from within the browser will be implemented in a later release.
style/: This directory contains the .less .css stylesheets used in the portal. See Less Tips and Tricks for more information.

5 Comment Management

The Titania Comment Manager is a plug-in that allows users to leave comments on Portal content. The default Portal Themes add a comment area to the bottom of any content-containing page. If the content is XML-based, then it is configured to also allow for commenting on any block-level element. Metadata is stored on the comment to map it back to its source document and element.

The Comment Manager allows for collecting feedback directly from Portal users. It is highly configurable to allow for different levels of read and write access, which elements can be commented on, and more. The comments are available via a CSV in the "Reports" Tab of the admin application.

Document-Level comments are those that are left on the entire document, whether it is a static, file such as a PDF or Word document, or dynamic content such as a DITA topic or map. Document-level comments can be included on any page by adding: <#include "components/comments/documentCommentThread.ftl"/> to any template.

Element-level comments are those that can be left on a specific HTML element in the page. In Titania Delivery, these comments are meant to be left on the HTML-transformed version of XML content. Titania Delivery then takes care of mapping the comment back to the element in the source XML, so that comments can be easily identified with their source. Element-level comments can be added to a template via <#include "components/comments/elementLevelComments.ftl"/>.

Commenting is only available to Organization-owned Portals. Attempting to allow commenting on a personal Portal will result in 400-level response codes from the server.

6 Document-Level Comments

Document-level comments are those that are associated with an entire document, and are displayed at the bottom of each content displaying page. Document-level comments are enabled on content by adding

<#include
                     "components/comments/documentCommentThread.ftl"/>

to those pages.

The entire file is wrapped in <#if hasSecurity && portal.hasFeature('docLevelComments')>. This will ensure that Document-level comments will appear in secured portals that have enabled document-level comments. Both of these attributes can be configured in the Portal Administration page.

This template includes the following code:

<#if !user??>
    <#assign pluginUser = {'id': -1, 'userName': 'Anonymous'}>
<#else>
    <#assign pluginUser = user>
</#if>

This code creates a pluginUser variable which is later passed as an option to titaniaAnnotate(). It assigns a dummy user to that variable if a user is not logged in (<#if !user??>). Otherwise, it assigns the currently logged-in user.

To enable Document-level commenting, Titania Delivery passes the following options to the Titania Comment Manager:

 $('#commentContainer').titaniaAnnotate({
  serverUrl: HARPPortal.getPortalRpcUrl('comments'),
  siteKey: '${portal.commentManagerSiteKey?js_string}',
  pageId: 'document:${itemData.item.projectKey?js_string}${itemData.item.projectPath?js_string}',
  author: {
    name: '${pluginUser.userName?js_string}',
    id: '${pluginUser.id?js_string}'
  },
  targetId: 'data-itemKey',
  metadata: {
    xtrf: $('#viewerContent').find('[data-xtrf]').attr('data-xtrf'),
    xtrc: 'root',
    itemKey: '${itemData.item.key?js_string}',
    itemName: '${itemData.item.label?js_string}',
    projectKey: '${itemData.item.projectKey?js_string}',
    portalName: '${portal.name?js_string}',
    portalKey: '${portal.key?js_string}',
    <#if contextMetadata??>
      contextKey : '${contextMetadata.key}',
      contextName: '${contextMetadata.name}',
    </#if>
    modifiedDate: '${itemData.item.lastModified?datetime?iso_utc?js_string}'
  },
  showLoadingIndicator: false,
  hoverClass: '',
  moderators: [<#list moderators as m>'${m?js_string}',</#list>],
  readOnly: ${(!user??)?string}
 });

Of note above:

The values for the following options are given Titania Delivery-specific values and should not be changed to preserve expected functionality:
- serverUrl
- siteKey
- pageId
- author
- moderators
- metadata
hoverClass - As configured in the default themes, Document-level commenting is triggered by clicking a button. As such, it does not make sense to extra visual cues on mouse-over, so this option is left blank.
targetId - The unique identifier for the document being commented on is stored in the data-itemKey attribute. This can be changed in the markup inside this template. If that attribute changes, then this option should be changed accordingly.
metadata - The values provided to the metadata field are used to map a comment back to its source comment. It is not recommended to remove any of the given values. However, any other values may be added.
readOnly - The expression ${(!user??)?string} sets this value to true if a user is not logged in.
metadata.contextKey and metadata.contextName - These values are added to the metadata only if the document is being viewed within the context of a parent ditamap (<#if contextMetadata??>).

7 Element-Level Comments

Element-level comments are those that can be applied to specific HTML elements. With element-level comments, users can click specific content to comment on it. This is best applied to XML-based content. These are enabled on content by adding

<#include
                     "components/comments/elementLevelComments.ftl"/>

to any content-displaying page.

The entire template is wrapped in <#if user?? && portal.hasFeature('elLevelComments')>. This will ensure that element-level comments are only enabled if a user is logged in and the portal has the element-level comments feature enabled. Note that this is subtly different from document-level comments, which require security to be configured but do not require that a user be logged in.

The portal establishes two variables, annotationCandidates and annotationExceptions, which are used to select the annotatable elements. The value passed to annotationCandidates is '[data-xtrc]'. This will select all elements that have a data-xtrc attribute. Titania Delivery places these attributes on all elements that correspond to a source DITA element. Because element-level commenting works best on block-level elements, a list of inline HTML tags (and some others) are passed to annotationExceptions, removing them as annotation candidates. This list can be safely customized and experimented with.

Note: The Titania Annotator plugin will "filter" annotatable elements to prevent nesting. An annotable element nested in another annotable element confuses the UI, and makes it difficult to determine which element the comment was intended for. Therefore, if the plugin detects nested annotatable elements, it will only allow commenting on the parent element.

To enable element-level commenting, Titania Delivery activates the Comment Manager via the following:

$('#viewerContent').find(annotationCandidates).not(annotationExceptions).titaniaAnnotate({
  serverUrl: HARPPortal.getPortalRpcUrl('comments'),
  siteKey:'${portal.commentManagerSiteKey?js_string}',
  pageId: 'elements:${itemData.item.projectKey?js_string}${itemData.item.projectPath?js_string}::${itemData.item.lastModified?datetime?iso_utc?js_string}',
  author: {
    name: '${user.userName?js_string}',
    id: '${user.id?js_string}'
  },
  targetId: function($el) {
    var xtrf = $el.closest('[data-xtrf]').attr('data-xtrf'),
        xtrc = $el.attr('data-xtrc');
    
    return xtrf && xtrc ? xtrf + '#' + xtrc : null;
  },
  metadata: function($element) {
    return {
      xtrf: $element.closest('[data-xtrf]').attr('data-xtrf'),
      xtrc: $element.closest('[data-xtrc]').attr('data-xtrc'),
      itemKey: '${itemData.item.key?js_string}',
      itemName: '${itemData.item.label?js_string}',
      projectKey: '${itemData.item.projectKey?js_string}',
      portalName: '${portal.name?js_string}',
      portalKey: '${portal.key?js_string}',
      <#if contextMetadata??>
        contextKey : '${contextMetadata.key}',
        contextName: '${contextMetadata.name}',
      </#if>
      modifiedDate: '${itemData.item.lastModified?datetime?iso_utc?js_string}'
    };
  },
  moderators: [<#list moderators as m>'${m?js_string}',</#list>]
});

It is not recommended that any of the above values be changed. However, any of the other options available to the Titania Annotator may be customized.

8 Basic Modifications

Changes to a Portal Theme can be made from within the admin application itself via the embedded browser-based code editor. Alternatively, the entire theme could be downloaded to a local computer, edited, and re-uploaded. As soon as the Portal Theme changes in the admin application, those modifications will be reflected in any Portal that uses it.

Modifying the Style

In the admin application, open /static/syle/vars.less. Change the value of @harp-background to black. Then refresh any page in your portal. The refresh will take a moment as the server re-compiles the .less into a new .css file. Once the page reloads, you should see the new color scheme.

Modifying DITA Elements' Style

When rendering DITA content as HTML, Titania Delivery sets the base DITA element type as the class attribute of the output HTML tag. For example, a shortdesc element is transformed into HTML as <div class="shortdesc">...</div>.

To edit these styles, open /static/syle/dita.less in the admin application. On line 5 change this:

color: @harp-primary ! important;

to this:

color: red ! important;

Now view any content in the portal. The title of that content should now be in red-colored font.

Modifying the Templates

In the admin application, open /pages/portal-home.ftl. Find the following markup starting on line 46.

<div class="container">
 <div class="jumbotron">
  <h1>${portal.displayName?html}</h1>
  <p>${portal.description?html}</p>
  .
  .
  .

Add <h1>Hello, Portal!</h1>. Reload the Portal home page and you should see your message.

To do something more interesting, add the line <h1>Hello, ${currentUrl}</h1> instead. The ${} syntax tells Freemarker to replace that text with the data corresponding to the inner variable.

Note: If you do not see your changes after the page refreshes, make sure that the Portal you are viewing uses the Portal Theme you are currently editing.

Modifying the transforms

See Writing XSLT for DITA.

9 One-Page Map Display

The built-in portal themes exercise the ability to display all of the topics in a DITA map or assembly as a single HTML page. The handling of this functionality is slightly different between maps and assemblies.

The td.content portal theme tag carries the expandReferences attribute, which can be used when referencing DITA maps to insert an XML document containing all of the topics in the publication, instead of the flattened DITA map markup. The XML structure for this document is similar to, but not quite the same as, the structure used by the DITA Open Toolkit when rendering PDF output. See the td.content documentation for details.

For DITA maps, the mapViewer.ftl template includes a link to the custom page custom/expandedMap.ftl, which renders the map with the expandReferences flag set.

For Assemblies, the assemblyViewer.ftl tag includes a similar link. However, instead of going to a custom page, it reuses the assemblyViewer.ftl page with a special parameter controlling whether or not to expand references.

In both cases, the monolithic renderings use the /xsl/map/monolith.xsl transformation, which reuses /xsl/topic/topic.xsl, overriding certain things like related-link handling.

10 Bootstrap

By default, all Portal Theme pages come with a CSS framework called Bootstrap, which provides a mobile-friendly experience for the portal. The default Portal Themes utilize the CSS classes and JavaScript modules in Bootstrap to make the Portal responsive, meaning the Portal will allow for the same viewing experience on mobile devices as on a desktop-sized screen.

Bootstrap files are located in /static/scripts/bootstrap.min.js and /static/style/bootstrap. Modifying any Bootstrap files is not recommended. In order for Bootstrap to be used on a page, the page must have the following declared in the <head> section:

   <#include "header/jquery.ftl">
   <#include "header/bootstrap.ftl">

The "included" files above bring in all necessary files.

Bootstrap is an open-source library utilized by Titania Delivery. As such, it is well documented and enjoys a thriving user community. Questions about Bootstrap are often quickly answered by reading the documentation or searching on web forums, such as StackOverflow

As of Titania Delivery v2.0, Bootstrap v3.0.3 is included in the default Portal Themes.

11 macros.ftl

The default Portal Themes contain several Freemarker macros that encapsulate complex operations.

customViewerExtensions: This variable is used inside several of the macros in this template to map a file extension to a particular custom template.
extension: This macro is used to return the filename extension for a given filename.
searchResultUrl: This macro accepts a and generates a url to the page best suited to render it for viewing. If the document has a filename extension that is found in the customViewerExtensions object, then the appropriate custom page is rendered. Otherwise, if it is DITA-based, either viewer.ftl or mapViewer.ftl are used to render the page. If not, the responsibility of rendering will be handed off to the browser's native capability for rendering the given filetype.
searchResultTitle: This macro will return the title for a particular object, meant to be used as the link text. If one exists, a document's searchTitle will be preferred to its title.
searchResultLink: This macro returns a link to a given . It accepts an optional class name that will be set as the class attribute on the generated anchor tag.

Defaut Portal Themes

1 The /pages Directory Structure