How to highlight empty text fields with a specific tip text using an ONLYOFFICE macro

ONLYOFFICE forms make it easy to collect structured input, but empty unrequired fields often go unchecked. In this blog post, we demonstrate how to build a macro that highlights either all empty unrequired fields in a form or only those containing a specific tip text.

Building the macro

1. Retrieve form data and live form objects

The macro starts by accessing the active document using Api.GetDocument(). We then retrieve two sets of information:

• Forms data: Using doc.GetFormsData(), we obtain a JSON representation of all form fields. This JSON includes properties like key, type, value, tip, and whether the field is required.
• Live form objects: We use doc.GetAllForms() to retrieve the live objects corresponding to these form fields.

    var doc = Api.GetDocument();
    var forms = doc.GetAllForms();
    var formsData = JSON.parse(JSON.stringify(doc.GetFormsData()));

2. Optional tip-based validation

Sometimes you might want to check only those empty fields that have a specific tip text. In our macro, you can enable or disable this feature by toggling the checkSpecificTip variable. For example, you may need to validate only fields whose tip reads “Please enter your second address.”

   // Optional: set to true to check only fields with a specific tip text.
    var checkSpecificTip = false;
    var requiredTipText = "Please enter your second address"; // Change this as needed.

3. Loop through each form field

The macro then iterates over each form field in the JSON data. We focus only on text form fields (where the type is “text”). For each text field that is not marked as required, we check if its value is empty.

 forms.forEach(function(form) {
        if (form.GetFormType() === "textForm") {
            var key = form.GetFormKey();
            var required = form.IsRequired()
            // Find corresponding form data by key.
            var formData = formsData.find(function(fd) {
                return fd.key === key;
            });
            if (formData) {
                // A field is considered empty if its value is missing or only whitespace.
                var isEmpty = !formData.value || formData.value.trim() === "";
                // Use the live form's GetTip() to get the tip (if available).
                var tip = form.GetTipText() ? form.GetTipText() : "";
                
                var shouldCheck = !checkSpecificTip || (checkSpecificTip && tip.trim() === requiredTipText.trim());


                if (shouldCheck && isEmpty && !required) {
                    form.SetBorderColor(0,255,127); // spring green border.
                    form.SetBackgroundColor(171, 242, 255); // Light blue background.
                    invalidCount++;
                }
            }
        }
    });

• Checking field value:
  A field is considered empty if its JSON “value” property is missing or only whitespace.
• Tip filtering:
  If checkSpecificTip is enabled, we only check fields whose tip matches the requiredTipText.
• Highlighting:
  For fields that meet the criteria, we find the corresponding live form object (by matching the key) and set a spring green border and a light blue background.

4. Logging the results

Finally, the macro logs the total number of empty unrequired text fields that were highlighted.

console.log("Form Field Validator complete. " + invalidCount + " empty unrequired text field(s) highlighted.");

Complete macro code

(function () {
    // Optional: set to true to check only fields with a specific tip text.
    var checkSpecificTip = false;
    var requiredTipText = "Please enter your second address"; // Change this as needed.


    var doc = Api.GetDocument();
    var forms = doc.GetAllForms();
    var formsData = JSON.parse(JSON.stringify(doc.GetFormsData()));
    var invalidCount = 0;



    forms.forEach(function(form) {
        if (form.GetFormType() === "textForm") {
            var key = form.GetFormKey();
            var required = form.IsRequired()
            // Find corresponding form data by key.
            var formData = formsData.find(function(fd) {
                return fd.key === key;
            });
            if (formData) {
                // A field is considered empty if its value is missing or only whitespace.
                var isEmpty = !formData.value || formData.value.trim() === "";
                // Use the live form's GetTip() to get the tip (if available).
                var tip = form.GetTipText() ? form.GetTipText() : "";
                
                var shouldCheck = !checkSpecificTip || (checkSpecificTip && tip.trim() === requiredTipText.trim());


                if (shouldCheck && isEmpty && !required) {
                    form.SetBorderColor(0,255,127); // spring green border.
                    form.SetBackgroundColor(171, 242, 255); // Light blue background.
                    invalidCount++;
                }
            }
        }
    });
    console.log("Form Field Validator complete. " + invalidCount + " empty unrequired text field(s) highlighted.");
})();

Now, let’s run our macro and see how it works!

This macro automatically detects and highlights empty text fields containing predefined placeholder text, saving time and reducing repetitive work. We hope it proves helpful in optimizing your ONLYOFFICE forms and improving overall workflow efficiency. Don’t hesitate to explore other powerful ONLYOFFICE API methods to automate and enhance your document routine. If you have ideas, questions, or suggestions for future macros, feel free to reach out. We’d love to hear from you. Happy coding!

About the author