Field class

Field class

Represents a Microsoft Word document field. To learn more, visit the Working with Fields documentation article.

Remarks

A field in a Word document is a complex structure consisting of multiple nodes that include field start, field code, field separator, field result and field end. Fields can be nested, contain rich content and span multiple paragraphs or sections in a document. The Field class is a “facade” object that provides properties and methods that allow to work with a field as a single object.

The Field.start, Field.separator and Field.end properties point to the field start, separator and end nodes of the field respectively.

The content between the field start and separator is the field code. The content between the field separator and field end is the field result. The field code typically consists of one or more Run objects that specify instructions. The processing application is expected to execute the field code to calculate the field result.

The process of calculating field results is called the field update. Aspose.Words can update field results of most of the field types in exactly the same way as Microsoft Word does it. Most notably, Aspose.Words can calculate results of even the most complex formula fields. To calculate the field result of a single field use the Field.update() method. To update fields in the whole document use Document.update_fields().

You can get the plain text version of the field code using the Field.get_field_code() method. You can get and set the plain text version of the field result using the Field.result property. Both the field code and field result can contain complex content, such as nested fields, paragraphs, shapes, tables and in this case you might want to work with the field nodes directly if you need more control.

You do not create instances of the Field class directly. To create a new field use the DocumentBuilder.insert_field() method.

Properties

Name	Description
display_result	Gets the text that represents the displayed field result.
end	Gets the node that represents the field end.
format	Gets a FieldFormat object that provides typed access to field’s formatting.
is_dirty	Gets or sets whether the current result of the field is no longer correct (stale) due to other modifications made to the document.
is_locked	Gets or sets whether the field is locked (should not recalculate its result).
locale_id	Gets or sets the LCID of the field.
result	Gets or sets text that is between the field separator and field end.
separator	Gets the node that represents the field separator. Can be None.
start	Gets the node that represents the start of the field.
type	Gets the Microsoft Word field type.

Methods

Name	Description
as_field()
as_field_add_in()
as_field_address_block()
as_field_advance()
as_field_ask()
as_field_author()
as_field_auto_num()
as_field_auto_num_lgl()
as_field_auto_num_out()
as_field_auto_text()
as_field_auto_text_list()
as_field_barcode()
as_field_bibliography()
as_field_bidi_outline()
as_field_citation()
as_field_comments()
as_field_compare()
as_field_create_date()
as_field_data()
as_field_database()
as_field_date()
as_field_dde()
as_field_dde_auto()
as_field_display_barcode()
as_field_doc_property()
as_field_doc_variable()
as_field_edit_time()
as_field_embed()
as_field_eq()
as_field_file_name()
as_field_file_size()
as_field_fill_in()
as_field_footnote_ref()
as_field_form_check_box()
as_field_form_drop_down()
as_field_form_text()
as_field_formula()
as_field_glossary()
as_field_go_to_button()
as_field_greeting_line()
as_field_hyperlink()
as_field_if()
as_field_import()
as_field_include()
as_field_include_picture()
as_field_include_text()
as_field_index()
as_field_info()
as_field_keywords()
as_field_last_saved_by()
as_field_link()
as_field_list_num()
as_field_macro_button()
as_field_merge_barcode()
as_field_merge_field()
as_field_merge_rec()
as_field_merge_seq()
as_field_next()
as_field_next_if()
as_field_note_ref()
as_field_num_chars()
as_field_num_pages()
as_field_num_words()
as_field_ocx()
as_field_page()
as_field_page_ref()
as_field_print()
as_field_print_date()
as_field_private()
as_field_quote()
as_field_rd()
as_field_ref()
as_field_rev_num()
as_field_save_date()
as_field_section()
as_field_section_pages()
as_field_seq()
as_field_set()
as_field_shape()
as_field_skip_if()
as_field_style_ref()
as_field_subject()
as_field_symbol()
as_field_ta()
as_field_tc()
as_field_template()
as_field_time()
as_field_title()
as_field_toa()
as_field_toc()
as_field_unknown()
as_field_user_address()
as_field_user_initials()
as_field_user_name()
as_field_xe()
get_field_code()	Returns text between field start and field separator (or field end if there is no separator). Both field code and field result of child fields are included.
get_field_code(include_child_field_codes)	Returns text between field start and field separator (or field end if there is no separator).
remove()	Removes the field from the document. Returns a node right after the field. If the field’s end is the last child of its parent node, returns its parent paragraph. If the field is already removed, returns None.
unlink()	Performs the field unlink.
update()	Performs the field update. Throws if the field is being updated already.
update(ignore_merge_format)	Performs a field update. Throws if the field is being updated already.

Examples

Shows how to insert a field into a document using a field code.

doc = aw.Document()
builder = aw.DocumentBuilder(doc)
field = builder.insert_field('DATE \\@ "dddd, MMMM dd, yyyy"')
self.assertEqual(aw.fields.FieldType.FIELD_DATE, field.type)
self.assertEqual('DATE \\@ "dddd, MMMM dd, yyyy"', field.get_field_code())
# This overload of the "insert_field" method automatically updates inserted fields.
self.assertAlmostEqual(datetime.datetime.strptime(field.result, '%A, %B %d, %Y'), datetime.datetime.now(), delta=timedelta(1))

See Also

• module aspose.words.fields