How to Add Online Help

Teradata Employee

How to Add Online Help

This article describes how to include online help with your portlet and how to create a sample help topic.

The Teradata Viewpoint Help System

The Teradata Viewpoint Help System is a dynamic system where help content is assembled from individual portlets and combined into a central help location. The Teradata Viewpoint user accesses the help content by clicking on the ? icon on the upper right-hand corner of the portal.

Clicking the icon opens the help window. Users see help topics based on their portlet security permissions:

The help window is broken up into two sections. The left-hand side displays the Table of Contents (TOC). The right-hand side displays the content. Help content you create must be in HTML format to appear in the content area.

The TOC contains one main topic for each portlet. You can place individual topics beneath the main topic and subtopics under each topic. Each topic and subtopic provides links to HTML content in the content area.

What Kind of Files Do You Create and Where Do They Go?

The Teradata Viewpoint Help System automatically unpacks and deploys your help files with your portlet. For the system to work correctly, your help files need to be structured a certain way.

Create your help documents as HTML files and bundle them in one .zip file. The .zip file should contain:

  • toc.xml (see TOC section below)
  • map.dtd (see attachments section on right side bar)
  • HTML help files
  • Images, if any
  • CSS, files if any

Here is an example of what is contained in the help .zip file for Calendar (note the file structure is flat):

Table of Contents (TOC) structure

Creating the TOC file (toc.xml) is essential to adding online help for Teradata Viewpoint.

The TOC in Teradata Viewpoint Help is structured using an OASIS standard called Darwin Information Typing Architecture (DITA) . This XML standard "builds content reuse into the authoring process for document creation and management." In order to add Teradata Viewpoint online help, you must first create a toc.xml file that adheres to the DITA standard. The DITA DTD schema (map.dtd), against which the toc.xml file is validated, is located on the right side bar in the attachments section of this page.

Here is a sample toc.xml file for the Calendar Portlet:

<?xml version="1.0"?>
<\!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd" \[\]>
<map title="Calendar Online Help" id="calendar">
<topicref navtitle="Calendar" href="calendar.html#calendar" type="concept">
<topicref navtitle="Week View" href="aboutcalendarweekview.html#aboutcalendarweekview" type="concept">
<topicref navtitle="Adding Events" href="addingnewevent.html#addingnewevent" type="task"></topicref>
<topicref navtitle="Month View" href="aboutcalendarmonthview.html#aboutcalendarmonthview" type="concept">
<topicref navtitle="Adding Events" href="addingnewevent.html#addingnewevent" type="task"></topicref>
<topicref navtitle="Event Details" href="aboutcalendareventdetailsview.html#aboutcalendareventdetailsview" type="concept">
<topicref navtitle="Editing Events" href="editingevent.html" type="task"></topicref>
<topicref navtitle="Deleting Events" href="deletingevent.html#deletingevent" type="task"></topicref>

The basic unit of DITA content is <topicref>. Each <topicref> contains a "navtitle," which is the display title of the topic. It also contains "type," where type can be either a concept or a task.

Description of the topic types:

  • Concept: Designed to introduce the subject matter to the reader.
  • Task: Designed to guide the user through a procedure from step 1 to step N, with the end result being the successful completion of the task.

Task topics typically fall under concept topics as subtopics.

Creating Help for Your Portlet

In this section you will complete a series of steps and create basic online help for your portlet.

Note: It is assumed that you have already created HTML help content for your portlet. This procedure only covers creating the Table of Contents (toc.xml) and bundling and saving your portlet help .zip file.

Begin by calling your portlet "Example1".

Step 1: Prepare the help content

Assume we've created 6 HTML content files:

  • example1.html - Main Topic
  • conceptTopic1.html - 1st Topic
  • conceptTopic1TaskTopic1.html - 1st Sub Topic
  • conceptTopic1TaskTopic2.html - 2nd Sub Topic
  • conceptTopic2.html - 2nd Topic
  • conceptTopic2TaskTopic1.html - 2nd Sub Topic
  • common.css - Common CSS file for uniform look and feel
  • map.dtd - DTD Schema for toc file

(You can find the source for the entire example in on the right side bar attachments section)

We've also included a common CSS file (common.css) which contains style elements so you can retain the same look and feel as other Viewpoint portlets.

Step 2: Create the Table of Contents

Creating the Table of Contents is an important part of creating Viewpoint online help. As mentioned in the section above, Viewpoint TOC needs to be structured to DITA format.

Here is the code for our toc.xml:

<?xml version="1.0"?>
<\!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd" \[\]>
<map title="Example1 Online Help" id="example1">
<topicref navtitle="Example1" href="example1.html" type="concept">
<topicref navtitle="Concept Topic 1" href="conceptTopic1.html" type="concept">
<topicref navtitle="Concept Topic 1 - Task Topic 1" href="conceptTopic1TaskTopic1.html" type="task"></topicref>
<topicref navtitle="Concept Topic 1 - Task Topic 2" href="conceptTopic1TaskTopic2.html" type="task"></topicref>
<topicref navtitle="Concept Topic 2" href="conceptTopic2.html" type="concept">
<topicref navtitle="Concept Topic 2 - Task Topic 1" href="conceptTopic2TaskTopic1.html" type="task"></topicref>

After you've created your toc.xml file, save the file with the rest of your help content.

Step 3: Create help ZIP file

Once you've gotten your toc.xml and help content created, the next step is to ZIP up the folder with the content files. We will ZIP up ours and name it

Step 4: Place the help ZIP file in the source directory

We will now place our in the portlet help source directory so it will be extracted and deployed next time you deploy your portlet.

The portlet help source directory is located in:

  • YourPortletName/src/help/YourPortletName/

For example the Calendar help ZIP file is saved in:

  • Calendar/src/help/Calendar/

Step 5: Modify viewpoint-portlet.xml to reflect your help deploy directory

The portlet build system automatically extracts the help zip files you have created in your portlet on deployment.

You need to make sure that this deployment location is correctly reflected in <help-url> in viewpoint-portlet.xml

The viewpoint-portlet.xml is located at:

  • YourPortletName/web/WEB-INF/

Here is the viewpoint-portlet.xml for Calendar. (Note the <help-url> location)

<?xml version="1.0" encoding="UTF-8"?>
<td-portlet id="Calendar" label="Calendar">
<!-- Portlet name MUST be unique, so we use reverse-DNS naming -->
<!-- the context URL at which the webapp is deployed -->
<config-url />

<permission-domain name="Calendar">
<permission scope="domain" name="CREATE_EVENT" description="If granted, the user can create a new event" />
<permission scope="domain" name="EDIT_ANY_EVENT" description="If granted, the user can edit (modify, delete) any event" />
<permission scope="domain" name="EDIT_OWN_EVENT" description="If granted, the user can edit (modify, delete) events created by the user" />
<authorization-statements domain="">
<authorization-statement permissionable="Calendar" permission="ENABLE" role="User" decision="GRANT" />

Set the <help-url> of your portlet to be:

  • <YourPortletName>Portlet/help/<YourPortletName>/toc.html

Step 6: Testing deployment of online help

As mentioned in Step 5, the portlet build system will automatically deploy any help zip files you have created in your portlet. However you can run the extraction process manually for testing by invoking:

  • ant unpack-help

The toc.xml file will be transformed into toc.html via XSTL. The toc.html file is what the user will actually see.

This is what our online help for Example1 looks like after it has been deployed:

Tags (3)