com.aspose.words
Class FieldOptions

java.lang.Object
    com.aspose.words.FieldOptions

public class FieldOptions 
extends java.lang.Object

public IBarcodeGenerator getBarcodeGenerator() / public void setBarcodeGenerator(IBarcodeGenerator value)

Gets or set custom barcode generator.

Custom barcode generator should implement public interface IBarcodeGenerator.

Example:

Shows how to create barcode images using a barcode generator.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Assert.assertNull(doc.getFieldOptions().getBarcodeGenerator());

// Barcodes generated in this way will be images, and we can use a custom IBarcodeGenerator implementation to generate them
doc.getFieldOptions().setBarcodeGenerator(new CustomBarcodeGenerator());

// Configure barcode parameters for a QR barcode
BarcodeParameters barcodeParameters = new BarcodeParameters();
barcodeParameters.setBarcodeType("QR");
barcodeParameters.setBarcodeValue("ABC123");
barcodeParameters.setBackgroundColor("0xF8BD69");
barcodeParameters.setForegroundColor("0xB5413B");
barcodeParameters.setErrorCorrectionLevel("3");
barcodeParameters.setScalingFactor("250");
barcodeParameters.setSymbolHeight("1000");
barcodeParameters.setSymbolRotation("0");

// Save the generated barcode image to the file system
BufferedImage img = doc.getFieldOptions().getBarcodeGenerator().getBarcodeImage(barcodeParameters);
ImageIO.write(img, "jpg", new File(getArtifactsDir() + "Field.BarcodeGenerator.QR.jpg"));

// Insert the image into the document
builder.insertImage(img);

// Configure barcode parameters for a EAN13 barcode
barcodeParameters = new BarcodeParameters();
barcodeParameters.setBarcodeType("EAN13");
barcodeParameters.setBarcodeValue("501234567890");
barcodeParameters.setDisplayText(true);
barcodeParameters.setPosCodeStyle("CASE");
barcodeParameters.setFixCheckDigit(true);

img = doc.getFieldOptions().getBarcodeGenerator().getBarcodeImage(barcodeParameters);
ImageIO.write(img, "jpg", new File(getArtifactsDir() + "Field.BarcodeGenerator.EAN13.jpg"));
builder.insertImage(img);

// Configure barcode parameters for a CODE39 barcode
barcodeParameters = new BarcodeParameters();
barcodeParameters.setBarcodeType("CODE39");
barcodeParameters.setBarcodeValue("12345ABCDE");
barcodeParameters.setAddStartStopChar(true);

img = doc.getFieldOptions().getBarcodeGenerator().getBarcodeImage(barcodeParameters);
ImageIO.write(img, "jpg", new File(getArtifactsDir() + "Field.BarcodeGenerator.CODE39.jpg"));
builder.insertImage(img);

// Configure barcode parameters for an ITF14 barcode
barcodeParameters = new BarcodeParameters();
barcodeParameters.setBarcodeType("ITF14");
barcodeParameters.setBarcodeValue("09312345678907");
barcodeParameters.setCaseCodeStyle("STD");

img = doc.getFieldOptions().getBarcodeGenerator().getBarcodeImage(barcodeParameters);
ImageIO.write(img, "jpg", new File(getArtifactsDir() + "Field.BarcodeGenerator.ITF14.jpg"));
builder.insertImage(img);

doc.save(getArtifactsDir() + "Field.BarcodeGenerator.docx");

public java.lang.String[] getBuiltInTemplatesPaths() / public void setBuiltInTemplatesPaths(java.lang.String[] value)

Gets or sets paths of MS Word built-in templates.

This property is used by the AUTOTEXT and GLOSSARY fields, if referenced auto text entry is not found in the Document.AttachedTemplate template.

By defalut MS Word stores built-in templates in c:\Users\<username>\AppData\Roaming\Microsoft\Document Building Blocks\1033\16\Built-In Building Blocks.dotx and C:\Users\<username>\AppData\Roaming\Microsoft\Templates\Normal.dotm files.

Example:

Shows how to insert a building block into a document and display it with AUTOTEXT and GLOSSARY fields.

Document doc = new Document();

// Create a glossary document and add an AutoText building block
doc.setGlossaryDocument(new GlossaryDocument());
BuildingBlock buildingBlock = new BuildingBlock(doc.getGlossaryDocument());
buildingBlock.setName("MyBlock");
buildingBlock.setGallery(BuildingBlockGallery.AUTO_TEXT);
buildingBlock.setCategory("General");
buildingBlock.setDescription("MyBlock description");
buildingBlock.setBehavior(BuildingBlockBehavior.PARAGRAPH);
doc.getGlossaryDocument().appendChild(buildingBlock);

