com.aspose.words

com.aspose.words

Interface IFieldMergingCallback

  • public interface IFieldMergingCallback

Implement this interface if you want to control how data is inserted into merge fields during a mail merge operation.

Example:

Shows how to mail merge HTML data into a document.
public void insertHtml() throws Exception {
    Document doc = new Document(getMyDir() + "Field sample - MERGEFIELD.docx");

    // Add a handler for the MergeField event
    doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldInsertHtml());

    final String htmlText = "<html>\r\n<h1>Hello world!</h1>\r\n</html>";

    // Execute mail merge
    doc.getMailMerge().execute(new String[]{"htmlField1"}, new String[]{htmlText});

    // Save resulting document with a new name
    doc.save(getArtifactsDir() + "MailMergeEvent.InsertHtml.docx");
}

private class HandleMergeFieldInsertHtml implements IFieldMergingCallback {
    /**
     * This is called when merge field is actually merged with data in the document.
     */
    public void fieldMerging(final FieldMergingArgs args) throws Exception {
        // All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
        if (args.getDocumentFieldName().startsWith("html") && args.getField().getFieldCode().contains("\\b")) {
            FieldMergeField field = args.getField();

            // Insert the text for this merge field as HTML data, using DocumentBuilder
            DocumentBuilder builder = new DocumentBuilder(args.getDocument());
            builder.moveToMergeField(args.getDocumentFieldName());
            builder.write(field.getTextBefore());
            builder.insertHtml((String) args.getFieldValue());

            // The HTML text itself should not be inserted
            // We have already inserted it as an HTML
            args.setText("");
        }
    }

    public void /*IFieldMergingCallback.*/imageFieldMerging(ImageFieldMergingArgs args) {
        // Do nothing
    }
}

Example:

Shows how to insert images stored in a database BLOB field into a report.
public void imageFromBlob() throws Exception {
    Document doc = new Document(getMyDir() + "Mail merge destination - Northwind employees.docx");

    // Set up the event handler for image fields
    doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());

    // Loads the driver
    Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");

    // Open the database connection
    String connString = "jdbc:ucanaccess://" + getDatabaseDir() + "Northwind.mdb";

    // DSN-less DB connection
    java.sql.Connection conn = java.sql.DriverManager.getConnection(connString, "Admin", "");

    // Create and execute a command
    java.sql.Statement statement = conn.createStatement();
    java.sql.ResultSet resultSet = statement.executeQuery("SELECT * FROM Employees");

    DataTable table = new DataTable(resultSet, "Employees");

    // Perform mail merge
    doc.getMailMerge().executeWithRegions(table);

    // Close the database
    conn.close();

    doc.save(getArtifactsDir() + "MailMergeEvent.ImageFromBlob.docx");
}

private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback {
    public void fieldMerging(final FieldMergingArgs args) {
        // Do nothing
    }

    /**
     * This is called when mail merge engine encounters Image:XXX merge field in the document.
     * You have a chance to return an Image object, file name or a stream that contains the image.
     */
    public void imageFieldMerging(final ImageFieldMergingArgs e) {
        // The field value is a byte array, just cast it and create a stream on it
        ByteArrayInputStream imageStream = new ByteArrayInputStream((byte[]) e.getFieldValue());
        // Now the mail merge engine will retrieve the image from the stream
        e.setImageStream(imageStream);
    }
}

Method Summary
abstract voidfieldMerging(FieldMergingArgs args)
Called when the Aspose.Words mail merge engine is about to insert data into a merge field in the document.
abstract voidimageFieldMerging(ImageFieldMergingArgs args)
Called when the Aspose.Words mail merge engine is about to insert an image into a merge field.
 

    • Method Detail

      • fieldMerging

        public abstract void fieldMerging(FieldMergingArgs args)
                               throws java.lang.Exception
        Called when the Aspose.Words mail merge engine is about to insert data into a merge field in the document.

        Example:

        Shows how to insert images stored in a database BLOB field into a report.
        public void imageFromBlob() throws Exception {
    Document doc = new Document(getMyDir() + "Mail merge destination - Northwind employees.docx");

    // Set up the event handler for image fields
    doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());

    // Loads the driver
    Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");

    // Open the database connection
    String connString = "jdbc:ucanaccess://" + getDatabaseDir() + "Northwind.mdb";

    // DSN-less DB connection
    java.sql.Connection conn = java.sql.DriverManager.getConnection(connString, "Admin", "");

    // Create and execute a command
    java.sql.Statement statement = conn.createStatement();
    java.sql.ResultSet resultSet = statement.executeQuery("SELECT * FROM Employees");

    DataTable table = new DataTable(resultSet, "Employees");

    // Perform mail merge
    doc.getMailMerge().executeWithRegions(table);

    // Close the database
    conn.close();

    doc.save(getArtifactsDir() + "MailMergeEvent.ImageFromBlob.docx");
}

