.NET Word Processing API and UI Components - How to Use Fields to Create a Holiday Party Invitation

With the winter holidays upon us, some of you may be busy sending electronic greeting cards, invitations, and other mailouts to your family, friends, and business associates.

The purpose of this blog post is to illustrate the use of our word processing products to automate this document generation process and demonstrate the ease with which you can insert dynamic content into your documents. We’ll show you how to use fields to generate a holiday party invitation and also review a couple of field-related enhancements we introduced in our most recent major release (v21.2).

Add Fields to the Template

For this blog post, we’ll use the following document template:

We will use the DevExpress Word Processing Document API to replace static strings (“party date”, “time”, “response date”, and "manager”) in the document template with fields.

Note: You’ll need to call the FieldCollection.Create method to add a new field. This method allows you to convert text to a field, or insert a field at a specified document position. See the following topic for a full list of supported fields: Field Codes.

You can add code switches to define formats for numeric, text, date, and time fields. Refer to the following topic for a full list of supported field format switches: Format Switches.

The code sample below creates a DOCPROPERTY field (to insert the party date) and a TIME field with the H:mm am/pm format:

private static void CreateFields(Document document)
{
  // Create a “Party Date” custom document property
  document.CustomProperties["Party Date"] = new DateTime(2021, 12, 23); 

  // Find the “Party Date” phrase
  DocumentRange[] dateRanges = document.FindAll("Party Date", SearchOptions.WholeWord);
  DocumentPosition datePosition = dateRanges[0].End; 

  // Delete the phrase
  document.Delete(dateRanges[0]); 

  // Create a field at the phrase’s position
  document.Fields.Create(datePosition, @"DOCPROPERTY ""Party Date"""); 

  // Find the word “Time”
  DocumentRange[] timeRanges = document.FindAll("Time", SearchOptions.WholeWord);
  DocumentPosition timePosition = timeRanges[0].End; 

  // Delete the phrase
  document.Delete(timeRanges[0]);

  // Create a field at the phrase’s position
  document.Fields.Create(timePosition, @" TIME \@ ""H:mm AM/PM""");
}

DOCVARIABLE Fields

The DOCVARIABLE field allows you to insert any type of content into a document – from a simple variable to dynamic data from a database or another document. Explore our DOCVARIABLE field (dynamic content) demo to see how easy it can be to insert RSS data into a document: Dynamic Content.

Variables can be stored in a document or calculated within the CalculateDocumentVariable event. In this example, we created a Response Date variable to calculate the response deadline.

private static void CalculateResponseDate(Document document)
{
  // Obtain the Party Date property value
  DateTime date = (DateTime)document.CustomProperties["Party Date"]; 

  // Specify the interval between the response and party dates
  var responseBefore = new TimeSpan(7, 0, 0, 0); 

  // Calculate the response date
  DateTime responseDate = date.Subtract(responseBefore); 

  // Create a new document variable
  document.Variables.Add("Response Date", responseDate);
}

You can add fields to any portion of the document: main body, header, footer, text box, footnote, or endnote. The code sample below adds our “Response Date” variable and the DOCPROPERTY field (that inserts the manager’s name) to the document footer:

private static void CreateFieldsInFooter(Document document)
{
  // Start the footer update
  var footer = document.Sections[0].BeginUpdateFooter(HeaderFooterType.Primary);
  
  // Find the word “Manager”
  DocumentRange[] managerRanges = footer.FindAll("Manager", SearchOptions.WholeWord); 

  // Convert the found text to a field
  Field managerField = footer.Fields.Create(managerRanges[0]); 

  // Insert the field name 
  footer.InsertText(managerField.CodeRange.Start, "DOCPROPERTY "); 

  // Find the “Response Date” phrase
  DocumentRange[] responseRanges =
      footer.FindAll("Response Date", SearchOptions.WholeWord);
  DocumentPosition responsePosition = responseRanges[0].End; 

  // Remove the phrase 
  footer.Delete(responseRanges[0]); 

  // Create a field at the phrase’s position 
  footer.Fields.Create(responsePosition, @" DOCVARIABLE ""Response Date"""); 

 // Finalize the footer update
 document.Sections[0].EndUpdateFooter(footer);
}

A new UpdateFieldOptions.DocVariable property (implemented in v21.2) allows you to preserve DOCVARIABLE field value when the document is loaded. For example, if you need to change the party date while keeping the response date the same. Set the UpdateFieldOptions.DocVariable property to false within the BeforeImport event handler, as shown below.

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.Import;

wordProcessor.BeforeImport += WordProcessor_BeforeImport; 

private static void WordProcessor_BeforeImport(object sender, BeforeImportEventArgs e)
{
  if (e.DocumentFormat == DocumentFormat.OpenXml)
  { 
    ((OpenXmlDocumentImporterOptions)e.Options).UpdateField.DocVariable = false;
  }
}

If you re-load the document now, change the party date, and save the result, you’ll see that the DOCVARIABLE field still displays the same date:

Update Fields and Save the Result

After you insert fields, update them to insert actual field data, and then save the document. In previous versions, you had to call the FieldCollection.Update method for each individual document section (header, main body, footnote, and others). In v21.2, we added the Document.UpdateAllFields method to update all document fields simultaneously.

The code sample below utilizes all methods created in previous examples, updates all document fields, and saves the result:

using DevExpress.XtraRichEdit;
using DevExpress.XtraRichEdit.API.Native;

using (var wordProcessor = new RichEditDocumentServer())
{
  // Load a document
  wordProcessor.LoadDocument(“party invitation.docx”);
  Document document = wordProcessor.Document; 

  // Create fields
  CreateFields(document);
  CalculateResponseDate(document);
  CreateFieldsInFooter(document); 

  // Update all fields
  document.UpdateAllFields(); 

  // Save the result
  wordProcessor.SaveDocument(“party invitation_docx.docx”, DocumentFormat.OpenXml);
}

Let’s switch to the Rich Text Editor for WinForms and look at our results. You can add and modify fields via the Rich Text Editor’s UI. Press CTRL+F9 to insert a field, and ALT+F9 (or click Toggle Field Codes in the context menu) to modify a field.

If the holiday skin applied to the Rich Text Editor caught your eye, check out the following blog post for information on how to add a bit of a holiday spirit to your application: WinForms — New Winter Joy Vector Skin.

If fields are no longer needed, you can replace them with their values (unlink the fields). DevExpress Word Processing products (v21.2+) ship with the following methods that can help you with this requirement:

• Field.Unlink— unlinks an individual field
• FieldCollection.Unlink— unlinks all fields in a specific document portion
• Document.UnlinkAllFields— unlinks all document fields

In this example, we added a custom button that unlinks all fields and opens the Save As dialog to save the result.

using DevExpress.XtraBars;

private void unlinkButton_ItemClick(object sender, ItemClickEventArgs e)
{
  richEditControl.Document.UnlinkAllFields();
  richEditControl.SaveDocumentAs();
}

If you liked our party invitation template, you can download it here: Party Invitation. Print or export the invitation to a PDF file, or save it as a Word document.

We wish all of you the best this holiday season and in the coming year.

Your Feedback Matters

Let us know what you think about the field enhancements described in this blog post. And if you have specific questions or need assistance with the DevExpress Word Processing product line, feel free to contact us through the DevExpress Support Center (support@devexpress.com).