// Create a source and add it as text content to our building block
Document buildingBlockSource = new Document();
DocumentBuilder buildingBlockSourceBuilder = new DocumentBuilder(buildingBlockSource);
buildingBlockSourceBuilder.writeln("Hello World!");

Node buildingBlockContent = doc.getGlossaryDocument().importNode(buildingBlockSource.getFirstSection(), true);
buildingBlock.appendChild(buildingBlockContent);

// Create an advance field using document builder
DocumentBuilder builder = new DocumentBuilder(doc);
FieldAutoText fieldAutoText = (FieldAutoText) builder.insertField(FieldType.FIELD_AUTO_TEXT, true);

// Refer to our building block by name
fieldAutoText.setEntryName("MyBlock");

Assert.assertEquals(fieldAutoText.getFieldCode(), " AUTOTEXT  MyBlock");

// Put additional templates here
doc.getFieldOptions().setBuiltInTemplatesPaths(new String[]{getMyDir() + "Busniess brochure.dotx"});

// We can also display our building block with a GLOSSARY field
FieldGlossary fieldGlossary = (FieldGlossary) builder.insertField(FieldType.FIELD_GLOSSARY, true);
fieldGlossary.setEntryName("MyBlock");

Assert.assertEquals(fieldGlossary.getFieldCode(), " GLOSSARY  MyBlock");

// The text content of our building block will be visible in the output
doc.updateFields();
doc.save(getArtifactsDir() + "Field.AUTOTEXT.dotx");

public UserInformation getCurrentUser() / public void setCurrentUser(UserInformation value)

Gets or sets the current user information.

Example:

Shows how to set user details and display them with fields.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Set user information
UserInformation userInformation = new UserInformation();
userInformation.setName("John Doe");
userInformation.setInitials("J. D.");
userInformation.setAddress("123 Main Street");
doc.getFieldOptions().setCurrentUser(userInformation);

// Insert fields that reference our user information
Assert.assertEquals(userInformation.getName(), builder.insertField(" USERNAME ").getResult());
Assert.assertEquals(userInformation.getInitials(), builder.insertField(" USERINITIALS ").getResult());
Assert.assertEquals(userInformation.getAddress(), builder.insertField(" USERADDRESS ").getResult());

// The field options object also has a static default user value that fields from many documents can refer to
UserInformation.getDefaultUser().setName("Default User");
UserInformation.getDefaultUser().setInitials("D. U.");
UserInformation.getDefaultUser().setAddress("One Microsoft Way");
doc.getFieldOptions().setCurrentUser(UserInformation.getDefaultUser());

Assert.assertEquals("Default User", builder.insertField(" USERNAME ").getResult());
Assert.assertEquals("D. U.", builder.insertField(" USERINITIALS ").getResult());
Assert.assertEquals("One Microsoft Way", builder.insertField(" USERADDRESS ").getResult());

doc.updateFields();
doc.save(getArtifactsDir() + "FieldOptions.FieldOptionsCurrentUser.docx");

public java.lang.String getCustomTocStyleSeparator() / public void setCustomTocStyleSeparator(java.lang.String value)

Gets or sets custom style separator for the \t switch in TOC field.

By default, custom styles defined by the \t switch in the TOC field are separated by a delimiter taken from the current culture. This property overrides that behaviour by specifying a user defined delimiter.

Example:

Shows how to insert a TOC and populate it with entries based on heading styles.

