Customize the Term Contributor

Customizing the Term Contribution Page

You can customize the term contribution feature in the following ways:

  • Adapt the term contribution fields to your term validation workflow.
  • Customize the style sheet, which defines the look and feel of the term contribution page to meet the requirements of your organization.

The Term Contribution Template

You can configure the fields on the term contribution page by creating an overlay of the term contribution template and updating the file. The term contribution template is an XML file that is installed to the following location.

<INSTALL_DIR>\data\ common\term_contribution_template.xml

Before you start updating your term help template, create an overlay of the term help template file at the following location:

%ACROLINX_CONFIGURATION_ROOT%\data\ common\term_contribution_template.xml

This section describes which fields you can add to the term contribution template and the XML syntax required to add fields.

Configurable Fields

You can add any custom field and a limited selection of system fields to the term contribution template.

Some system fields are compulsory for the term contribution feature to function correctly. Compulsory fields always appear on the term contribution page even if they aren’t included in the term contribution template. 

The following table lists the system fields that are applicable to term contribution page:

Field NameUsed toCompulsory?
SURFACEEnter the term name.Yes
LANGUAGESelect the term languageYes
DOMAINSelect a domain for the term.Yes
COMMENTEnter a comment.No
STATUSView or select the term status.No
EXTERNAL_ID

View or enter a custom identifier for the term.

In the Terminology Manager interface, this field is referred to as theTerm ID.
No
To ensure that contributors enter terms with one specific language and domain, ensure that the language and domain fields have the desired default values and set those fields to be read only.

The Default Field Order

The following table shows the default order of fields on the term contribution page:

PositionFieldComments
1SURFACEThe term name must always the first field on the term contribution page.
2LANGUAGEIf they aren’t defined in the term contribution template, the Language andDomain fields appear after the term name.

If you add language or domain to the term contribution template, those fields appear in the order that they’re added.

3DOMAIN
4Custom Fields

Custom fields are listed in the order that they’re defined in the term contribution template.


Adding or Removing Fields

To add or remove a field on the term contribution page, follow these steps:

  1. Open your overlay of the following file: term_contribution_template.xml 

    If you haven’t yet created an overlay of this file, create a new version of the file at the following location:

    %ACROLINX_CONFIGURATION_ROOT%\data\ common

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

  2. Add or remove a field reference.

    To add a field, locate the <fields> section and add one or more of the following lines:

    • <customfield name="[FIELD_INTERNAL_NAME]"/> to display a custom field.
    • <uifield name="COMMENT"/> to add a Comment field.

      Your users can update this field to explain why they’re contributing the term. Users can also add further comments on the Add comment page.

    • <systemfield name="[FIELD_NAME]"/> to display a system field.
      Fastpath: You can find the system field names in the topic Configurable Fields.

    Example:

    <?xml version="1.0" encoding="UTF-8"?> <termcontributor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <fields> <custom field name="imageURL"/> <systemfield name="STATUS"/> <uifield name="COMMENT"/> </fields> </termcontributor>

    To remove a field, remove the line corresponding line from the term contribution template.

  3. Save your changes.

    The changes take effect when you refresh the term contribution page.

Restricting the Available List Items for a Field

In some circumstances, you may want to limit the range of list items available in a specific list field.

For example, your terminology database may store terms in ten different languages, but you only want to allow terms to be contributed in two of the possible languages, such as English and German.

To restrict the available list items a list field, follow these steps:

  1. Open your overlay of the following file: term_contribution_template.xml 

    If you haven’t yet created an overlay of this file, create a new version of the file at the following location:

    %ACROLINX_CONFIGURATION_ROOT%\data\ common

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

  2. Locate the relevant section for your field and add the <range> element.

    Use the following example for the language field as a basis:

    Example:

    <systemfield name="LANGUAGE"> <range> <value>English</value> <value>German</value> </range> </systemfield>
  3. Save your changes.

    The changes take effect when you refresh the term contribution page.

Setting Default Values for a Field

You can set default values for term-related fields both in the Terminology Manager and in the term contribution template. Any default values defined in the term contribution template override the defaults defined in the Terminology Manager.

Setting default values in the term contribution template can be useful if you want term contributors to use different default values than standard Terminology Manager users.

A default value can be the following:

  • Default text that appears in a text box
  • A list item that is initially selected in a dropdown field

