com.aspose.words

Class FieldBuilder

java.lang.Object

com.aspose.words.FieldBuilder

public class FieldBuilder
extends java.lang.Object

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 ƒ (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");
 
 

Constructor Summary

Constructors

Constructor and Description
FieldBuilder(int fieldType) Initializes a new instance of this class.

Method Summary

Modifier and Type	Method and Description
FieldBuilder	addArgument(double argument) Adds a field's argument.
FieldBuilder	addArgument(FieldArgumentBuilder argument) Adds a field's argument represented by FieldArgumentBuilder to the field's code.
FieldBuilder	addArgument(FieldBuilder argument) Adds a child field represented by another FieldBuilder to the field's code.
FieldBuilder	addArgument(int argument) Adds a field's argument.
FieldBuilder	addArgument(java.lang.String argument) Adds a field's argument.
FieldBuilder	addSwitch(java.lang.String switchName) Adds a field's switch.
FieldBuilder	addSwitch(java.lang.String switchName, double switchArgument) Adds a field's switch.
FieldBuilder	addSwitch(java.lang.String switchName, int switchArgument) Adds a field's switch.
FieldBuilder	addSwitch(java.lang.String switchName, java.lang.String switchArgument) Adds a field's switch.
Field	buildAndInsert(Inline refNode) Builds and inserts a field into the document before the specified inline node.
Field	buildAndInsert(Paragraph refNode) Builds and inserts a field into the document to the end of the specified paragraph.
void	buildBlock(DocumentBuilder documentBuilder)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FieldBuilder

public FieldBuilder(int fieldType)

Initializes a new instance of this class.

Method Detail

addArgument

public FieldBuilder addArgument(java.lang.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 ƒ (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:

argument - The argument value.

addArgument

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 ƒ (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:

argument - The argument value.

addArgument

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 ƒ (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:

argument - The argument value.

addArgument

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 ƒ (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");
 
 

addArgument

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 ƒ (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");
 
 

addSwitch

public FieldBuilder addSwitch(java.lang.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 ƒ (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:

switchName - The switch name.

addSwitch

public FieldBuilder addSwitch(java.lang.String switchName,
                              java.lang.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 ƒ (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:

switchName - The switch name.

switchArgument - The switch value.

addSwitch

public FieldBuilder addSwitch(java.lang.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 ƒ (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:

switchName - The switch name.

switchArgument - The switch value.

addSwitch

public FieldBuilder addSwitch(java.lang.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 ƒ (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:

switchName - The switch name.

switchArgument - The switch value.

buildAndInsert

public Field buildAndInsert(Inline refNode)
                     throws java.lang.Exception

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");
 
 

Returns:

A Field object that represents the inserted field.

Throws:

java.lang.Exception

buildAndInsert

public Field buildAndInsert(Paragraph refNode)
                     throws java.lang.Exception

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 ƒ (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");
 
 

Returns:

A Field object that represents the inserted field.

Throws:

java.lang.Exception

buildBlock

public void buildBlock(DocumentBuilder documentBuilder)
                throws java.lang.Exception

Throws:

java.lang.Exception