FieldBuilder
Contents
[
Hide
]Inheritance: java.lang.Object
public class FieldBuilder
Builds a field from field code tokens (arguments and switches).
To learn more, visit the Working with Fields documentation article.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Constructors
| Constructor | Description |
|---|---|
| FieldBuilder(int fieldType) | Initializes a new instance of this class. |
Methods
| Method | Description |
|---|---|
| addArgument(FieldArgumentBuilder argument) | Adds a field’s argument represented by FieldArgumentBuilder to the field’s code. |
| addArgument(FieldBuilder argument) | Adds a child field represented by another FieldBuilder to the field’s code. |
| addArgument(double argument) | Adds a field’s argument. |
| addArgument(int argument) | Adds a field’s argument. |
| addArgument(String argument) | Adds a field’s argument. |
| addSwitch(String switchName) | Adds a field’s switch. |
| addSwitch(String switchName, double switchArgument) | Adds a field’s switch. |
| addSwitch(String switchName, int switchArgument) | Adds a field’s switch. |
| addSwitch(String switchName, String switchArgument) | Adds a field’s switch. |
| buildAndInsert(Inline refNode) | Builds and inserts a field into the document before the specified inline node. |
| buildAndInsert(Paragraph refNode) | Builds and inserts a field into the document to the end of the specified paragraph. |
| buildBlock(DocumentBuilder documentBuilder) |
FieldBuilder(int fieldType)
public FieldBuilder(int fieldType)
Initializes a new instance of this class.
Parameters:
| Parameter | Type | Description |
|---|---|---|
| fieldType | int |
addArgument(FieldArgumentBuilder argument)
public FieldBuilder addArgument(FieldArgumentBuilder argument)
Adds a field’s argument represented by FieldArgumentBuilder to the field’s code.
Remarks:
This overload is used when the argument consists of a mixture of different parts such as child fields, nodes, and plain text.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| argument | FieldArgumentBuilder |
Returns: FieldBuilder
addArgument(FieldBuilder argument)
public FieldBuilder addArgument(FieldBuilder argument)
Adds a child field represented by another FieldBuilder to the field’s code.
Remarks:
This overload is used when the argument consists of a single child field.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| argument | FieldBuilder |
Returns: FieldBuilder
addArgument(double argument)
public FieldBuilder addArgument(double argument)
Adds a field’s argument.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| argument | double | The argument value. |
Returns: FieldBuilder
addArgument(int argument)
public FieldBuilder addArgument(int argument)
Adds a field’s argument.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| argument | int | The argument value. |
Returns: FieldBuilder
addArgument(String argument)
public FieldBuilder addArgument(String argument)
Adds a field’s argument.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| argument | java.lang.String | The argument value. |
Returns: FieldBuilder
addSwitch(String switchName)
public FieldBuilder addSwitch(String switchName)
Adds a field’s switch.
Remarks:
This overload adds a flag (switch without argument).
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| switchName | java.lang.String | The switch name. |
Returns: FieldBuilder
addSwitch(String switchName, double switchArgument)
public FieldBuilder addSwitch(String switchName, double switchArgument)
Adds a field’s switch.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| switchName | java.lang.String | The switch name. |
| switchArgument | double | The switch value. |
Returns: FieldBuilder
addSwitch(String switchName, int switchArgument)
public FieldBuilder addSwitch(String switchName, int switchArgument)
Adds a field’s switch.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| switchName | java.lang.String | The switch name. |
| switchArgument | int | The switch value. |
Returns: FieldBuilder
addSwitch(String switchName, String switchArgument)
public FieldBuilder addSwitch(String switchName, String switchArgument)
Adds a field’s switch.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| switchName | java.lang.String | The switch name. |
| switchArgument | java.lang.String | The switch value. |
Returns: FieldBuilder
buildAndInsert(Inline refNode)
public Field buildAndInsert(Inline refNode)
Builds and inserts a field into the document before the specified inline node.
Examples:
Shows how to create and insert a field using a field builder.
Document doc = new Document();
// A convenient way of adding text content to a document is with a document builder.
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write(" Hello world! This text is one Run, which is an inline node.");
// Fields have their builder, which we can use to construct a field code piece by piece.
// In this case, we will construct a BARCODE field representing a US postal code,
// and then insert it in front of a Run.
FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_BARCODE);
fieldBuilder.addArgument("90210");
fieldBuilder.addSwitch("\\f", "A");
fieldBuilder.addSwitch("\\u");
fieldBuilder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph().getRuns().get(0));
doc.updateFields();
doc.save(getArtifactsDir() + "Field.CreateWithFieldBuilder.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| refNode | Inline |
Returns: Field - A Field object that represents the inserted field.
buildAndInsert(Paragraph refNode)
public Field buildAndInsert(Paragraph refNode)
Builds and inserts a field into the document to the end of the specified paragraph.
Examples:
Shows how to construct fields using a field builder, and then insert them into the document.
Document doc = new Document();
// Below are three examples of field construction done using a field builder.
// 1 - Single field:
// Use a field builder to add a SYMBOL field which displays the \u0192 (Florin) symbol.
FieldBuilder builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(402);
builder.addSwitch("\\f", "Arial");
builder.addSwitch("\\s", 25);
builder.addSwitch("\\u");
Field field = builder.buildAndInsert(doc.getFirstSection().getBody().getFirstParagraph());
Assert.assertEquals(field.getFieldCode(), " SYMBOL 402 \\f Arial \\s 25 \\u ");
// 2 - Nested field:
// Use a field builder to create a formula field used as an inner field by another field builder.
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);
// Create another builder for another SYMBOL field, and insert the formula field
// that we have created above into the SYMBOL field as its argument.
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
// The outer SYMBOL field will use the formula field result, 174, as its argument,
// which will make the field display the (Registered Sign) symbol since its character number is 174.
Assert.assertEquals(" SYMBOL = 100 + 74 ", field.getFieldCode());
// 3 - Multiple nested fields and arguments:
// Now, we will use a builder to create an IF field, which displays one of two custom string values,
// depending on the true/false value of its expression. To get a true/false value
// that determines which string the IF field displays, the IF field will test two numeric expressions for equality.
// We will provide the two expressions in the form of formula fields, which we will nest inside the IF field.
FieldBuilder leftExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
leftExpression.addArgument(2);
leftExpression.addArgument("+");
leftExpression.addArgument(3);
FieldBuilder rightExpression = new FieldBuilder(FieldType.FIELD_FORMULA);
rightExpression.addArgument(2.5);
rightExpression.addArgument("*");
rightExpression.addArgument(5.2);
// Next, we will build two field arguments, which will serve as the true/false output strings for the IF field.
// These arguments will reuse the output values of our numeric expressions.
FieldArgumentBuilder trueOutput = new FieldArgumentBuilder();
trueOutput.addText("True, both expressions amount to ");
trueOutput.addField(leftExpression);
FieldArgumentBuilder falseOutput = new FieldArgumentBuilder();
falseOutput.addNode(new Run(doc, "False, "));
falseOutput.addField(leftExpression);
falseOutput.addNode(new Run(doc, " does not equal "));
falseOutput.addField(rightExpression);
// Finally, we will create one more field builder for the IF field and combine all of the expressions.
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
Assert.assertEquals(" IF = 2 + 3 = = 2.5 * 5.2 " +
"\"True, both expressions amount to = 2 + 3 \" " +
"\"False, = 2 + 3 does not equal = 2.5 * 5.2 \" ", field.getFieldCode());
doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");
Parameters:
| Parameter | Type | Description |
|---|---|---|
| refNode | Paragraph |
Returns: Field - A Field object that represents the inserted field.
buildBlock(DocumentBuilder documentBuilder)
public void buildBlock(DocumentBuilder documentBuilder)
Parameters:
| Parameter | Type | Description |
|---|---|---|
| documentBuilder | DocumentBuilder |
