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 execute a mail merge with a custom callback that handles merge data in the form of HTML documents.
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.
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.
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 execute a mail merge with a custom callback that handles merge data in the form of HTML documents.
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.
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);
    }
}

See Also:
          Aspose.Words Documentation - the home page for the Aspose.Words Product Documentation.
          Aspose.Words Support Forum - our preferred method of support.