GcWord provides different types of content controls that help in organizing the content of a document in a structured manner. They are often used for creating templates and forms. They provide the flexibility to position the content and deny or allow editing of controls.

For example, consider a scenario of a company event. Thousands of invite forms need to be generated which will have the company address by default. Since the same address needs to be replicated over all the invite forms, this can be done by using Repeating Section content control. Also, in case the company address needs to be changed, the value of address field will be updated only in the Repeating Section control and it will automatically reflect in all the invite forms.

GcWord library supports content controls which are represented by the ContentControl class. In fact, there are various types of content controls which are represented by the enum ContentControlType and are explained below:

GcWord allows you to add, modify, and delete content controls from a Word document. A content control can be created using the Add or Insert method of the ContentControlCollection class. It can be modified using the ContentControl class properties, and deleted using Delete method of the ContentControl class.

Create Content Control

To create a content control:

1. Create a new Word document by instantiating the GcWordDocument class.

2. Add a paragraph using Add method of the ParagraphCollection class.

3. Create a content control of type plain text using the Add method of ContentControlCollection class.

4. Configure the content control by setting its properties.

5. Add text to the content control using Add method of the ParagraphCollection class.

   GcWordDocument doc = new GcWordDocument();
   
   doc.Body.Sections.First.GetRange().Paragraphs.Add("This sample demonstrates creation/insertion of content controls in a Word document");
   Style paraStyle = doc.Styles.Add("paraStyle", StyleType.Paragraph);
   paraStyle.Font.Bold = true;
   paraStyle.Font.Size = 12;
   
   doc.Body.Sections.First.GetRange().Paragraphs.Add("Employee Name: ", paraStyle);
   
   //Create a content control of type plain text and add static text to it         
   ContentControl cc_plainText = doc.Body.ContentControls.Add(ContentControlType.Text,false);
   cc_plainText.Appearance = ContentControlAppearance.BoundingBox;
   cc_plainText.LockContents = false;
   cc_plainText.LockControl = true;           
   cc_plainText.Content.GetRange().Paragraphs.Add("Robert King");
   
   doc.Save("ContentControls.docx");

To create a content control using custom placeholder text:

1. Create a new Word document by instantiating the GcWordDocument class.

2. Add a content control of type plain text using the Add method of ContentControlCollection class.

3. Create a building block that defines the custom placeholder text using the Add method of BuildingBlockCollection class.

4. Add the custom placeholder text to the building block by adding a paragraph to it.

5. Assign the value of the custom placeholder text to the content control's placeholder text by setting the PlaceHolderText property of the content control.

   GcWordDocument doc = new GcWordDocument();
   
   doc.Body.Sections.First.GetRange().Paragraphs.Add("Job Title: ", paraStyle);
   
   //Create a content control of type rich text with custom placeholder
   ContentControl cc_custom = doc.Body.ContentControls.Add(ContentControlType.Text);          
   BuildingBlock placeholder = doc.GlossaryDocument.BuildingBlocks.Add("placeholder", "General", BuildingBlockGallery.Placeholder, BuildingBlockInsertOptions.Content, BuildingBlockType.ContentControlPlaceholder);
   Paragraph p = placeholder.Body.Paragraphs.Add("Enter your job title:");
   p.GetRange().Runs.First.Style = p.ParentBody.Document.Styles[BuiltInStyleId.PlaceholderText];        
   cc_custom.PlaceholderText = placeholder; // attach the custom placeholder to the content control           
   
   doc.Save("ContentControls.docx");

Modify Content Control

To modify a content control:

1. Load the document using Load method of GcWordDocument class.

2. Access the content control which needs to be modified using ContentControls property of RangeBase class.

3. Clear the existing text in the content control using the Clear method of RangeBase class.