public void fieldToc() throws Exception {
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    // The table of contents we will insert will accept entries that are only within the scope of this bookmark
    builder.startBookmark("MyBookmark");

    // Insert a list num field using a document builder
    FieldToc field = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true);

    // Limit possible TOC entries to only those within the bookmark we name here
    field.setBookmarkName("MyBookmark");

    // Normally paragraphs with a "Heading n" style will be the only ones that will be added to a TOC as entries
    // We can set this attribute to include other styles, such as "Quote" and "Intense Quote" in this case
    field.setCustomStyles("Quote; 6; Intense Quote; 7");

    // Styles are normally separated by a comma (",") but we can use this property to set a custom delimiter
    doc.getFieldOptions().setCustomTocStyleSeparator(";");

    // Filter out any headings that are outside this range
    field.setHeadingLevelRange("1-3");

    // Headings in this range won't display their page number in their TOC entry
    field.setPageNumberOmittingLevelRange("2-5");

    field.setEntrySeparator("-");
    field.setInsertHyperlinks(true);
    field.setHideInWebLayout(false);
    field.setPreserveLineBreaks(true);
    field.setPreserveTabs(true);
    field.setUseParagraphOutlineLevel(false);

    insertNewPageWithHeading(builder, "First entry", "Heading 1");
    builder.writeln("Paragraph text.");
    insertNewPageWithHeading(builder, "Second entry", "Heading 1");
    insertNewPageWithHeading(builder, "Third entry", "Quote");
    insertNewPageWithHeading(builder, "Fourth entry", "Intense Quote");

    // These two headings will have the page numbers omitted because they are within the "2-5" range
    insertNewPageWithHeading(builder, "Fifth entry", "Heading 2");
    insertNewPageWithHeading(builder, "Sixth entry", "Heading 3");

    // This entry will be omitted because "Heading 4" is outside of the "1-3" range we set earlier
    insertNewPageWithHeading(builder, "Seventh entry", "Heading 4");

    builder.endBookmark("MyBookmark");
    builder.writeln("Paragraph text.");

    // This entry will be omitted because it is outside the bookmark specified by the TOC
    insertNewPageWithHeading(builder, "Eighth entry", "Heading 1");

    Assert.assertEquals(" TOC  \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w", field.getFieldCode());

    field.updatePageNumbers();
    doc.updateFields();
    doc.save(getArtifactsDir() + "Field.TOC.docx");

}

/// <summary>
/// Start a new page and insert a paragraph of a specified style.
/// </summary>
@Test(enabled = false)
public void insertNewPageWithHeading(final DocumentBuilder builder, final String captionText, final String styleName) {
    builder.insertBreak(BreakType.PAGE_BREAK);
    String originalStyle = builder.getParagraphFormat().getStyleName();
    builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(styleName));
    builder.writeln(captionText);
    builder.getParagraphFormat().setStyle(builder.getDocument().getStyles().get(originalStyle));
}

public java.lang.String getDefaultDocumentAuthor() / public void setDefaultDocumentAuthor(java.lang.String value)

Gets or sets default document author's name. If author's name is already specified in built-in document properties, this option is not considered.

Example:

Shows how to display a document creator's name with an AUTHOR field.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// If we open an existing document, the document's author's full name will be displayed by the field
// If we create a document programmatically, we need to set this attribute to the author's name so our field has something to display
doc.getFieldOptions().setDefaultDocumentAuthor("Joe Bloggs");

builder.write("This document was created by ");
FieldAuthor field = (FieldAuthor) builder.insertField(FieldType.FIELD_AUTHOR, true);
field.update();

Assert.assertEquals(field.getFieldCode(), " AUTHOR ");
Assert.assertEquals(field.getResult(), "Joe Bloggs");

// If this property has a value, it will supersede the one we set above
doc.getBuiltInDocumentProperties().setAuthor("John Doe");
field.update();

Assert.assertEquals(field.getFieldCode(), " AUTHOR ");
Assert.assertEquals(field.getResult(), "John Doe");

// Our field can also override the document's built in author name like this
field.setAuthorName("Jane Doe");
field.update();

Assert.assertEquals(field.getFieldCode(), " AUTHOR  \"Jane Doe\"");
Assert.assertEquals(field.getResult(), "Jane Doe");

// The author name in the built in properties was changed by the field, but the default document author stays the same
Assert.assertEquals(doc.getBuiltInDocumentProperties().getAuthor(), "Jane Doe");
Assert.assertEquals(doc.getFieldOptions().getDefaultDocumentAuthor(), "Joe Bloggs");

doc.save(getArtifactsDir() + "Field.AUTHOR.docx");

public int getFieldIndexFormat() / public void setFieldIndexFormat(int value)

Gets or sets a FieldIndexFormat that represents the formatting for the FieldIndex fields in the document. The value of the property is FieldIndexFormat integer constant.

public IFieldUpdateCultureProvider getFieldUpdateCultureProvider() / public void setFieldUpdateCultureProvider(IFieldUpdateCultureProvider value)

Gets or sets a provider that returns a culture object specific for each particular field.

The provider is requested when the value of FieldUpdateCultureSource is FieldUpdateCultureSource.FieldCode.

