Term Help Page

Using the Term Help Page

You can open the term help page by performing one of the following actions:

  • Select a term from the autocomplete dropdown
  • Click a term in the search results

You can use the term help page to get basic information about a term. Your Acrolinx Terminology Manager can fully customize the layout and information in the term help page to meet the requirements of your organization. For example, your administrator can adjust the term help template to add fields, images, and company branding.

The Acrolinx Term Browser displays different search tools with the term help page depending in whether you are in the standard view or the translation view.

Term Help Templates

A term help template defines the appearance of the term help file.The term help file displays key information about a term when users click a help link in the Acrolinx Integration shortcut menu or open a term in the Term Browser. You can preview the appearance of the Term Help page in the Term Browser.

The Default Term Help Template

The Terminology Manager comes installed with a default term help template which uses Acrolinx branding and displays some sample information.

The template is stored in the Acrolinx Server installation directory in the path:

<INSTALL_DIR>\data\common\term_help_template.vm

If you want to change your existing templates or create new templates, create overlay files for the templates in your configuration directory. You create your template overlay files in the following location:

%ACROLINX_CONFIGURATION_ROOT%\data\common

The Term Browser Term Help Templates

If you use the Term Browser, you can also configure separate term help templates for the standard and translation views. Because the Term Browser displays term help a frame, you might use separate templates to adapt the appearance of the term help file when it is viewed in the Term Browser.

You can create separate term help template files by making copies of the default term template with the following names:

standardview_term_help_template.vm

translationview_term_help_template.vm

If these files are not present, the default term help template is used for the standard and translation views.

By default, all template files are stored in the directory:

<INSTALL_DIR>\data\common

If you want to change your existing templates or create new templates, create overlay files for the templates in your configuration directory. You create your template overlay files in the following location:

%ACROLINX_CONFIGURATION_ROOT%\data\common

The Term Help Template Language

The term help templates are based on a Java-based template engine called Velocity. You can find more information about Velocity templates on the Apache Website.

If you create multiple templates and are comfortable with the Velocity template language, you can use velocity directives #include and #parse to minimize the amount of code duplication in your template structure.

 Relative File References

When customizing term help templates it is good practice to ensure that any paths to images or style sheets are relative and can adapt to changes in your server environment. For example, the paths to some files might break if you configure your server to redirect requests to another base URL.

About Term Help Template Variables

You can display the contents of term fields in your term help file by adding the following variables to the term help template:

Field NameVariableDescription
Term Entry ID$termEntryIdDisplays the term entry ID.
Term Entry UUD$termEntryUUIDDisplays the Universally Unique Identifier for the term entry.
Term Entry$termEntry.  <SYSTEM_FIELD_NAME>

$termEntry.customFields.<CUSTOM_FIELD_NAME>

Displays information related to the whole term entry by referring to the attributes of the head term. Use in combination with other variables.

Example: $termEntry.surface

Always use the variable $termEntry in combination with another variable. Do not use the variable $termEntry in isolation. Otherwise, you might display content that has not been protected against cross-site scripting (XSS).
Head Term$isTermEntryIndicates if the term is a head term, by display a true or false value.
Term Name$surfaceDisplays the term name.
Language$languageDisplays the language of the term.
Domains$domainDisplayNamesStringDisplays the domains which the term belongs to.
Status$statusDisplays the term status.
Creation Date$creationDateDisplays the creation date of the term.
Creator User Name$creatorUserNameDisplays the name of the user who created the term.
Last Modification Date$lastModificationDateDisplays the date that the term was last modified.
Last Modifier User Name$lastModifierUserNameDisplays the name of the user who last modified the term.
Term UUID$UUIDDisplays the Universally Unique Identifier for the term.
Term ID$externalIdentifierDisplays the term ID.
Term Database ID$idDisplays the term database ID.
Frequency$frequencyDisplays the frequency of the terms which were imported from an Acrolinx Term Harvesting report.
Linked Terms
#foreach($link in $links)  $link.surface ($link.status) <br/> #end
Displays a list of linked terms with the term status in parentheses.
Custom Fields: Basic Display$customFields.get('<FIELD_NAME>')Displays the contents of any custom field, and can be used multiple times in the term help template.

Use the Field Manager to find the correct field name.

Example:$customFields.get('context')

Custom Fields: Multiple-value
<table>
#foreach($value in $customFields.get('<FIELD_NAME>').getValue())
<tr><td>$value</td></tr>
#end
</table>
Displays all the values for a multiple-choice field in a table with a row for each value.


Example:
<table>
#foreach($value in $customFields.get('products').getValue())
<tr><td>$value</td></tr>
#end
</table>
Test if a custom field has multiple values$customField.isMultiValueCategory()Returns true or false depending on whether the field contains multiple values.

Use this variable in combination with an#if statement.

Comment on this Term
#if ($comments)  <a href="/TermContribution.html?addComment/termDatabaseId/$id" target="blank">Comment on this Term</a> #end
Displays a link to add a comment to the term.
Comments
#foreach($comment in $comments)  <span style="font-weight: bold;">$comment.userName on $comment.date</span>  <p/> $comment.text  <p/> #end 
Displays the comments created for a term.

Adding a Variable to a Term Help Template

You add variables to term help templates to change the content that is displayed to users in the term help file. For example, you might update the term help template so that users can see the source of the term when they review the help information.

To add a variable to a term help template, follow these steps:

  1. Open your overlay of the following file:  term_help_template.vm 

    If you have not yet created an overlay of this file, create a new version of the file at the following location:

    %ACROLINX_CONFIGURATION_ROOT%\data\common

    Do not edit the installed version of the file. Instead, always edit your overlay copy in the configuration directory.

  2. Edit the relevant XHTML code and add your desired variable.

    For example, to update the default template with another table row that displays the term context, add the following line:

    <tr><td class="left">Context:</td><td class="right">$customFields.context</td></tr>

    above the table closing tag: 

    </table>
  3. Save your changes.

    To see your changes, open the Term Help Page for a term.

    Expand the Help Panel, and click the Refresh button.

    Your new field is displayed in the help file.

Configuring the Location of the Term Help Templates

If you plan to make advanced customization to your term help templates, you might want to configure the server to load the templates from a location that is easier for other teams or systems to access.

To change the location of the term help templates, follow these steps:

  1. Open your overlay of the following file:  termbrowser.properties 

    If you have not yet created an overlay of this file, create a new version of the file at the following location:

    %ACROLINX_CONFIGURATION_ROOT%\data\
  2. Add the following property:  

    termhelp.template.root=<DIRECTORY_PATH>

    This property defines the root directory for all template files.

    The file path can be a relative path or absolute path.

    Example:
    termhelp.template.root=P:/resources/shared

    Relative paths are relative to the directory:

    %ACROLINX_CONFIGURATION_ROOT%\data\

    The default value is

    termhelp.template.root=./common
  3. Save your changes and restart the core server.
  4. Reload the term help in your web browser.

    The changes take effect immediately.

Configuring Term Help to Support Comments

As well as contributing new terms, users can also contribute comments to existing terms. Before users can add comments, you must first update your term help template with an Add Comment link.

To display an 'Add Comment' link in your term help file:

  • Add the following lines to your term help template:

    #if ($comments) <a href="/termcontribution.html#addComment/termDatabaseId/$id"  target="blank">Add Comment</a> #end

To display a list of previous comments in your term help file:

  • Add the following lines to your term help template:

    #foreach ($comment in $comments) <span style="font-weight: bold;">$comment.userName on $comment.date</span> <p/>$comment.text <p/> #end