Mastering ONLYOFFICE version 8.0: Unveiling new Document Builder API form methods

Originally published at: Mastering ONLYOFFICE version 8.0: Unveiling new Document Builder API form methods | ONLYOFFICE Blog


With the unveiling of version 8.0, a set of new Document Builder API methods has been introduced. In this blog post, we will delve into two of these methods and demonstrate how to incorporate them into two fresh ONLYOFFICE macros, streamlining the experience of working with form templates.

Mastering ONLYOFFICE version 8.0: Unveiling new Document Builder API form methods

About new methods

  • GetFormsData

The GetFormsData method retrieves an array encompassing form data for all form elements featured within the document.

expression.GetFormsData();

Where expression is a variable that represents the ApiDocument class.

By utilizing this method, you can retrieve targeted data from forms in a document, allowing you to dynamically modify forms based on their types and properties.

  • SetFormsData

Contrary to the earlier method, the SetFormsData does not return any data. However it allows us to set the value of the form elements.

expression.SetFormsData();

Where expression is a variable that represents the ApiDocument class.

The method parameters are passed in the format of the FormData array where the form key and value are specified. Additionally, there is an option to specify the form type.

By employing this method, you can easily define default values for all relevant form elements, automating the dynamic document editing.

Macro for modifying text fields: GetFormsData implementation

This nifty macro provides the ability to modify all text fields in the document. Also it can be customized for making changes to other form types.

First we target the active document:

const oDocument = Api.GetDocument();

Then we retrieve an array(aForms) containing all the form elements present in the document.

const aForms = oDocument.GetAllForms();

After that we collect data about all the forms in the document and store it in the formsData variable:

const formsData = oDocument.GetFormsData();

Then we add a loop that iterates through each form element in the array:

for (let i = 0; i < aForms.length; i++) {
}

We check if the type of the current form is “text.” If true, in the subsequent lines we make changes to the form elements:

if (formsData[i]["type"] == "text") {
  //aForms[i].SetBackgroundColor(205, 0, 0); // <---- Sets/Changes the Background Color of all the form elements.
  //aForms[i].SetBorderColor(205, 0, 0);       //<---- Unccomment if you want to set/change the border color for all the form elements.
  //aForms[i].SetPlaceholderText("Placeholder Text");       //<---- Unccomment if you want to set/change the Placeholder Text for all the form elements.
  //aForms[i].SetRequired(true);          //<---- Unccomment if you want to set/change the 'required' property for all the form elements.
  //aForms[i].SetTipText("Tip Text");       //<---- Unccomment if you want to set/change the Tip Text for all the form elements.
}

Here, each line is commented with a description of the action it performs.

The entire macro code is the following:

(function() {
  const oDocument = Api.GetDocument();
  const aForms = oDocument.GetAllForms();
  const formsData = oDocument.GetFormsData();

for (let i = 0; i < aForms.length; i++) {
if (formsData[i][“type”] == “text”) {
// Uncomment the following lines based on your preferences:
// aForms[i].SetBackgroundColor(205, 0, 0); // Sets/Changes the Background Color of all the form elements.
// aForms[i].SetBorderColor(205, 0, 0); // Uncomment if you want to set/change the border color for all the form elements.
// aForms[i].SetPlaceholderText(“Placeholder Text”); // Uncomment if you want to set/change the Placeholder Text for all the form elements.
// aForms[i].SetRequired(true); // Uncomment if you want to set/change the ‘required’ property for all the form elements.
// aForms[i].SetTipText(“Tip Text”); // Uncomment if you want to set/change the Tip Text for all the form elements.
}
}
})();

Macro for setting default form values: SetFormsData implementation

By using the second macro, we can easily and seamlessly adjust the values of the targeted forms. The macro is rather simple and can be done in just a few steps.

First we retrieve the active document:

const oDocument = Api.GetDocument();

Next, we employ the SetFormsData method, where we define the element key and the desired default value within the method parameters:

oDocument.SetFormsData([
  {key: "CompanyName", value: "OnlyOffice"}
]);

The entire macro code is the following:

The entire macro code is the following:
const oDocument = Api.GetDocument();
oDocument.SetFormsData([
  {key: "CompanyName", value: "OnlyOffice"}
]);

We hope the showcased methods and macros prove valuable to you, streamlining document workflow. Macros serve as powerful tools and our extensive API library offers a myriad of possibilities for automating various tasks.

Feel free to delve into our API, crafting personalized macros that harness the robust features of document processing. Don’t hesitate to reach out to us, sharing your innovative ideas. We welcome open discussions and collaboration. Best of luck in your exploratory endeavors!

Useful links

Free office suite

Learn more about the GetFormsData method

Learn more about the SetFormsData method

OFORMS libriary

Other useful macros