Advanced Features

This page covers some more advanced features and techniques available in Office-stamper.

Headers and Footers

The .docx file format doesn’t permit comments within headers or footers. Office-stamper provides a workaround for this limitation:

  1. Craft the expression as you would in a comment
  2. Encapsulate it with "#{}".
  3. Position it at the beginning of the paragraph you want to manipulate.

Example:

#{displayParagraphIf(showPageNumbers)} Page ${pageNumber} of ${totalPages}

This allows you to conditionally display content or repeat elements in headers and footers.

Preprocessors

Preprocessors allow you to perform operations on the document before the stamping process begins. This can be useful for document preparation, validation, or setting up complex transformations.

Standard preprocessors are available in the pro.verron.officestamper.preset.Preprocessors class. You can also implement the pro.verron.officestamper.api.PreProcessor interface for custom logic.

void main(String[] args){
    // Create a custom preprocessor
    class CustomPreprocessor implements PreProcessor {
        @Override
        public void process(WordprocessingMLPackage document) {
            // Perform operations on the document before stamping
        }
    }

    // Add the preprocessor to the configuration
    var configuration = OfficeStamperConfigurations.standard();
    configuration.addPreprocessor(new CustomPreprocessor());
}

Post Processors

Post-processors allow you to perform additional operations after the stamping process is complete. This can be useful for cleaning up the document or adding summaries.

Standard post-processors are available in the pro.verron.officestamper.preset.Postprocessors class. You can also implement the pro.verron.officestamper.api.PostProcessor interface for custom logic.

void main(String[] args){
    // Create a custom post processor
    class CustomPostProcessor implements PostProcessor {
        @Override
        public void process(WordprocessingMLPackage document) {
            // Perform operations on the document after stamping
        }
    }

    // Add the post-processor to the configuration
    var configuration = OfficeStamperConfigurations.standard();
    configuration.addPostProcessor(new CustomPostProcessor());

    // Use a standard post-processor to remove engine-specific tags
    configuration.addPostProcessor(Postprocessors.removeTags("placeholder"));
}

Working with Footnotes and Endnotes

As of version 2.7.0, Office-stamper is aware of footnotes and endnotes. With the standard() configuration, it cleans orphaned notes automatically.

Future versions may include more comprehensive support for stamping within footnotes and endnotes.

Handling Complex Tables

Dynamic Table Generation

The resolveTable comment processor allows you to dynamically generate tables from data:

resolveTable(report.dataTable)

Where report.dataTable is an instance of StampTable that contains: - A list of headers for columns – A 2-level list of rows containing values for each column.

Table Row Repetition

For tables with existing structure, you can use the repeatTableRow processor:

repeatTableRow(employees)

This will repeat the row for each item in the collection, evaluating expressions within the cells against each item.

Document Parts

The repeatDocPart processor allows you to repeat more complex structures that may include multiple paragraphs, tables, or other elements:

repeatDocPart(chapters)

This is more flexible than repeatParagraph or repeatTableRow when you need to repeat larger sections of your document.

Conditional Display

Office-stamper provides a rich set of conditional display options:

// Basic boolean condition
displayParagraphIf(customer.vip)
displayTableRowIf(order.items.size() > 0)
displayTableIf(report.hasData())

// Check if object is present
displayParagraphIfPresent(customer.address)
displayTableRowIfPresent(order.discounts)
displayTableIfPresent(report.data)
displayWordsIfPresent(customer.middleName)
displayDocPartIfPresent(chapter.summary)

// Check if object is absent
displayParagraphIfAbsent(customer.address)
displayTableRowIfAbsent(order.discounts)
displayTableIfAbsent(report.data)
displayWordsIfAbsent(customer.middleName)
displayDocPartIfAbsent(chapter.summary)

Working with Images

Office-stamper can insert images into documents using the Image class:

void main(){
    // Create an image from a file
    var image = new Image(new File("path/to/image.jpg"));

    // Or from a byte array
    var image = new Image(imageByteArray);

    // Customize the image
    image.setWidth(400);  // Width in points
    image.setHeight(300); // Height in points

    // Use in your context object
    class ReportContext {
        public Image getLogo() {
            return image;
        }
    }
    // In the template: ${logo}
}

Performance Considerations

For large documents or batch processing, consider the following:

  1. Reuse configuration: create the configuration once and reuse it for multiple stamping operations.
  2. Minimize context size: keep your context objects as small as possible.
  3. Use efficient data structures: prefer lists to sets or maps when order matters.
  4. Consider memory usage: for large documents, monitor memory usage and consider processing in chunks.

Next Steps