private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback {
    public void fieldMerging(final FieldMergingArgs args) {
        // Do nothing
    }

    /**
     * This is called when mail merge engine encounters Image:XXX merge field in the document.
     * You have a chance to return an Image object, file name or a stream that contains the image.
     */
    public void imageFieldMerging(final ImageFieldMergingArgs e) {
        // The field value is a byte array, just cast it and create a stream on it
        ByteArrayInputStream imageStream = new ByteArrayInputStream((byte[]) e.getFieldValue());
        // Now the mail merge engine will retrieve the image from the stream
        e.setImageStream(imageStream);
    }
}

        Example:

        Shows how to mail merge HTML data into a document.
        public void insertHtml() throws Exception {
    Document doc = new Document(getMyDir() + "Field sample - MERGEFIELD.docx");

    // Add a handler for the MergeField event
    doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldInsertHtml());

    final String htmlText = "<html>\r\n<h1>Hello world!</h1>\r\n</html>";

    // Execute mail merge
    doc.getMailMerge().execute(new String[]{"htmlField1"}, new String[]{htmlText});

    // Save resulting document with a new name
    doc.save(getArtifactsDir() + "MailMergeEvent.InsertHtml.docx");
}

private class HandleMergeFieldInsertHtml implements IFieldMergingCallback {
    /**
     * This is called when merge field is actually merged with data in the document.
     */
    public void fieldMerging(final FieldMergingArgs args) throws Exception {
        // All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'
        if (args.getDocumentFieldName().startsWith("html") && args.getField().getFieldCode().contains("\\b")) {
            FieldMergeField field = args.getField();

            // Insert the text for this merge field as HTML data, using DocumentBuilder
            DocumentBuilder builder = new DocumentBuilder(args.getDocument());
            builder.moveToMergeField(args.getDocumentFieldName());
            builder.write(field.getTextBefore());
            builder.insertHtml((String) args.getFieldValue());

            // The HTML text itself should not be inserted
            // We have already inserted it as an HTML
            args.setText("");
        }
    }

    public void /*IFieldMergingCallback.*/imageFieldMerging(ImageFieldMergingArgs args) {
        // Do nothing
    }
}

      • imageFieldMerging

        public abstract void imageFieldMerging(ImageFieldMergingArgs args)
                                    throws java.lang.Exception
        Called when the Aspose.Words mail merge engine is about to insert an image into a merge field.

        Example:

        Shows how to insert images stored in a database BLOB field into a report.
        public void imageFromBlob() throws Exception {
    Document doc = new Document(getMyDir() + "Mail merge destination - Northwind employees.docx");

    // Set up the event handler for image fields
    doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());

    // Loads the driver
    Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");

    // Open the database connection
    String connString = "jdbc:ucanaccess://" + getDatabaseDir() + "Northwind.mdb";

    // DSN-less DB connection
    java.sql.Connection conn = java.sql.DriverManager.getConnection(connString, "Admin", "");

    // Create and execute a command
    java.sql.Statement statement = conn.createStatement();
    java.sql.ResultSet resultSet = statement.executeQuery("SELECT * FROM Employees");

    DataTable table = new DataTable(resultSet, "Employees");

    // Perform mail merge
    doc.getMailMerge().executeWithRegions(table);

    // Close the database
    conn.close();

    doc.save(getArtifactsDir() + "MailMergeEvent.ImageFromBlob.docx");
}

private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback {
    public void fieldMerging(final FieldMergingArgs args) {
        // Do nothing
    }

    /**
     * This is called when mail merge engine encounters Image:XXX merge field in the document.
     * You have a chance to return an Image object, file name or a stream that contains the image.
     */
    public void imageFieldMerging(final ImageFieldMergingArgs e) {
        // The field value is a byte array, just cast it and create a stream on it
        ByteArrayInputStream imageStream = new ByteArrayInputStream((byte[]) e.getFieldValue());
        // Now the mail merge engine will retrieve the image from the stream
        e.setImageStream(imageStream);
    }
}