To set a default value for a field, follow these steps:

  1. Open your overlay of the following file: term_contribution_template.xml 

    If you haven’t yet created an overlay of this file, create a new version of the file at the following location:

    %ACROLINX_CONFIGURATION_ROOT%\data\ common

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

  2. Locate the relevant section for your field and add the <default> element.
    • Examples for a system list field and a custom list field:


      <systemfield name="STATUS"> <range> <value>proposed</value> </range> <default>proposed</default> </systemfield>
      
      <customfield name="workflowstep"> <range> <value>new submission</value> <value>repeat submission</value> </range> <default>new submission</default> </systemfield>
    • Example for a multiple-choice list field that has two default values:


      <customfield name="applicableProducts"> <range> <value>Turbo Widget 1000</value> <value>Ultra Widget 5000</value> <value>Over 9000 Deluxe</value> <value>CarterTron 2020</value> </range> <default>Turbo Widget 1000</default> <default>Ultra Widget 5000</default> </customfield>
    • Example for a text field:

      <customfield name="note"> <default>This is some default text.</default> </customfield>
    • Example for a text field that has default text in the Terminology Manager and but should be blank on the term contribution page:

      <customfield name="note"> <default/> </customfield>
  3. Save your changes.

    The changes take effect when you refresh the term contribution page.

Defining Fields as Required, Read Only or Invisible

You can change the behavior of a field by adding specific attributes to your term contribution or add comment template.

  • To ensure that users complete the field before submitting the form, configure the field as required.
  • To ensure that users can see the value of a field but not change it, configure the field as read only.
  • If you don’t want users to see the field but want to ensure that a default value is always saved for the term, configure the field as invisible

To define fields as required, read only or invisible, follow these steps:

  1. Open your overlay of the following file: term_contribution_template.xml (to edit the term contribution template) oradd_comment_template.xml (to edit the add comment template) 

    If you haven’t yet created an overlay of this file, create a new version of the file at the following location:


    %ACROLINX_CONFIGURATION_ROOT%\data\ common
    

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

  2. Locate the relevant section for your field.
    • To configure the field as required, add the attribute required="true".

      Use the following example for the 'definition' field as a reference:

      <custom field name="definition" required="true"/>
    • To configure the field as read only, add the attribute readonly="true".

      Use the following example for the 'status' field as a reference:

      <systemfield name="STATUS" readonly="true"> <default>proposed</default> </systemfield>
    • To configure the field as invisible, add the attribute invisible="true".

      Use the following example for the 'project' field as a reference:

      <customfield name="project" invisible="true"> <default>Test</default> </customfield>
  3. Save your changes.

    The changes take effect when you refresh the term contribution or add comment page.

Customizing the Styling for the Term Contribution Page

You can customize the look of the term contribution page and adapt it to the look and feel of your organization. For example, you can change the image and logo in the page header.

Important: This task requires knowledge of web design and the structure of CSS files.

To customize the view of the term contribution page, follow these steps:

  1. Open your overlay of the following file: TermContribution.css 

    If you haven’t yet created an overlay of this file, create a new version of the file at the following location:

    %ACROLINX_CONFIGURATION_ROOT%\server\www\ gwt\css

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

  2. Edit the file according to your requirements.
  3. Save your changes.
    Your changes take effect after you reload the term contribution page.

Customizing the Field Size

You might need to change the size of the displayed fields, for example if users often contribute long terms or the standard field size is insufficient.

To change the field size, follow these steps:

  1. In the Dashboard, open the Field Manager (Home Terminology Customize Field Manager).
  2. Click on the Name, edit the Text field size (chars), and Save the changes.

Logging and Fallback Behavior

Logging

All configuration issues with the term contribution template are logged in the core server log file.

A configuration issue can occur when you perform one of the following actions:

  • Adding a field, which doesn’t exist in the terminology database.
  • Adding a field, which isn’t configurable.
  • Adding <default> or <range> elements, which reference list items that don’t exist in the terminology database.

 Fallback Behavior

  • If an optional field has a configuration issue, the field isn’t displayed on the term contribution page
  • If there’s an issue with list items configured for the Language or Domain fields, those fields revert to their default state.

    In their default state, the Language and Domain fields are editable, and the dropdowns display the full range list items as configured in the category manager.

  • If term contribution template is missing or cannot be parsed, the term contribution page displays the minimum list of compulsory fields.