How to insert custom page numbers from the second page using the new ONLYOFFICE API method

ONLYOFFICE macros are powerful tools that allow users to extend the functionality of the editors and customize them to meet specific needs. At ONLYOFFICE, we are committed to continuously enhancing our products with new features. With the release of the version 8.3, we introduced a wide range of new API methods designed to streamline your workflow. In this blog post, we’ll use one of these methods to create a macro that inserts custom page numbers across the entire document, starting from the second page.

About the SetStartPageNumber method

The SetStartPageNumber method is part of the ApiSection class. This new method allows you to define the starting page number for a specific section in a document. Below is an example of its implementation:

let doc = Api.GetDocument();
let paragraph = doc.GetElement(0);
paragraph.AddText("This section starts with second page number");
paragraph.AddPageBreak();
paragraph.AddText("Third page");
paragraph.AddPageBreak();
paragraph.AddText("Fourth page");
let section = paragraph.GetSection();
section.SetStartPageNumber(2);
let header = section.GetHeader("default", true);
paragraph = header.GetElement(0);
paragraph.AddText("Page #");
paragraph.AddPageNumber();
let footer = section.GetFooter("default", true);
paragraph = footer.GetElement(0);
paragraph.AddText("Page #");
paragraph.AddPageNumber();

Later in this blog post, we’ll use this method to set the starting page number for the second page of the document.

Building the macro

Retrieving the document and sections

The macro starts by accessing the active document using Api.GetDocument().
It retrieves the first section using doc.GetSections()[0], which represents the first page:

let doc = Api.GetDocument();
let firstSection = doc.GetSections()[0];

Configuring the first page

// First Page Configuration
firstSection.SetTitlePage(true);
// Remove first page header/footer
firstSection.RemoveHeader("title");
firstSection.RemoveFooter("title");

• SetTitlePage(true) marks the first page as a title page.
• RemoveHeader(“title”) and RemoveFooter(“title”) ensure that no headers or footers appear on the title page.

Setting up subsequent pages

// Subsequent Pages Configuration
let finalSection = doc.GetFinalSection();
finalSection.SetStartPageNumber(0); // Sets start page number. Default is 0 => 1st numbered page is 1

• The finalSection variable represents the section where headers, footers, and page numbering will be applied.
• SetStartPageNumber(0) ensures the numbering starts correctly from the second page, making the first numbered page “1”.

Configuring the header

// Header Configuration
let header = finalSection.GetHeader("default", true);
const headerText = header.GetElement(0);
headerText.AddPageNumber();

// Choose header justification (uncomment one):
//headerText.SetJc("left"); // Left alignment 
headerText.SetJc("center"); // Center alignment 
//headerText.SetJc("right"); // Right alignment

• GetHeader(“default”, true) retrieves a header for the section.
• The header’s first element is accessed using GetElement(0).
• AddPageNumber() inserts a dynamic page number.
• The SetJc() method defines the alignment of the header text, positioning it to the left, center, or right.

Configuring the footer

// Footer Configuration - uncomment for inserting a page number in the footer
let footer = finalSection.GetFooter("default", true);
const footerText = footer.GetElement(0);
footerText.AddPageNumber();

// Choose footer justification (uncomment one):
// footerText.SetJc("left");    // Left alignment
footerText.SetJc("center");  // Center alignment
// footerText.SetJc("right");   // Right alignment

• GetFooter(“default”, true) retrieves a footer for the section.
• The footer’s first element is accessed using GetElement(0).
• AddPageNumber() inserts a dynamic page number in the footer.
• The SetJc() method controls the alignment of the footer text, similar to the header.

Note! By default, the footer configuration is commented out. You can switch between inserting numbering in the header, footer, or both by simply commenting or uncommenting the relevant sections.

The entire macro is the following:

let doc = Api.GetDocument();
let firstSection = doc.GetSections()[0];

// First Page Configuration
firstSection.SetTitlePage(true);
// Remove first page header/footer
firstSection.RemoveHeader("title");
firstSection.RemoveFooter("title");

// Subsequent Pages Configuration
let finalSection = doc.GetFinalSection();
finalSection.SetStartPageNumber(0); // Sets start page number. Default is 0 => 1st numbered page is 1

// Header Configuration
let header = finalSection.GetHeader("default", true);
const headerText = header.GetElement(0);
headerText.AddPageNumber();

// Choose header justification (uncomment one):
//headerText.SetJc("left"); // Left alignment 
headerText.SetJc("center"); // Center alignment 
//headerText.SetJc("right"); // Right alignment

// Footer Configuration - uncomment for inserting a page number in the footer
// let footer = finalSection.GetFooter("default", true);
// const footerText = footer.GetElement(0);
// footerText.AddPageNumber();

// Choose footer justification (uncomment one):
// footerText.SetJc("left");    // Left alignment
// footerText.SetJc("center");  // Center alignment
// footerText.SetJc("right");   // Right alignment

Let’s run our macro and see how it works!

We hope this macro becomes a valuable addition to your toolkit, helping you streamline your workflow. At ONLYOFFICE, we are committed to providing our users with versatile functionality and the flexibility to tailor it to their specific needs.

With the  recent release, we’ve introduced a wealth of new methods to our API library. We encourage you to explore these enhancements and create your own macros. If you have any questions or suggestions, feel free to reach out. Best of luck in your exploratory endeavors!