4. Add new text to the content control using the Add method of the ParagraphCollection class.

   GcWordDocument doc = new GcWordDocument();
   doc.Load("ContentControls.docx");
   
   //Retrieves the content control and modifies its content
   ContentControl contentControl = doc.Body.ContentControls[0];
   contentControl.Content.GetRange().Clear();
   contentControl.Content.GetRange().Paragraphs.Add("Andrew Fuller");
   
   doc.Save("ContentControl_Modified.docx");

Delete Content Control

To delete a content control:

1. Load the document using Load method of GcWordDocument class.

2. Access the content control which needs to be deleted using the ContentControls property of RangeBase class.

3. Delete the content control using Delete method of the ContentControl class.

   GcWordDocument doc = new GcWordDocument();
   doc.Load("ContentControls.docx");
   
   //Retrieves the first content control and deletes it
   ContentControl contentControl = doc.Body.ContentControls.First;
   contentControl.Delete();
   
   doc.Save("ContentControl_Deleted.docx");

Bind Content Controls to Custom XML parts

GcWord supports binding content controls to XML data using custom XML parts. Custom xml parts are used to embed XML data in documents for some Microsoft Office applications. Any change that is made to the text in a content control is saved to the custom XML part and vice versa. GcWord allows you to bind content controls to elements in a custom XML part using the XmlMapping class.

To bind the content control to custom XML parts:

1. Create and load an XML document using Load method of XmlDocument class.

2. Use Add method of CustomXmlPartCollection to embed the XML data to the word document.

3. Create a content control of type plain text which will be bound to the custom XML part.

4. Bind the content control to an element in the custom XML part using the SetMapping method of XmlMapping class.

   GcWordDocument doc = new GcWordDocument();
   
   doc.Body.Sections.First.GetRange().Paragraphs.Add("This sample demonstrates the binding of content controls to custom XML parts ");
   Style paraStyle = doc.Styles.Add("paraStyle", StyleType.Paragraph);
   paraStyle.Font.Bold = true;
   paraStyle.Font.Size = 12;
   
   //Create an XML document
   XmlDocument xmlDoc = new XmlDocument();
   xmlDoc.Load("Employees.xml");
   
   //Add the XML document to the custom XML part
   
   string xmlPartId = Guid.NewGuid().ToString();
   doc.CustomXmlParts.Add(xmlDoc, xmlPartId);
   
   doc.Body.Sections.First.GetRange().Paragraphs.Add("Employee Name: ", paraStyle);
   
   //Create a content control of type plain text          
   ContentControl plainTextContentControl = doc.Body.ContentControls.Insert(ContentControlType.Text, InsertLocation.End);
   //bind the content control to element in the custom XML part using XPath expression
   plainTextContentControl.XmlMapping.SetMapping("/employees/employee[1]/name[1]", null, xmlPartId);
   
   doc.Save("XMLMapping.docx");

Bind Content Controls to Built-in Properties

GcWord allows you to bind content controls to built-in document properties (like Application name, Title, Last saved time, Version, Author, Category etc). The SetMapping method of XmlMapping class takes the property name as a parameter to establish the binding.

To bind the content control to built-in properties:

1. Create a new Word document by instantiating the GcWordDocument class.

2. Set the value of a built-in property 'Author' using the BuiltinProperties property of the BuiltInPropertyCollection class.

3. Create a content control of type plain text which will be bound to the built-in property.

4. Map the content control to built-in property using the SetMapping method of XmlMapping class.

   GcWordDocument doc = new GcWordDocument();
   
   doc.Body.Sections.First.GetRange().Paragraphs.Add("Document Author: ", paraStyle);
   
   doc.Settings.BuiltinProperties.Author = "James Smith"; // set a built-in property value
   
   // Add a new content control of type plain text for the built-in property
   ContentControl cc_builtInProp = doc.Body.ContentControls.Insert(ContentControlType.Text,InsertLocation.End);
   /*map the built-in property value with the content control. Now when a user 
     changes the content control value the built-in property will be changed automatically*/
   string author = cc_builtInProp.XmlMapping.SetMapping(() => doc.Settings.BuiltinProperties.Author);
   
   doc.Save("XMLMapping.docx");

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