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 insert fields using a field builder.
Document doc = new Document();

// Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");

// Use a field builder to create a formula field that will be used by another field builder
FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
innerFormulaBuilder.addArgument(100);
innerFormulaBuilder.addArgument("+");
innerFormulaBuilder.addArgument(74);

// Add a field builder as an argument to another field builder
// The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
// to be displayed by this SYMBOL field
builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
builder.addArgument(innerFormulaBuilder);
field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));

Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");

// Now we will use our builder to construct a more complex field with nested fields
// For our IF field, we will first create two formula fields to serve as expressions
// Their results will be tested for equality to decide what value an IF field displays
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 create two field arguments using field argument builders
// These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
// and two field argument builders as the two potential outputs
builder = new FieldBuilder(FieldType.FIELD_IF);
builder.addArgument(leftExpression);
builder.addArgument("=");
builder.addArgument(rightExpression);
builder.addArgument(trueOutput);
builder.addArgument(falseOutput);

builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));

doc.updateFields();
doc.save(getArtifactsDir() + "Field.FieldBuilder.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:

        Builds and inserts a field into the document before the specified inline node
        Document doc = new Document();
        Run run = DocumentHelper.insertNewRun(doc, " Hello World!", 0);
        
        FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_REVISION_NUM);
        fieldBuilder.buildAndInsert(run);
        
        doc.updateFields();
    • 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 insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.docx");

        Example:

        Inserts a field into a document using field builder constructor
        Document doc = new Document();
        
        // Add text into the paragraph
        Paragraph para = doc.getFirstSection().getBody().getParagraphs().get(0);
        Run run = new Run(doc);
        run.setText(" Hello World!");
        
        para.appendChild(run);
        
        FieldArgumentBuilder argumentBuilder = new FieldArgumentBuilder();
        argumentBuilder.addField(new FieldBuilder(FieldType.FIELD_MERGE_FIELD));
        argumentBuilder.addText("BestField");
        
        FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_IF);
        fieldBuilder.addArgument(argumentBuilder).addArgument("=").addArgument("BestField").addArgument(10).addArgument(20.0).addSwitch("12", "13").buildAndInsert(run);
        
        doc.updateFields();
      • 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 insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.docx");
      • addArgument

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

        Example:

        Shows how to insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.docx");

        Example:

        Inserts a field into a document using field builder constructor
        Document doc = new Document();
        
        // Add text into the paragraph
        Paragraph para = doc.getFirstSection().getBody().getParagraphs().get(0);
        Run run = new Run(doc);
        run.setText(" Hello World!");
        
        para.appendChild(run);
        
        FieldArgumentBuilder argumentBuilder = new FieldArgumentBuilder();
        argumentBuilder.addField(new FieldBuilder(FieldType.FIELD_MERGE_FIELD));
        argumentBuilder.addText("BestField");
        
        FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_IF);
        fieldBuilder.addArgument(argumentBuilder).addArgument("=").addArgument("BestField").addArgument(10).addArgument(20.0).addSwitch("12", "13").buildAndInsert(run);
        
        doc.updateFields();
      • addArgument

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

        Example:

        Shows how to insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.docx");

        Example:

        Inserts a field into a document using field builder constructor
        Document doc = new Document();
        
        // Add text into the paragraph
        Paragraph para = doc.getFirstSection().getBody().getParagraphs().get(0);
        Run run = new Run(doc);
        run.setText(" Hello World!");
        
        para.appendChild(run);
        
        FieldArgumentBuilder argumentBuilder = new FieldArgumentBuilder();
        argumentBuilder.addField(new FieldBuilder(FieldType.FIELD_MERGE_FIELD));
        argumentBuilder.addText("BestField");
        
        FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_IF);
        fieldBuilder.addArgument(argumentBuilder).addArgument("=").addArgument("BestField").addArgument(10).addArgument(20.0).addSwitch("12", "13").buildAndInsert(run);
        
        doc.updateFields();
      • addArgument

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

        Example:

        Shows how to insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.docx");

        Example:

        Inserts a field into a document using field builder constructor
        Document doc = new Document();
        
        // Add text into the paragraph
        Paragraph para = doc.getFirstSection().getBody().getParagraphs().get(0);
        Run run = new Run(doc);
        run.setText(" Hello World!");
        
        para.appendChild(run);
        
        FieldArgumentBuilder argumentBuilder = new FieldArgumentBuilder();
        argumentBuilder.addField(new FieldBuilder(FieldType.FIELD_MERGE_FIELD));
        argumentBuilder.addText("BestField");
        
        FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_IF);
        fieldBuilder.addArgument(argumentBuilder).addArgument("=").addArgument("BestField").addArgument(10).addArgument(20.0).addSwitch("12", "13").buildAndInsert(run);
        
        doc.updateFields();
      • 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 insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.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 insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.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 insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.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 insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.docx");

        Example:

        Inserts a field into a document using field builder constructor
        Document doc = new Document();
        
        // Add text into the paragraph
        Paragraph para = doc.getFirstSection().getBody().getParagraphs().get(0);
        Run run = new Run(doc);
        run.setText(" Hello World!");
        
        para.appendChild(run);
        
        FieldArgumentBuilder argumentBuilder = new FieldArgumentBuilder();
        argumentBuilder.addField(new FieldBuilder(FieldType.FIELD_MERGE_FIELD));
        argumentBuilder.addText("BestField");
        
        FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_IF);
        fieldBuilder.addArgument(argumentBuilder).addArgument("=").addArgument("BestField").addArgument(10).addArgument(20.0).addSwitch("12", "13").buildAndInsert(run);
        
        doc.updateFields();
      • 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:

        Builds and inserts a field into the document before the specified inline node
        Document doc = new Document();
        Run run = DocumentHelper.insertNewRun(doc, " Hello World!", 0);
        
        FieldBuilder fieldBuilder = new FieldBuilder(FieldType.FIELD_REVISION_NUM);
        fieldBuilder.buildAndInsert(run);
        
        doc.updateFields();
      • 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 insert fields using a field builder.
        Document doc = new Document();
        
        // Use a field builder to add a SYMBOL field which displays the "F with hook" 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 ");
        
        // Use a field builder to create a formula field that will be used by another field builder
        FieldBuilder innerFormulaBuilder = new FieldBuilder(FieldType.FIELD_FORMULA);
        innerFormulaBuilder.addArgument(100);
        innerFormulaBuilder.addArgument("+");
        innerFormulaBuilder.addArgument(74);
        
        // Add a field builder as an argument to another field builder
        // The result of our formula field will be used as an ANSI value representing the "enclosed R" symbol,
        // to be displayed by this SYMBOL field
        builder = new FieldBuilder(FieldType.FIELD_SYMBOL);
        builder.addArgument(innerFormulaBuilder);
        field = builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        Assert.assertEquals(field.getFieldCode(), " SYMBOL \u0013 = 100 + 74 \u0014\u0015 ");
        
        // Now we will use our builder to construct a more complex field with nested fields
        // For our IF field, we will first create two formula fields to serve as expressions
        // Their results will be tested for equality to decide what value an IF field displays
        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 create two field arguments using field argument builders
        // These will serve as the two possible outputs of our IF field and they will also use our two 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 use a field builder to create an IF field which takes two field builders as expressions,
        // and two field argument builders as the two potential outputs
        builder = new FieldBuilder(FieldType.FIELD_IF);
        builder.addArgument(leftExpression);
        builder.addArgument("=");
        builder.addArgument(rightExpression);
        builder.addArgument(trueOutput);
        builder.addArgument(falseOutput);
        
        builder.buildAndInsert(doc.getFirstSection().getBody().appendParagraph(""));
        
        doc.updateFields();
        doc.save(getArtifactsDir() + "Field.FieldBuilder.docx");