Documents for Word .NET Edition
Features / Fields
In This Topic
    Fields
    In This Topic

    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.

    Fields in a Word document

    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.

    C#
    Copy Code
    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");

    Back to Top

    Modify Simple Field

    To modify a simple field:

    1. 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.
    2. Modify the field code using Code property of the SimpleField class.
      C#
      Copy Code
      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");
    Back to Top

    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.

    C#
    Copy Code
    doc.Load("AddSimpleField.docx");
    
    //Delete a simple field
    doc.Body.Sections.First.GetRange().SimpleFields.First.Delete();
    
    //Save the document
    doc.Save("DeleteSimpleField.docx");
    Back to Top

    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:

    1. Add a complex field with instruction using Add method of the ComplexFieldCollection class. For example, add a complex field with "IF" instruction.
    2. 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.
    3. Access the field code from the field code collection using the CodeFields property of the ComplexField class.
    4. Add a field code to the field code collection using Add method of the FieldCodeCollection class.
      C#
      Copy Code
      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");
    Back to Top

    Modify Complex Field

    To modify a complex field:

    1. Access a complex field from the field collection using ComplexFields property of the RangeBase class.
    2. 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.
    3. Modify the field code value using the Value property.
      C#
      Copy Code
      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");
    Back to Top

    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.

    C#
    Copy Code
    doc.Load("AddComplexField.docx");
    
    //Delete complex field          
    doc.Body.Sections.First.GetRange().ComplexFields.First.Delete();
    
    doc.Save("DeleteComplexField.docx");
    Back to Top

    For more information on how to implement fields using GcWord, see GcWord sample browser.