Customize the Term Help Page

Use the Term Help Page

The term help page gives you basic information about a term. You'll find a term help page for each term in the Terminology section of the Acrolinx Dashboard.

To open the term help page, do of the following actions:

Select a term from the autocomplete dropdown.

Click a term in the search results.

You'll then find the term help page for the term or terms under Terms.

It's possible to fully customize the layout and information in the term help page to meet the requirements of your organization. For example, you 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 on whether you are in the standard view or the translation view.

Tip

If you're on an Acrolinx Private Cloud instance and are interested in these configurations, contact us and we'll set them for you!

Configuration Steps for Standard Stack

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. If you want to change your existing templates or create new templates, create overlay files for the templates in your configuration directory.

To create your template overlay files in the follow these steps:

We recommend saving a copy of the default template to the location <config directory>/data/common.

Open your command line and enter the following command:

kubectl cp -n acrolinx acrolinx-core-server-0:/opt/guidance/<path> /home/acrolinx/config/<path>

For example, your command might look like this:

kubectl cp -n acrolinx acrolinx-core-server-0:/opt/guidance/data/common/term_help_template.vm <config directory>/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’s 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 aren’t present, the default term help template is used for the standard and translation views.

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

<config directory>/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:

<config directory>/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’s 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 Name and Variable

Description

Term Entry ID

$termEntryId

Displays the term entry ID.

Term Entry UUD

$termEntryUUID

Displays 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

Note

Always use the variable $termEntry in combination with another variable. Don't use the variable $termEntry in isolation. Otherwise, you might display content that hasn’t been protected against cross-site scripting (XSS).

Head Term

$isTermEntry

Indicates if the term is a head term, by display a true or false value.

Term Name

$surface

Displays the term name.

Language

$language

Displays the language of the term.

Domains

$domainDisplayNamesString

Displays the domains that the term belongs to.

Status

$status

Displays the term status.

Creation Date

$creationDate

Displays the creation date of the term.

Creator Username

$creatorUserName

Displays the name of the user who created the term.

Last Modification Date

$lastModificationDate

Displays the date that the term was last modified.

Last Modifier Username

$lastModifierUserName

Displays the name of the user who last modified the term.

Term UUID

$UUID

Displays the Universally Unique Identifier for the term.

Term ID

$externalIdentifier

Displays the term ID.

Frequency

$frequency

Displays the frequency of the terms that were imported from an Acrolinx Term Discovery 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:

Open your overlay of the following file:term_help_template.vm

Warning

Don’t edit the installed version of the file. Instead, always edit your overlay copy in the configuration directory.
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>
```
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.

Configure 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:

Open your overlay of the following file:termbrowser.properties

Warning

Don’t edit the installed version of the file. Instead, always edit your overlay copy in the configuration directory.

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:

                                 <config directory>/data/

The default value is

termhelp.template.root=./common

Save your changes and restart the core server.
Reload the term help in your web browser.

The changes take effect immediately.

Configure Term Help to Support Comments

As well as contributing 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: