java.lang.Objectcom.aspose.words.FieldOptions
public class FieldOptions
Example:
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
// Insert two merge fields with German locale
builder.getFont().setLocaleId(1031);
builder.insertField("MERGEFIELD Date1 \\@ \"dddd, d MMMM yyyy\"");
builder.write(" - ");
builder.insertField("MERGEFIELD Date2 \\@ \"dddd, d MMMM yyyy\"");
// Store the current culture in a variable and explicitly set it to US English
Locale currentLocale = Locale.getDefault();
Locale.setDefault(new Locale("en", "US"));
// Execute a mail merge for the first MERGEFIELD using the current culture (US English) for date formatting
doc.getMailMerge().execute(new String[]{"Date1"}, new Object[]{new SimpleDateFormat("yyyy/MM/DD").parse("2011/01/01")});
// Execute a mail merge for the second MERGEFIELD using the field's culture (German) for date formatting
doc.getFieldOptions().setFieldUpdateCultureSource(FieldUpdateCultureSource.FIELD_CODE);
doc.getMailMerge().execute(new String[]{"Date2"}, new Object[]{new SimpleDateFormat("yyyy/MM/DD").parse("2011/01/01")});
// The first MERGEFIELD has received a date formatted in English, while the second one is in German
Assert.assertEquals(doc.getRange().getText().trim(), "Saturday, 1 January 2011 - Samstag, 1 Januar 2011");
// Restore the original culture
Locale.setDefault(currentLocale);
Property Getters/Setters Summary | ||
---|---|---|
IBarcodeGenerator | getBarcodeGenerator() | |
void | setBarcodeGenerator(IBarcodeGenerator value) | |
Gets or set custom barcode generator. | ||
java.lang.String[] | getBuiltInTemplatesPaths() | |
void | setBuiltInTemplatesPaths(java.lang.String[] value) | |
Gets or sets paths of MS Word built-in templates. | ||
UserInformation | getCurrentUser() | |
void | setCurrentUser(UserInformation value) | |
Gets or sets the current user information. | ||
java.lang.String | getCustomTocStyleSeparator() | |
void | setCustomTocStyleSeparator(java.lang.String value) | |
Gets or sets custom style separator for the \t switch in TOC field. | ||
java.lang.String | getDefaultDocumentAuthor() | |
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. | ||
IFieldUpdateCultureProvider | getFieldUpdateCultureProvider() | |
void | setFieldUpdateCultureProvider(IFieldUpdateCultureProvider value) | |
Gets or sets a provider that returns a culture object specific for each particular field. | ||
int | getFieldUpdateCultureSource() | |
void | setFieldUpdateCultureSource(int value) | |
Specifies what culture to use to format the field result. The value of the property is FieldUpdateCultureSource integer constant. | ||
java.lang.String | getFileName() | |
void | setFileName(java.lang.String value) | |
Gets or sets the file name of the document. | ||
boolean | isBidiTextSupportedOnUpdate() | |
void | isBidiTextSupportedOnUpdate(boolean value) | |
Gets or sets the value indicating whether bidirectional text is fully supported during field update or not. | ||
boolean | getLegacyNumberFormat() | |
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. | ||
System.Globalization.CultureInfo | getPreProcessCulture() | |
Gets or sets the culture to preprocess field values. | ||
IFieldResultFormatter | getResultFormatter() | |
void | setResultFormatter(IFieldResultFormatter value) | |
Allows to control how the field result is formatted. | ||
ToaCategories | getToaCategories() | |
void | setToaCategories(ToaCategories value) | |
Gets or sets the table of authorities categories. | ||
boolean | getUseInvariantCultureNumberFormat() | |
void | setUseInvariantCultureNumberFormat(boolean value) | |
Gets or sets the value indicating that number format is parsed using invariant culture or not | ||
IFieldUserPromptRespondent | getUserPromptRespondent() | |
void | setUserPromptRespondent(IFieldUserPromptRespondent value) | |
Gets or sets the respondent to user prompts during field update. |
Property Getters/Setters Detail |
---|
getBarcodeGenerator/setBarcodeGenerator | |
public IBarcodeGenerator getBarcodeGenerator() / public void setBarcodeGenerator(IBarcodeGenerator value) |
Example:
Shows how to create barcode images using a barcode generator.public void barcodeGenerator() throws Exception { 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"); }
getBuiltInTemplatesPaths/setBuiltInTemplatesPaths | |
public java.lang.String[] getBuiltInTemplatesPaths() / public void setBuiltInTemplatesPaths(java.lang.String[] value) |
This property is used by the AUTOTEXT and GLOSSARY fields, if referenced auto text entry is not found in the
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");
getCurrentUser/setCurrentUser | |
public UserInformation getCurrentUser() / public void setCurrentUser(UserInformation value) |
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");
getCustomTocStyleSeparator/setCustomTocStyleSeparator | |
public java.lang.String getCustomTocStyleSeparator() / public void setCustomTocStyleSeparator(java.lang.String value) |
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 fieldToc = (FieldToc) builder.insertField(FieldType.FIELD_TOC, true); // Limit possible TOC entries to only those within the bookmark we name here fieldToc.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 fieldToc.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 fieldToc.setHeadingLevelRange("1-3"); // Headings in this range won't display their page number in their TOC entry fieldToc.setPageNumberOmittingLevelRange("2-5"); fieldToc.setEntrySeparator("-"); fieldToc.setInsertHyperlinks(true); fieldToc.setHideInWebLayout(false); fieldToc.setPreserveLineBreaks(true); fieldToc.setPreserveTabs(true); fieldToc.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(fieldToc.getFieldCode(), " TOC \\b MyBookmark \\t \"Quote; 6; Intense Quote; 7\" \\o 1-3 \\n 2-5 \\p - \\h \\x \\w"); fieldToc.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)); }
getDefaultDocumentAuthor/setDefaultDocumentAuthor | |
public java.lang.String getDefaultDocumentAuthor() / public void setDefaultDocumentAuthor(java.lang.String value) |
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");
getFieldUpdateCultureProvider/setFieldUpdateCultureProvider | |
public IFieldUpdateCultureProvider getFieldUpdateCultureProvider() / public void setFieldUpdateCultureProvider(IFieldUpdateCultureProvider value) |
The provider is requested when the value of
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 specifying a culture defining date/time formatting on per field basis@Test 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() != EditingLanguage.RUSSIAN) fieldDate.setLocaleId(EditingLanguage.RUSSIAN); doc.save(getArtifactsDir() + "Field.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(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(name); default: return null; } } }
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; } } }
getFieldUpdateCultureSource/setFieldUpdateCultureSource | |
public int getFieldUpdateCultureSource() / public void setFieldUpdateCultureSource(int value) |
By default, the culture of the current thread is used.
The setting affects only date/time fields with \\@ format switch.
Example:
Shows how to specify where the culture used for date formatting during field update and mail merge is chosen from.Document doc = new Document(); DocumentBuilder builder = new DocumentBuilder(doc); // Insert two merge fields with German locale builder.getFont().setLocaleId(1031); builder.insertField("MERGEFIELD Date1 \\@ \"dddd, d MMMM yyyy\""); builder.write(" - "); builder.insertField("MERGEFIELD Date2 \\@ \"dddd, d MMMM yyyy\""); // Store the current culture in a variable and explicitly set it to US English Locale currentLocale = Locale.getDefault(); Locale.setDefault(new Locale("en", "US")); // Execute a mail merge for the first MERGEFIELD using the current culture (US English) for date formatting doc.getMailMerge().execute(new String[]{"Date1"}, new Object[]{new SimpleDateFormat("yyyy/MM/DD").parse("2011/01/01")}); // Execute a mail merge for the second MERGEFIELD using the field's culture (German) for date formatting doc.getFieldOptions().setFieldUpdateCultureSource(FieldUpdateCultureSource.FIELD_CODE); doc.getMailMerge().execute(new String[]{"Date2"}, new Object[]{new SimpleDateFormat("yyyy/MM/DD").parse("2011/01/01")}); // The first MERGEFIELD has received a date formatted in English, while the second one is in German Assert.assertEquals(doc.getRange().getText().trim(), "Saturday, 1 January 2011 - Samstag, 1 Januar 2011"); // Restore the original culture Locale.setDefault(currentLocale);
getFileName/setFileName | |
public java.lang.String getFileName() / public void setFileName(java.lang.String value) |
This property is used by the FILENAME field with higher priority than the
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());
isBidiTextSupportedOnUpdate/isBidiTextSupportedOnUpdate | |
public boolean isBidiTextSupportedOnUpdate() / public void isBidiTextSupportedOnUpdate(boolean value) |
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");
getLegacyNumberFormat/setLegacyNumberFormat | |
public boolean getLegacyNumberFormat() / public void setLegacyNumberFormat(boolean value) |
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());
getPreProcessCulture | |
public System.Globalization.CultureInfo getPreProcessCulture() |
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
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}"));
getResultFormatter/setResultFormatter | |
public IFieldResultFormatter getResultFormatter() / public void setResultFormatter(IFieldResultFormatter value) |
Example:
Shows how to control how the field result is formatted.public void fieldResultFormatting() throws Exception { Document doc = new Document(); DocumentBuilder builder = new DocumentBuilder(doc); doc.getFieldOptions().setResultFormatter(new FieldResultFormatter("${0}", "Date: {0}", "Item # {0}:")); // Insert a field with a numeric format builder.insertField(" = 2 + 3 \\# $###", null); // Insert a field with a date/time format builder.insertField("DATE \\@ \"d MMMM yyyy\"", null); // Insert a field with a general format builder.insertField("QUOTE \"2\" \\* Ordinal", null); // Formats will be applied and recorded by the formatter during the field update doc.updateFields(); ((FieldResultFormatter) doc.getFieldOptions().getResultFormatter()).printInvocations(); // Our formatter has also overridden the formats that were originally applied in the fields Assert.assertEquals(doc.getRange().getFields().get(0).getResult(), "$5"); Assert.assertTrue(doc.getRange().getFields().get(1).getResult().startsWith("Date: ")); Assert.assertEquals(doc.getRange().getFields().get(2).getResult(), "Item # 2:"); } /// <summary> /// Custom IFieldResult implementation that applies formats and tracks format invocations /// </summary> private static class FieldResultFormatter implements IFieldResultFormatter { public FieldResultFormatter(final String numberFormat, final String dateFormat, final String generalFormat) { mNumberFormat = numberFormat; mDateFormat = dateFormat; mGeneralFormat = generalFormat; } public String formatNumeric(final double value, final String format) { mNumberFormatInvocations.add(new Object[]{value, format}); return (mNumberFormat == null || "".equals(mNumberFormat)) ? null : MessageFormat.format(mNumberFormat, value); } public String formatDateTime(final Date value, final String format, final int calendarType) { mDateFormatInvocations.add(new Object[]{value, format, calendarType}); return (mDateFormat == null || "".equals(mDateFormat)) ? null : MessageFormat.format(mDateFormat, value); } public String format(final String value, final int format) { return format((Object) value, format); } public String format(final double value, final int format) { return format((Object) value, format); } private String format(final Object value, final int format) { mGeneralFormatInvocations.add(new Object[]{value, format}); return (mGeneralFormat == null || "".equals(mGeneralFormat)) ? null : MessageFormat.format(mGeneralFormat, value); } public void printInvocations() { System.out.println(MessageFormat.format("Number format invocations ({0}):", mNumberFormatInvocations.size())); for (Object[] s : (Iterable<Object[]>) mNumberFormatInvocations) { System.out.println("\tValue: " + s[0] + ", original format: " + s[1]); } System.out.println(MessageFormat.format("Date format invocations ({0}):", mDateFormatInvocations.size())); for (Object[] s : (Iterable<Object[]>) mDateFormatInvocations) { System.out.println("\tValue: " + s[0] + ", original format: " + s[1] + ", calendar type: " + s[2]); } System.out.println(MessageFormat.format("General format invocations ({0}):", mGeneralFormatInvocations.size())); for (Object[] s : (Iterable<Object[]>) mGeneralFormatInvocations) { System.out.println("\tValue: " + s[0] + ", original format: " + s[1]); } } private String mNumberFormat; private String mDateFormat; private String mGeneralFormat; private ArrayList mNumberFormatInvocations = new ArrayList(); private ArrayList mDateFormatInvocations = new ArrayList(); private ArrayList mGeneralFormatInvocations = new ArrayList(); }
getToaCategories/setToaCategories | |
public ToaCategories getToaCategories() / public void setToaCategories(ToaCategories value) |
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");
getUseInvariantCultureNumberFormat/setUseInvariantCultureNumberFormat | |
public boolean getUseInvariantCultureNumberFormat() / public void setUseInvariantCultureNumberFormat(boolean value) |
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());
getUserPromptRespondent/setUserPromptRespondent | |
public IFieldUserPromptRespondent getUserPromptRespondent() / public void setUserPromptRespondent(IFieldUserPromptRespondent value) |
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(fieldAsk.getFieldCode(), " ASK MyAskField \"Please provide a response for this ASK field\" \\d \"Response from within the field.\" \\o"); } /// <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; } }