Fields
Fields in word document are used as placeholders to display the dynamic information such as date, page number, table of contents etc. These fields are defined using a combination of a FieldCode and FieldResult. The FieldCode represents a set of instructions which are evaluated to generate the dynamic content. When the document is rendered, the field codes implicitly execute the set of instruction and inserts the text, graphics, etc. in the document. The text or element that is inserted is referred to as FieldResult.
MS Word has a defined set of FieldCodes which are supported in GcWord. All these FieldCodes can be added to the word document either as a SimpleField or as a ComplexField depending on whether the FieldResult is rendered as a single run or multiple runs.
For example, the "DATE" field code inserts the current date in the document, which is a single run of text. When using this FieldCode in a document, the inserted date has the same formatting such as font, font size etc. In such scenario, the DATE field should be implemented as a SimpleField as the FieldResult is to be rendered as a single run. But, in case you need to render each part of the date with different formatting, three runs would be required to render a single date. Hence, in this case, the DATE FieldCode should be implemented as a ComplexField.
GcWord supports two types of field elements, simple field element and complex field element, to hold such dynamic information. These simple and complex field elements are represented by the SimpleField and ComplexField class respectively.
Add Simple Field
To add a simple field in a document, you can use Add method of the SimpleFieldCollection class. The following sample code adds two Fields i.e DATE and TIME to the Document using the SimpleField class.
Section section = doc.Body.Sections.First;
// Add the paragraph:
section.GetRange().Paragraphs.Add("Simple Field Example");
var p0 = section.GetRange().Paragraphs.Add("DATE field with default formatting: ");
//Add Date Field
p0.GetRange().SimpleFields.Add("DATE \\@ \"d-MMM-yy\"");
//Add a Run in the paragraph
p0.GetRange().Runs.Add("\rTIME field with default formatting: ");
//Add Time Field
p0.GetRange().SimpleFields.Add("TIME");
//Save the document
doc.Save("AddSimpleField.docx");
Modify Simple Field
To modify a simple field:
Access the field collection using SimpleFields property of the RangeBase class and get a reference to a specific field. For example, the first field of the collection.
Modify the field code using Code property of the SimpleField class.
doc.Load("AddSimpleField.docx"); //Modify the simple field doc.Body.Sections.First.GetRange().Paragraphs[2].GetRange().SimpleFields.First.Code = "DATE \\@ \"dd-MM-yy\""; //Save the document doc.Save("ModifySimpleField.docx");
Delete Simple Field
To delete a simple field, access a simple field from the field collection using SimpleFields property of the RangeBase class and delete it using the Delete method.
doc.Load("AddSimpleField.docx");
//Delete a simple field
doc.Body.Sections.First.GetRange().SimpleFields.First.Delete();
//Save the document
doc.Save("DeleteSimpleField.docx");
Add Complex Field
To add a complex field in a document, you can use Add method of the ComplexFieldCollection class.
The following sample code creates a ComplexField using IF and DATE fields to render a sentence in the document to notify the users whether today is a new year day or not. Here, we are rendering “not” with bold formatting when DATE field result is not equal to “1-1”. Follow the steps below to add the complex field:
Add a complex field with instruction using Add method of the ComplexFieldCollection class. For example, add a complex field with "IF" instruction.
Add a complex field to the complex field code range. For example, add a complex field with "Date" instruction to the complex field code range.
Access the field code from the field code collection using the CodeFields property of the ComplexField class.
Add a field code to the field code collection using Add method of the FieldCodeCollection class.
Section section = doc.Body.Sections.First; // create a paragraph and get its range section.GetRange().Paragraphs.Add("Complex Field Example"); var pr = section.GetRange().Paragraphs.Add().GetRange(); // add a static phrase "It's " pr.Runs.Add("It's "); // add a complex field with "IF" instruction var f = pr.ComplexFields.Add("IF "); // add a complex field with "DATE" instruction. f.GetCodeRange().ComplexFields.Add(" DATE \\@ \"M-d\" "); //Add additional instruction to the "IF" field to compare the nested //DATE field result with "1-1" and if it's not true - return "not" word. // also make the "not" word (if visible) bold. f.CodeFields.Add("<> \"1-1\" \"not \"").ParentRun.Font.Bold = true; // add a static phrase "new year's day!" pr.Runs.Add("new year's day!"); //Save the document doc.Save("AddComplexField.docx");
Modify Complex Field
To modify a complex field:
Access a complex field from the field collection using ComplexFields property of the RangeBase class.
Access a field code from the field code collection using the CodeFields property of the ComplexField class. For example, access the second field of the collection.
Modify the field code value using the Value property.
doc.Load("AddComplexField.docx"); //Modify complex field doc.Body.Sections.First.GetRange().Paragraphs[2].GetRange().ComplexFields.First.CodeFields[1].Value = "<> \"12-31\" \"not \""; doc.Body.Sections.First.GetRange().Paragraphs[2].GetRange().Runs[10].GetRange().Texts.First.Value = "year's last day"; //Save the document doc.Save("ModifyComplexField.docx");
Delete Complex Field
To delete a complex field, access a complex field from the field collection using ComplexFields property of the RangeBase class and delete it using Delete method of the ComplexField class.
doc.Load("AddComplexField.docx");
//Delete complex field
doc.Body.Sections.First.GetRange().ComplexFields.First.Delete();
doc.Save("DeleteComplexField.docx");
For more information on how to implement fields using GcWord, see GcWord sample browser.