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:
Type |
Description |
---|---|
Plain text | A plain text control is restricted to write plain text only. |
Rich text | A rich text control contains formatted text as well as other items like tables, pictures etc. |
Picture | A picture control displays a single image in the content control. |
ComboBox | A combo box can contain any arbitrary text and also displays a list of values which can be selected from a drop down. |
Drop down list | A drop-down list displays a list of items out of which only one can be selected. |
Date | A date control provides a calendar for selecting a date. |
CheckBox | A check box provides the option to represent the binary state: checked or unchecked. |
Building block gallery | A building block gallery allows to select from a list of building blocks to insert into a document. |
Group | A group control represents a protected region which users cannot edit or delete. |
Repeating Section | A repeating section control acts as a container for repeated items. |
RepeatingSectionItem |
A repeating section item specifies that the content control is a repeated item. |
BuildingBlock |
A building block is a pre-designed and pre-formatted block of text and formatting. |
Equation |
An equation specifies that the content control shall be of type equation. |
Bibliography |
A bibliography specifies that the content control shall be of type bibliography. |
Citation |
A citation specifies that the content control shall be of type citation. |
ExternalContentEntityPicker |
An external content entity picker control allows the user to select an instance of an external content type. |
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.
To create a content control:
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"); |
To create a content control using custom placeholder text:
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"); |
To modify a content control:
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"); |
To delete a content control:
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"); |
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:
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"); |
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:
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.