move_to_merge_field method

move_to_merge_field(field_name)

Moves the cursor to a position just beyond the specified merge field and removes the merge field.

def move_to_merge_field(self, field_name: str):
    ...

Parameter	Type	Description
field_name	str	The case-insensitive name of the mail merge field.

Remarks

Note that this method deletes the merge field from the document after moving the cursor.

Returns

True if the merge field was found and the cursor was moved; False otherwise.

move_to_merge_field(field_name, is_after, is_delete_field)

Moves the merge field to the specified merge field.

def move_to_merge_field(self, field_name: str, is_after: bool, is_delete_field: bool):
    ...

Parameter	Type	Description
field_name	str	The case-insensitive name of the mail merge field.
is_after	bool	When True, moves the cursor to be after the field end. When False, moves the cursor to be before the field start.
is_delete_field	bool	When True, deletes the merge field.

Returns

True if the merge field was found and the cursor was moved; False otherwise.

Examples

Shows how to fill MERGEFIELDs with data with a document builder instead of a mail merge.

doc = aw.Document()
builder = aw.DocumentBuilder(doc)
# Insert some MERGEFIELDS, which accept data from columns of the same name in a data source during a mail merge,
# and then fill them manually.
builder.insert_field(field_code=' MERGEFIELD Chairman ')
builder.insert_field(field_code=' MERGEFIELD ChiefFinancialOfficer ')
builder.insert_field(field_code=' MERGEFIELD ChiefTechnologyOfficer ')
builder.move_to_merge_field(field_name='Chairman')
builder.bold = True
builder.writeln('John Doe')
builder.move_to_merge_field(field_name='ChiefFinancialOfficer')
builder.italic = True
builder.writeln('Jane Doe')
builder.move_to_merge_field(field_name='ChiefTechnologyOfficer')
builder.italic = True
builder.writeln('John Bloggs')
doc.save(file_name=ARTIFACTS_DIR + 'DocumentBuilder.FillMergeFields.docx')

Shows how to insert fields, and move the document builder’s cursor to them.

doc = aw.Document()
builder = aw.DocumentBuilder(doc)
builder.insert_field('MERGEFIELD MyMergeField1 \\* MERGEFORMAT')
builder.insert_field('MERGEFIELD MyMergeField2 \\* MERGEFORMAT')
# Move the cursor to the first MERGEFIELD.
builder.move_to_merge_field('MyMergeField1', True, False)
# Note that the cursor is placed immediately after the first MERGEFIELD, and before the second.
self.assertEqual(doc.range.fields[1].start, builder.current_node)
self.assertEqual(doc.range.fields[0].end, builder.current_node.previous_sibling)
# If we wish to edit the field's field code or contents using the builder,
# its cursor would need to be inside a field.
# To place it inside a field, we would need to call the document builder's "move_to" method
# and pass the field's start or separator node as an argument.
builder.write(' Text between our merge fields. ')
doc.save(ARTIFACTS_DIR + 'DocumentBuilder.merge_fields.docx')

See Also

• module aspose.words
• class DocumentBuilder