If the provider is present, then the culture object it returns is used for the field update. Otherwise, a system culture is used.

Example:

Shows how to specify a culture defining date/time formatting on per field basis.

public void defineDateTimeFormatting() throws Exception {
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    builder.insertField(FieldType.FIELD_TIME, true);

    doc.getFieldOptions().setFieldUpdateCultureSource(FieldUpdateCultureSource.FIELD_CODE);
    // Set a provider that return a culture object specific for each particular field
    doc.getFieldOptions().setFieldUpdateCultureProvider(new FieldUpdateCultureProvider());

    FieldTime fieldDate = (FieldTime) doc.getRange().getFields().get(0);
    if (fieldDate.getLocaleId() != (int) EditingLanguage.RUSSIAN)
        fieldDate.setLocaleId((int) EditingLanguage.RUSSIAN);

    doc.save(getArtifactsDir() + "FieldOptions.UpdateDateTimeFormatting.pdf");
}

/// <summary>
/// Provides a CultureInfo object that should be used during the update of a particular field.
/// </summary>
private static class FieldUpdateCultureProvider implements IFieldUpdateCultureProvider {
    /// <summary>
    /// Returns a CultureInfo object to be used during the field's update.
    /// </summary>
    public CultureInfo getCulture(String name, Field field) {
        switch (name) {
            case "ru-RU":
                CultureInfo culture = new CultureInfo(new Locale(name));
                DateTimeFormatInfo format = culture.getDateTimeFormat();

                format.setMonthNames(new String[]{"месяц 1", "месяц 2", "месяц 3", "месяц 4", "месяц 5", "месяц 6", "месяц 7", "месяц 8", "месяц 9", "месяц 10", "месяц 11", "месяц 12", ""});
                format.setMonthGenitiveNames(format.getMonthNames());
                format.setAbbreviatedMonthNames(new String[]{"мес 1", "мес 2", "мес 3", "мес 4", "мес 5", "мес 6", "мес 7", "мес 8", "мес 9", "мес 10", "мес 11", "мес 12", ""});
                format.setAbbreviatedMonthGenitiveNames(format.getAbbreviatedMonthNames());

                format.setDayNames(new String[]{"день недели 7", "день недели 1", "день недели 2", "день недели 3", "день недели 4", "день недели 5", "день недели 6"});
                format.setAbbreviatedDayNames(new String[]{"день 7", "день 1", "день 2", "день 3", "день 4", "день 5", "день 6"});
                format.setShortestDayNames(new String[]{"д7", "д1", "д2", "д3", "д4", "д5", "д6"});

                format.setAMDesignator("До полудня");
                format.setPMDesignator("После полудня");

                final String PATTERN = "yyyy MM (MMMM) dd (dddd) hh:mm:ss tt";
                format.setLongDatePattern(PATTERN);
                format.setLongTimePattern(PATTERN);
                format.setShortDatePattern(PATTERN);
                format.setShortTimePattern(PATTERN);

                return culture;
            case "en-US":
                return new CultureInfo(new Locale(name));
            default:
                return null;
        }
    }
}

public int getFieldUpdateCultureSource() / public void setFieldUpdateCultureSource(int value)

Specifies what culture to use to format the field result. The value of the property is FieldUpdateCultureSource integer constant.

By default, the culture of the current thread is used.

The setting affects only date/time fields with \\@ format switch.

public java.lang.String getFileName() / public void setFileName(java.lang.String value)

Gets or sets the file name of the document.

This property is used by the FILENAME field with higher priority than the Document.OriginalFileName property.

Example:

Shows how to use FieldOptions to override the default value for the FILENAME field.

Document doc = new Document(getMyDir() + "Document.docx");
DocumentBuilder builder = new DocumentBuilder(doc);

builder.moveToDocumentEnd();
builder.writeln();

// This FILENAME field will display the file name of the document we opened
FieldFileName field = (FieldFileName) builder.insertField(FieldType.FIELD_FILE_NAME, true);
field.update();

Assert.assertEquals(" FILENAME ", field.getFieldCode());
Assert.assertEquals("Document.docx", field.getResult());

builder.writeln();

// By default, the FILENAME field does not show the full path, and we can change this
field = (FieldFileName) builder.insertField(FieldType.FIELD_FILE_NAME, true);
field.setIncludeFullPath(true);

// We can override the values displayed by our FILENAME fields by setting this attribute
doc.getFieldOptions().setFileName("FieldOptions.FILENAME.docx");
field.update();

