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.
You can configure the fields on the term contribution page by creating an overlay of the term contribution template and updating the file.
Before you start updating your term help template, create an overlay of the term help template file at the following location: <config directory>/data/common/term_contribution_template.xml
To do this, 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_contribution_template.xml <config directory>/data/common
This section describes which fields you can add to the term contribution template and the XML syntax required to add 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 Name |
Used to |
Compulsory? |
---|---|---|
SURFACE |
Enter the term name. |
Yes |
LANGUAGE |
Select the term language |
Yes |
DOMAIN |
Select a domain for the term. |
Yes |
COMMENT |
Enter a comment. |
No |
STATUS |
View or select the term status. |
No |
EXTERNAL_ID |
View or enter a custom identifier for the term. TipIn the Terminology Manager interface, this field is referred to as the Term ID. |
No |
Tip
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 following table shows the default order of fields on the term contribution page:
Position |
Field |
Comments |
---|---|---|
1 |
SURFACE |
The term name must always the first field on the term contribution page. |
2 |
LANGUAGE |
If they aren’t defined in the term contribution template, the Language and Domain 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. |
3 |
DOMAIN |
|
4 |
Custom Fields |
Custom fields are listed in the order that they’re defined in the term contribution template. |
To add or remove a field on the term contribution page, follow these steps:
-
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:
<config_directory>/data/common
Don’t edit the installed version of the file. Instead, always edit your overlay in the configuration directory.
-
Add or remove a field reference.
To add a field, locate the
<fields>
section and add one or more of the following lines:-
To add a custom field:
<customfield name="[FIELD_INTERNAL_NAME]"/>
What is a field's internal name?
The field name that you see displayed on the term contribution page can be different from that field's internal name.
To find a custom field's internal name:
-
In the Dashboard, go to Terminology > Customization > Field Manager.
-
Click on the field. In the dialog box that appears, the internal name is the “Field name”. Field names are case sensitive.
-
-
To add a comment field:
<uifield name="COMMENT"/>
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.
-
To add a system field:
<systemfield name="[FIELD_NAME]"/>
Tip
You can find the system field names in the section Configurable Fields . Field names are case sensitive.
Example
<termcontributor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <fields> <customfield name="imageURL"/> <systemfield name="STATUS"/> <uifield name="COMMENT"/> </fields> </termcontributor>
To remove a field, remove the corresponding line from the term contribution template.
-
-
Save your changes. The changes take effect when you refresh the term contribution page.
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 10 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:
-
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:
<config_directory>/data/common
Don’t edit the installed version of the file. Instead, always edit your overlay in the configuration directory.
-
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>en</value> <value>de</value> </range> </systemfield>
-
Save your changes.The changes take effect when you refresh the term contribution page.
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:
-
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:
<config_directory>/data/common
Don’t edit the installed version of the file. Instead, always edit your overlay in the configuration directory.
-
Locate the relevant section for your field and add the <default> element.
-
Examples for a system list field and a custom list field:
Example
<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:
Example
<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:
Example
<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:
Example
<customfield name="note"> <default/> </customfield>
-
-
Save your changes. The changes take effect when you refresh the term contribution page.
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:
-
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:
<config_directory>/data/common
Don’t edit the installed version of the file. Instead, always edit your overlay in the configuration directory.
-
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:
Example
<customfield 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:
Example
<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:
Example
<customfield name="project" invisible="true"> <default>Test</default> </customfield>
-
-
Save your changes. The changes take effect when you refresh the term contribution or add comment 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.
Note
Important: This task requires knowledge of web design and the structure of CSS files.
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:
-
In the Dashboard, open the Field Manager (Home > Terminology > Customize > Field Manager).
-
Click on the Name, edit the Text field size (chars), and Save the changes.
To customize the view of the term contribution page, follow these steps:
-
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:
<config directory>/server/www/gwt/css
Don’t edit the installed version of the file. Instead, always edit your overlay in the configuration directory.
-
Edit the file according to your requirements.
-
Save your changes.
Your changes take effect after you reload the term contribution page.
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.
-
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.