Metadata Script

The Script field allows executing custom JavaScript code to implement dynamic behaviors in metadata forms.

This field can interact with form elements such as:

Input
CheckBox
Select
TextArea

Attribute	Description	Required
label	The text is shown as a label in the user interface. Although this field has a label attribute, it is typically not displayed in the UI since scripts execute in the background. However, it’s useful for administrative purposes and documentation.	true
name	Unique field identifier. Two metadata items can’t have the same name. The name must be unique. The name must start with “okp:”. Using the metadata group name as the basis for the metadata field name is a good practice. For example, using “okg:consulting” for the group name results in the field name “okp:consulting.script” by changing “okg” to “okp”. That helps to find the metadata group based on the metadata field name. Please use only letters, numbers, and underscores: “0-9a-zA-Z_”.	true
source	Path to the JavaScript file to be executed. The file must be located in the plugins directory. The JavaScript file must be placed in the plugins directory of the OpenKM installation. For example: /opt/openkm/tomcat/plugins/metadata_script.js The script is loaded and executed after the form is rendered, allowing it to access and manipulate form elements.	true
value	An optional initial value or data passed to the script. Accessible within the script at runtime.	false

Interacting with form fields:
The script can interact with other metadata fields using their names as the element IDs. Form fields that can be accessed include:
Additionally, each form field row can be accessed using the prefix “row-” followed by the field name.

Basic Example

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.15//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.15.dtd">
<property-groups>
  <property-group label="Consulting" name="okg:consulting">
    <input label="Input label" name="okp:consulting.input1" />
    <separator label="Separator label" name="okp:consulting.separator" />
    <input label="Input label" name="okp:consulting.input2" />
    <script label="Script label" name="okp:consulting.script" source="metadata_script.js" />
  </property-group>
</property-groups>

JavaScript Example

Example of a script file (metadata_script.js) that demonstrates interaction with form fields:

(function() {
  alert('loading');
  const input = document.getElementById('okp:consulting.input1');
  const row = document.getElementById('row-okp:consulting.input1');
  if (input) {
    input.value = 'modified';
    // Trigger the input event so Vue detects the change
    input.dispatchEvent(new Event('input', { bubbles: true }));

    // Add event listener to detect changes
    input.addEventListener('input', function(event) {
      if (event.target.value.length === 10) {
        alert('Text length greater than 10 characters');
      } else if (event.target.value.length === 11) {
        row.style.display = 'none'; // hide the field
      }
    });
  }
  alert('loaded');
})();

Common Use Cases

Best Practices