Assert.assertEquals(" FILENAME  \\p", field.getFieldCode());
Assert.assertEquals("FieldOptions.FILENAME.docx", field.getResult());

doc.updateFields();
doc.save(getArtifactsDir() + doc.getFieldOptions().getFileName());

public boolean isBidiTextSupportedOnUpdate() / public void isBidiTextSupportedOnUpdate(boolean value)

Gets or sets the value indicating whether bidirectional text is fully supported during field update or not.

When this property is set to true, additional steps are performed to produce Right-To-Left language (i.e. Arabic or Hebrew) compatible field result during its update.

When this property is set to false and Right-To-Left language is used, correctness of field result after its update is not guaranteed.

The default value is false.

Example:

Shows how to use FieldOptions to ensure that bi-directional text is properly supported during the field update.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Ensure that any field operation involving right-to-left text is performed correctly 
doc.getFieldOptions().isBidiTextSupportedOnUpdate(true);

// Use a document builder to insert a field which contains right-to-left text
FormField comboBox = builder.insertComboBox("MyComboBox", new String[]{"עֶשְׂרִים", "שְׁלוֹשִׁים", "אַרְבָּעִים", "חֲמִשִּׁים", "שִׁשִּׁים"}, 0);
comboBox.setCalculateOnExit(true);

doc.updateFields();
doc.save(getArtifactsDir() + "FieldOptions.FieldOptionsBidi.docx");

public boolean getLegacyNumberFormat() / public void setLegacyNumberFormat(boolean value)

Gets or sets the value indicating whether legacy (early than AW 13.10) number format for fields is enabled or not.

When this property is set to true, template symbol "#" worked as in .net: Replaces the pound sign with the corresponding digit if one is present; otherwise, no symbols appears in the result string.

