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 insert images stored in a database BLOB field into a report.
public void mailMergeImageFromBlob() throws Exception
{
    Document doc = new Document(getMyDir() + "MailMerge.MergeImage.doc");

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

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

    // 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(getMyDir() + "\\Artifacts\\MailMerge.MergeImage.doc");
}

private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback
{
    public void fieldMerging(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(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.
// File 'MailMerge.InsertHtml.doc' has merge field named 'htmlField1' in it.
// File 'MailMerge.HtmlData.html' contains some valid HTML data.
// The same approach can be used when merging HTML data from database.

public void mailMergeInsertHtml() throws Exception
{
    Document doc = new Document(getMyDir() + "MailMerge.InsertHtml.doc");

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

    // Load some Html from file.
    StringBuilder htmlText = new StringBuilder();
    BufferedReader reader = new BufferedReader(new FileReader(getMyDir() + "MailMerge.HtmlData.html"));
    String line;
    while ((line = reader.readLine()) != null)
    {
        htmlText.append(line);
        htmlText.append("\r\n");
    }

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

    // Save resulting document with a new name.
    doc.save(getMyDir() + "\\Artifacts\\MailMerge.InsertHtml.doc");
}

private class HandleMergeFieldInsertHtml implements IFieldMergingCallback
{
    /**
     * This is called when merge field is actually merged with data in the document.
     */
    public void fieldMerging(FieldMergingArgs e) throws Exception
    {
        // All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'.
        if (e.getDocumentFieldName().startsWith("html"))
        {
            // Insert the text for this merge field as HTML data, using DocumentBuilder.
            DocumentBuilder builder = new DocumentBuilder(e.getDocument());
            builder.moveToMergeField(e.getDocumentFieldName());
            builder.insertHtml((String) e.getFieldValue());

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

    public void imageFieldMerging(ImageFieldMergingArgs e)
    {
        // Do nothing.
    }
}

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 mail merge HTML data into a document.
        // File 'MailMerge.InsertHtml.doc' has merge field named 'htmlField1' in it.
        // File 'MailMerge.HtmlData.html' contains some valid HTML data.
        // The same approach can be used when merging HTML data from database.
        
        public void mailMergeInsertHtml() throws Exception
        {
            Document doc = new Document(getMyDir() + "MailMerge.InsertHtml.doc");
        
            // Add a handler for the MergeField event.
            doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldInsertHtml());
        
            // Load some Html from file.
            StringBuilder htmlText = new StringBuilder();
            BufferedReader reader = new BufferedReader(new FileReader(getMyDir() + "MailMerge.HtmlData.html"));
            String line;
            while ((line = reader.readLine()) != null)
            {
                htmlText.append(line);
                htmlText.append("\r\n");
            }
        
            // Execute mail merge.
            doc.getMailMerge().execute(new String[]{"htmlField1"}, new String[]{htmlText.toString()});
        
            // Save resulting document with a new name.
            doc.save(getMyDir() + "\\Artifacts\\MailMerge.InsertHtml.doc");
        }
        
        private class HandleMergeFieldInsertHtml implements IFieldMergingCallback
        {
            /**
             * This is called when merge field is actually merged with data in the document.
             */
            public void fieldMerging(FieldMergingArgs e) throws Exception
            {
                // All merge fields that expect HTML data should be marked with some prefix, e.g. 'html'.
                if (e.getDocumentFieldName().startsWith("html"))
                {
                    // Insert the text for this merge field as HTML data, using DocumentBuilder.
                    DocumentBuilder builder = new DocumentBuilder(e.getDocument());
                    builder.moveToMergeField(e.getDocumentFieldName());
                    builder.insertHtml((String) e.getFieldValue());
        
                    // The HTML text itself should not be inserted.
                    // We have already inserted it as an HTML.
                    e.setText("");
                }
            }
        
            public void imageFieldMerging(ImageFieldMergingArgs e)
            {
                // Do nothing.
            }
        }

        Example:

        Shows how to insert images stored in a database BLOB field into a report.
        public void mailMergeImageFromBlob() throws Exception
        {
            Document doc = new Document(getMyDir() + "MailMerge.MergeImage.doc");
        
            // Set up the event handler for image fields.
            doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());
        
            Class.forName("net.ucanaccess.jdbc.UcanaccessDriver"); // Loads the driver
        
            // 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(getMyDir() + "\\Artifacts\\MailMerge.MergeImage.doc");
        }
        
        private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback
        {
            public void fieldMerging(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(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);
            }
        }
      • 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 mailMergeImageFromBlob() throws Exception
        {
            Document doc = new Document(getMyDir() + "MailMerge.MergeImage.doc");
        
            // Set up the event handler for image fields.
            doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());
        
            Class.forName("net.ucanaccess.jdbc.UcanaccessDriver"); // Loads the driver
        
            // 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(getMyDir() + "\\Artifacts\\MailMerge.MergeImage.doc");
        }
        
        private class HandleMergeImageFieldFromBlob implements IFieldMergingCallback
        {
            public void fieldMerging(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(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);
            }
        }