Using Fields in Aspose.Words for Java
Contents
[
Hide
]In this step-by-step tutorial, we will guide you on how to use fields in Aspose.Words for Java to manipulate documents with ease. Aspose.Words for Java is a powerful API that allows you to work with Word documents programmatically, giving you full control over their content and formatting.
1. Introduction
Aspose.Words for Java is an essential tool for anyone dealing with Word documents in Java applications. Fields are placeholders that can store dynamic data in your document. This tutorial will show you how to work with fields effectively.
2. Setting Up Your Environment
Before you begin, make sure you have Aspose.Words for Java installed. You can download it from here. Also, ensure that you have Java and an integrated development environment (IDE) like Eclipse or IntelliJ IDEA installed on your system.
3. Loading a Word Document
In your Java application, you need to load the Word document you want to work with. Here’s a snippet of code to get you started:
string dataDir = "Your Document Directory";
string outPath = "Your Output Directory";
Document doc = new Document(dataDir + "Mail merge destinations - Fax.docx");
Replace "Your Document Directory" and "Your Output Directory" with the appropriate paths.
4. Customizing Mail Merge
Aspose.Words for Java provides excellent support for mail merge operations. You can customize the mail merge process by setting up a mail merge event handler. Here’s how to do it:
// Setup mail merge event handler to do the custom work.
doc.getMailMerge().setFieldMergingCallback(new HandleMergeField());
// Trim trailing and leading whitespaces mail merge values.
doc.getMailMerge().setTrimWhitespaces(false);
String[] fieldNames = {
"RecipientName", "SenderName", "FaxNumber", "PhoneNumber",
"Subject", "Body", "Urgent", "ForReview", "PleaseComment"
};
Object[] fieldValues = {
"Josh", "Jenny", "123456789", "", "Hello",
"<b>HTML Body Test message 1</b>", true, false, true
};
doc.getMailMerge().execute(fieldNames, fieldValues);
5. Saving the Document
After customizing your document, you can save it using the following code:
doc.save(outPath + "WorkingWithFields.MailMergeFormFields.docx");
Replace "Your Output Directory" with the desired output path.
Complete Source Code
string dataDir = "Your Document Directory";
string outPath = "Your Output Directory";
Document doc = new Document(dataDir + "Mail merge destinations - Fax.docx");
// Setup mail merge event handler to do the custom work.
doc.getMailMerge().setFieldMergingCallback(new HandleMergeField());
// Trim trailing and leading whitespaces mail merge values.
doc.getMailMerge().setTrimWhitespaces(false);
String[] fieldNames = {
"RecipientName", "SenderName", "FaxNumber", "PhoneNumber",
"Subject", "Body", "Urgent", "ForReview", "PleaseComment"
};
Object[] fieldValues = {
"Josh", "Jenny", "123456789", "", "Hello",
"<b>HTML Body Test message 1</b>", true, false, true
};
doc.getMailMerge().execute(fieldNames, fieldValues);
doc.save(outPath + "WorkingWithFields.MailMergeFormFields.docx");
Source code of Class HandleMergeField
private static class HandleMergeField implements IFieldMergingCallback
{
/// <summary>
/// This handler is called for every mail merge field found in the document,
/// for every record found in the data source.
/// </summary>
public void /*IFieldMergingCallback.*/fieldMerging(FieldMergingArgs e) throws Exception
{
if (mBuilder == null)
mBuilder = new DocumentBuilder(e.getDocument());
// We decided that we want all boolean values to be output as check box form fields.
if (e.getFieldValue() instanceof /*boolean*/Boolean)
{
// Move the "cursor" to the current merge field.
mBuilder.moveToMergeField(e.getFieldName());
String checkBoxName = MessageFormat.format("{0}{1}", e.getFieldName(), e.getRecordIndex());
mBuilder.insertCheckBox(checkBoxName, (Boolean) e.getFieldValue(), 0);
return;
}
switch (e.getFieldName())
{
case "Body":
mBuilder.moveToMergeField(e.getFieldName());
mBuilder.insertHtml((String) e.getFieldValue());
break;
case "Subject":
{
mBuilder.moveToMergeField(e.getFieldName());
String textInputName = MessageFormat.format("{0}{1}", e.getFieldName(), e.getRecordIndex());
mBuilder.insertTextInput(textInputName, TextFormFieldType.REGULAR, "", (String) e.getFieldValue(), 0);
break;
}
}
}
public void imageFieldMerging(ImageFieldMergingArgs args)
{
args.setImageFileName("Image.png");
args.getImageWidth().setValue(200.0);
args.setImageHeight(new MergeFieldImageDimension(200.0, MergeFieldImageDimensionUnit.PERCENT));
}
private DocumentBuilder mBuilder;
}
@Test
public void mailMergeImageField() throws Exception
{
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.writeln("{{#foreach example}}");
builder.writeln("{{Image(126pt;126pt):stempel}}");
builder.writeln("{{/foreach example}}");
doc.getMailMerge().setUseNonMergeFields(true);
doc.getMailMerge().setTrimWhitespaces(true);
doc.getMailMerge().setUseWholeParagraphAsRegion(false);
doc.getMailMerge().setCleanupOptions(MailMergeCleanupOptions.REMOVE_EMPTY_TABLE_ROWS
| MailMergeCleanupOptions.REMOVE_CONTAINING_FIELDS
| MailMergeCleanupOptions.REMOVE_UNUSED_REGIONS
| MailMergeCleanupOptions.REMOVE_UNUSED_FIELDS);
doc.getMailMerge().setFieldMergingCallback(new ImageFieldMergingHandler());
doc.getMailMerge().executeWithRegions(new DataSourceRoot());
doc.save("Your Directory Path" + "WorkingWithFields.MailMergeImageField.docx");
}
private static class ImageFieldMergingHandler implements IFieldMergingCallback
{
public void fieldMerging(FieldMergingArgs args)
{
// Implementation is not required.
}
public void imageFieldMerging(ImageFieldMergingArgs args) throws Exception
{
Shape shape = new Shape(args.getDocument(), ShapeType.IMAGE);
{
shape.setWidth(126.0); shape.setHeight(126.0); shape.setWrapType(WrapType.SQUARE);
}
shape.getImageData().setImage("Your Directory Path" + "Mail merge image.png");
args.setShape(shape);
}
}
public static class DataSourceRoot implements IMailMergeDataSourceRoot
{
public IMailMergeDataSource getDataSource(String s)
{
return new DataSource();
}
private static class DataSource implements IMailMergeDataSource
{
private boolean next = true;
private String tableName()
{
return "example";
}
@Override
public String getTableName() {
return tableName();
}
public boolean moveNext()
{
boolean result = next;
next = false;
return result;
}
public IMailMergeDataSource getChildDataSource(String s)
{
return null;
}
public boolean getValue(String fieldName, Ref<Object> fieldValue)
{
fieldValue.set(null);
return false;
}
}
}
@Test
public void mailMergeAndConditionalField() throws Exception
{
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert a MERGEFIELD nested inside an IF field.
// Since the IF field statement is false, the result of the inner MERGEFIELD will not be displayed,
// and the MERGEFIELD will not receive any data during a mail merge.
FieldIf fieldIf = (FieldIf)builder.insertField(" IF 1 = 2 ");
builder.moveTo(fieldIf.getSeparator());
builder.insertField(" MERGEFIELD FullName ");
// We can still count MERGEFIELDs inside false-statement IF fields if we set this flag to true.
doc.getMailMerge().setUnconditionalMergeFieldsAndRegions(true);
DataTable dataTable = new DataTable();
dataTable.getColumns().add("FullName");
dataTable.getRows().add("James Bond");
doc.getMailMerge().execute(dataTable);
// The result will not be visible in the document because the IF field is false,
// but the inner MERGEFIELD did indeed receive data.
doc.save("Your Directory Path" + "WorkingWithFields.MailMergeAndConditionalField.docx");
}
@Test
public void mailMergeImageFromBlob() throws Exception
{
Document doc = new Document("Your Directory Path" + "Mail merge destination - Northwind employees.docx");
doc.getMailMerge().setFieldMergingCallback(new HandleMergeImageFieldFromBlob());
Class.forName("net.ucanaccess.jdbc.UcanaccessDriver");
String connString = "jdbc:ucanaccess://" + getDatabaseDir() + "Northwind.mdb";
Connection connection = DriverManager.getConnection(connString, "Admin", "");
Statement statement = connection.createStatement();
ResultSet resultSet = statement.executeQuery("SELECT * FROM Employees");
DataTable dataTable = new DataTable(resultSet, "Employees");
IDataReader dataReader = new DataTableReader(dataTable);
doc.getMailMerge().executeWithRegions(dataReader, "Employees");
connection.close();
doc.save("Your Directory Path" + "WorkingWithFields.MailMergeImageFromBlob.docx");
}
public static class HandleMergeImageFieldFromBlob implements IFieldMergingCallback
{
public void /*IFieldMergingCallback.*/fieldMerging(FieldMergingArgs args)
{
// Do nothing.
}
/// <summary>
/// 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.
/// </summary>
public void /*IFieldMergingCallback.*/imageFieldMerging(ImageFieldMergingArgs e) throws Exception
{
// 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);
}
}
@Test
public void handleMailMergeSwitches() throws Exception
{
Document doc = new Document("Your Directory Path" + "Field sample - MERGEFIELD.docx");
doc.getMailMerge().setFieldMergingCallback(new MailMergeSwitches());
final String HTML = "<html>\r\n <h1>Hello world!</h1>\r\n </html>";
doc.getMailMerge().execute(new String[] { "htmlField1" }, new Object[] { HTML });
doc.save("Your Directory Path" + "WorkingWithFields.HandleMailMergeSwitches.docx");
}
public static class MailMergeSwitches implements IFieldMergingCallback
{
public void /*IFieldMergingCallback.*/fieldMerging(FieldMergingArgs e) throws Exception
{
if (e.getFieldName().startsWith("HTML"))
{
if (e.getField().getFieldCode().contains("\\b"))
{
FieldMergeField field = e.getField();
DocumentBuilder builder = new DocumentBuilder(e.getDocument());
builder.moveToMergeField(e.getDocumentFieldName(), true, false);
builder.write(field.getTextBefore());
builder.insertHtml(e.getFieldValue().toString());
e.setText("");
}
}
}
public void /*IFieldMergingCallback.*/imageFieldMerging(ImageFieldMergingArgs args)
{
}
}
@Test
public void alternatingRows() throws Exception
{
Document doc = new Document("Your Directory Path" + "Mail merge destination - Northwind suppliers.docx");
doc.getMailMerge().setFieldMergingCallback(new HandleMergeFieldAlternatingRows());
DataTable dataTable = getSuppliersDataTable();
doc.getMailMerge().executeWithRegions(dataTable);
doc.save("Your Directory Path" + "WorkingWithFields.AlternatingRows.doc");
}
private static class HandleMergeFieldAlternatingRows implements IFieldMergingCallback
{
/// <summary>
/// Called for every merge field encountered in the document.
/// We can either return some data to the mail merge engine or do something else with the document.
/// In this case we modify cell formatting.
/// </summary>
public void /*IFieldMergingCallback.*/fieldMerging(FieldMergingArgs e)
{
if (mBuilder == null)
mBuilder = new DocumentBuilder(e.getDocument());
if ("CompanyName".equals(e.getFieldName()))
{
// Select the color depending on whether the row number is even or odd.
Color rowColor = isOdd(mRowIdx)
? new Color((213), (227), (235))
: new Color((242), (242), (242));
// There is no way to set cell properties for the whole row at the moment, so we have to iterate over all cells in the row.
for (int colIdx = 0; colIdx < 4; colIdx++)
{
mBuilder.moveToCell(0, mRowIdx, colIdx, 0);
mBuilder.getCellFormat().getShading().setBackgroundPatternColor(rowColor);
}
mRowIdx++;
}
}
public void /*IFieldMergingCallback.*/imageFieldMerging(ImageFieldMergingArgs args)
{
// Do nothing.
}
private DocumentBuilder mBuilder;
private int mRowIdx;
}
/// <summary>
/// Returns true if the value is odd; false if the value is even.
/// </summary>
private static boolean isOdd(int value)
{
return (value / 2 * 2) == value;
}
/// <summary>
/// Create DataTable and fill it with data.
/// In real life this DataTable should be filled from a database.
/// </summary>
private DataTable getSuppliersDataTable()
{
DataTable dataTable = new DataTable("Suppliers");
dataTable.getColumns().add("CompanyName");
dataTable.getColumns().add("ContactName");
for (int i = 0; i < 10; i++)
{
DataRow datarow = dataTable.newRow();
dataTable.getRows().add(datarow);
datarow.set(0, "Company " + i);
datarow.set(1, "Contact " + i);
}
return dataTable;
}
}
6. Conclusion
Congratulations! You’ve learned how to use fields in Aspose.Words for Java to manipulate Word documents dynamically. This powerful API gives you complete control over your documents, making it a valuable asset for Java developers.
7. FAQs
Q1: Where can I download Aspose.Words for Java?
You can download Aspose.Words for Java from here.
Q2: How can I get a temporary license for Aspose.Words for Java?
You can obtain a temporary license from here.
Q3: Where can I get support for Aspose.Words for Java?
For support, you can visit the Aspose.Words forum here.
Q4: Is Aspose.Words for Java suitable for handling HTML content in Word documents?
Yes, Aspose.Words for Java provides excellent support for handling HTML content in Word documents.
Q5: Can I use Aspose.Words for Java for free?
Aspose.Words for Java is a commercial product, but you can explore its features with a free trial available here.
Get started with Aspose.Words for Java today and take control of your Word documents like never before!