When this property is set to false, template symbol "#" works as MS Word: This format item specifies the requisite numeric places to display in the result. If the result does not include a digit in that place, MS Word displays a space. For example, { = 9 + 6 \# $### } displays $ 15.

The default value is false.

Example:

Shows how use FieldOptions to change the number format.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Field field = builder.insertField("= 2 + 3 \\# $##");

Assert.assertEquals("$ 5", field.getResult());

doc.getFieldOptions().setLegacyNumberFormat(true);
field.update();

Assert.assertEquals("$5", field.getResult());

public com.aspose.words.net.System.Globalization.CultureInfo getPreProcessCulture() / public void setPreProcessCulture(com.aspose.words.net.System.Globalization.CultureInfo value)

Gets or sets the culture to preprocess field values.

Currently this property only affects value of the DOCPROPERTY field.

The default value is null. When this property is set to null, the DOCPROPERTY field's value is preprocessed with the culture controlled by the FieldUpdateCultureSource property.

Example:

Shows how to set the preprocess culture.

Document doc = new Document(getMyDir() + "Document.docx");
DocumentBuilder builder = new DocumentBuilder(doc);

doc.getFieldOptions().setPreProcessCulture(new CultureInfo("de-DE"));

Field field = builder.insertField(" DOCPROPERTY CreateTime");

// Conforming to the German culture, the date/time will be presented in the "dd.mm.yyyy hh:mm" format
Assert.assertTrue(field.getResult().matches("\\d{2}[.]\\d{2}[.]\\d{4} \\d{2}[:]\\d{2}"));

doc.getFieldOptions().setPreProcessCulture(new CultureInfo(Locale.ROOT));
field.update();

// After switching to the invariant culture, the date/time will be presented in the "mm/dd/yyyy hh:mm" format
Assert.assertTrue(field.getResult().matches("\\d{2}[/]\\d{2}[/]\\d{4} \\d{2}[:]\\d{2}"));

public IFieldResultFormatter getResultFormatter() / public void setResultFormatter(IFieldResultFormatter value)

Allows to control how the field result is formatted.

public ToaCategories getToaCategories() / public void setToaCategories(ToaCategories value)

Gets or sets the table of authorities categories.

Example:

Shows how to specify a table of authorities categories for a document.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// There are default category values we can use, or we can make our own like this
ToaCategories toaCategories = new ToaCategories();
doc.getFieldOptions().setToaCategories(toaCategories);

toaCategories.set(1, "My Category 1"); // Replaces default value "Cases"
toaCategories.set(2, "My Category 2"); // Replaces default value "Statutes"

// Even if we changed the categories in the FieldOptions object, the default categories are still available here
Assert.assertEquals("Cases", ToaCategories.getDefaultCategories().get(1));
Assert.assertEquals("Statutes", ToaCategories.getDefaultCategories().get(2));

// Insert 2 tables of authorities, one per category
builder.insertField("TOA \\c 1 \\h", null);
builder.insertField("TOA \\c 2 \\h", null);
builder.insertBreak(BreakType.PAGE_BREAK);

// Insert table of authorities entries across 2 categories
builder.insertField("TA \\c 2 \\l \"entry 1\"");
builder.insertBreak(BreakType.PAGE_BREAK);
builder.insertField("TA \\c 1 \\l \"entry 2\"");
builder.insertBreak(BreakType.PAGE_BREAK);
builder.insertField("TA \\c 2 \\l \"entry 3\"");

doc.updateFields();
doc.save(getArtifactsDir() + "FieldOptions.TOA.Categories.docx");

public boolean getUseInvariantCultureNumberFormat() / public void setUseInvariantCultureNumberFormat(boolean value)

Gets or sets the value indicating that number format is parsed using invariant culture or not

When this property is set to true, number format is taken from an invariant culture.

When this property is set to false, number format is taken from the current thread's culture.

The default value is false.

Example:

Shows how to format numbers according to the invariant culture.

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Locale.setDefault(new Locale("de-DE"));
Field field = builder.insertField(" = 1234567,89 \\# $#,###,###.##");
field.update();

// The combination of field, number format and thread culture can sometimes produce an unsuitable result
Assert.assertFalse(doc.getFieldOptions().getUseInvariantCultureNumberFormat());
Assert.assertEquals("$123,456,789.  ", field.getResult());

// We can set this attribute to avoid changing the whole thread culture just for numeric formats
doc.getFieldOptions().setUseInvariantCultureNumberFormat(true);
field.update();
Assert.assertEquals("$123,456,789.  ", field.getResult());

public IFieldUserPromptRespondent getUserPromptRespondent() / public void setUserPromptRespondent(IFieldUserPromptRespondent value)

Gets or sets the respondent to user prompts during field update.

If the value of this property is set to null, the fields that require user response on prompting (such as ASK or FILLIN) are not updated.

The default value is null.

Example:

Shows how to create an ASK field and set its properties.

@Test
public void fieldAsk() throws Exception {
    Document doc = new Document();
    DocumentBuilder builder = new DocumentBuilder(doc);

    // Place a field where the response to our ASK field will be placed
    FieldRef fieldRef = (FieldRef) builder.insertField(FieldType.FIELD_REF, true);
    fieldRef.setBookmarkName("MyAskField");
    builder.writeln();

    // Insert the ASK field and edit its properties, making sure to reference our REF field
    FieldAsk fieldAsk = (FieldAsk) builder.insertField(FieldType.FIELD_ASK, true);
    fieldAsk.setBookmarkName("MyAskField");
    fieldAsk.setPromptText("Please provide a response for this ASK field");
    fieldAsk.setDefaultResponse("Response from within the field.");
    fieldAsk.setPromptOnceOnMailMerge(true);
    builder.writeln();

    // ASK fields apply the default response to their respective REF fields during a mail merge
    DataTable table = new DataTable("My Table");
    table.getColumns().add("Column 1");
    table.getRows().add("Row 1");
    table.getRows().add("Row 2");

    FieldMergeField fieldMergeField = (FieldMergeField) builder.insertField(FieldType.FIELD_MERGE_FIELD, true);
    fieldMergeField.setFieldName("Column 1");

    // We can modify or override the default response in our ASK fields with a custom prompt responder, which will take place during a mail merge
    doc.getFieldOptions().setUserPromptRespondent(new MyPromptRespondent());
    doc.getMailMerge().execute(table);

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

    Assert.assertEquals(" REF  MyAskField", fieldRef.getFieldCode());
    Assert.assertEquals(
            " ASK  MyAskField \"Please provide a response for this ASK field\" \\d \"Response from within the field.\" \\o",
            fieldAsk.getFieldCode());
}

/// <summary>
/// IFieldUserPromptRespondent implementation that appends a line to the default response of an ASK field during a mail merge.
/// </summary>
private static class MyPromptRespondent implements IFieldUserPromptRespondent {
    public String respond(final String promptText, final String defaultResponse) {
        return "Response from MyPromptRespondent. " + defaultResponse;
    }
}