DsWord 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.

DsWord 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:

DsWord 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.

   C#

   Copy Code

   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");

Back to Top

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.

   C#

   Copy Code

   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.

   C#	Copy Code
   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.

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

DsWord 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. DsWord 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.

   C#

   Copy Code

   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

DsWord 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.

   C#

   Copy Code

   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 DsWord, see DsWord sample browser.