com.aspose.words

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).

Example:

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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

Constructor Summary
FieldBuilder(intfieldType)
Initializes an instance of the FieldBuilder class.
 
Method Summary
FieldBuilderaddArgument(FieldArgumentBuilder argument)
Adds a field's argument represented by FieldArgumentBuilder to the field's code.
FieldBuilderaddArgument(FieldBuilder argument)
Adds a child field represented by another FieldBuilder to the field's code.
FieldBuilderaddArgument(double argument)
Adds a field's argument.
FieldBuilderaddArgument(int argument)
Adds a field's argument.
FieldBuilderaddArgument(java.lang.String argument)
Adds a field's argument.
FieldBuilderaddSwitch(java.lang.String switchName)
Adds a field's switch.
FieldBuilderaddSwitch(java.lang.String switchName, double switchArgument)
Adds a field's switch.
FieldBuilderaddSwitch(java.lang.String switchName, int switchArgument)
Adds a field's switch.
FieldBuilderaddSwitch(java.lang.String switchName, java.lang.String switchArgument)
Adds a field's switch.
FieldbuildAndInsert(Inline refNode)
Builds and inserts a field into the document before the specified inline node.
FieldbuildAndInsert(Paragraph refNode)
Builds and inserts a field into the document to the end of the specified paragraph.
 

    • Constructor Detail

      • FieldBuilder

        public FieldBuilder(int fieldType)
        Initializes an instance of the FieldBuilder class.
        Parameters:
        fieldType - A FieldType value. The type of the field to build.

        Example:

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

    • Method Detail

      • addArgument

        public FieldBuilder addArgument(FieldArgumentBuilder argument)
        Adds a field's argument represented by FieldArgumentBuilder to the field's code. This overload is used when the argument consists of a mixture of different parts such as child fields, nodes, and plain text.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • addArgument

        public FieldBuilder addArgument(FieldBuilder argument)
        Adds a child field represented by another FieldBuilder to the field's code. This overload is used when the argument consists of a single child field.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • addArgument

        public FieldBuilder addArgument(double argument)
        Adds a field's argument.
        Parameters:
        argument - The argument value.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • addArgument

        public FieldBuilder addArgument(int argument)
        Adds a field's argument.
        Parameters:
        argument - The argument value.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • addArgument

        public FieldBuilder addArgument(java.lang.String argument)
        Adds a field's argument.
        Parameters:
        argument - The argument value.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • addSwitch

        public FieldBuilder addSwitch(java.lang.String switchName)
        Adds a field's switch. This overload adds a flag (switch without argument).
        Parameters:
        switchName - The switch name.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • addSwitch

        public FieldBuilder addSwitch(java.lang.String switchName, double switchArgument)
        Adds a field's switch.
        Parameters:
        switchName - The switch name.
        switchArgument - The switch value.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • addSwitch

        public FieldBuilder addSwitch(java.lang.String switchName, int switchArgument)
        Adds a field's switch.
        Parameters:
        switchName - The switch name.
        switchArgument - The switch value.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • addSwitch

        public FieldBuilder addSwitch(java.lang.String switchName, java.lang.String switchArgument)
        Adds a field's switch.
        Parameters:
        switchName - The switch name.
        switchArgument - The switch value.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");

      • buildAndInsert

        public Field buildAndInsert(Inline refNode)
                    throws java.lang.Exception
        Builds and inserts a field into the document before the specified inline node.
        Returns:
        A Field object that represents the inserted field.

        Example:

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

      • 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.
        Returns:
        A Field object that represents the inserted field.

        Example:

        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 \u0013 = 100 + 74 \u0014\u0015 ", 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 put all of its pieces together. 
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 \u0013 = 2 + 3 \u0014\u0015 = \u0013 = 2.5 * 5.2 \u0014\u0015 " +
                "\"True, both expressions amount to \u0013 = 2 + 3 \u0014\u0015\" " +
                "\"False, \u0013 = 2 + 3 \u0014\u0015 does not equal \u0013 = 2.5 * 5.2 \u0014\u0015\" ", field.getFieldCode());

doc.updateFields();
doc.save(getArtifactsDir() + "Field.SYMBOL.docx");