Content Controls (Structured Document Tags)

Structured Document Tags (SDT) enable users to add specific semantics to part of the document: restricting input, modifying editing behavior etc.

Currently, the WordsProcessing library can import and export content controls from and to Office Open XML (DOCX) format. When exporting to other formats the content controls will be lost, however, their content (current value) will be preserved.

Content Controls Inside the Document

The content controls can be defined on Block, Inline, Row or Cell level. They can be nested inside each other as well. In addition, one can modify the editing behavior of the content controls. This means that you can lock the content of the content control, the entire content control or both.

Supported Content Controls

Bibliography
CheckBox
Citation
ComboBox
Date
DocumentPart
DocumentPartGallery
DropDownList
Equation
Group
Picture
RichText
Text
RepeatingSection
RepeatingSectionItem

The following content controls are not supported by Microsoft Word:

Bibliography
Equation

Common Content Controls Properties

The above content controls share the following properties:

Type: The type of the current content control.
ID: Each content control must have unique ID.
DataBinding: Gets or sets an XML mapping (DataBinding) that relates the content of associated SDT to a specific XML node.
Lock: This property controls if the entire content control or its contents can be edited or deleted. The possible values are:
- Unlocked: The content control can be edited and deleted.
- SdtLocked: The content control can be edited but cannot be deleted.
- ContentLocked: The content control cannot be edited, the entire content control can be deleted.
- SdtContentLocked: The content control cannot be edited or deleted.
Alias: Gets or sets the name for the associated content control (this is necessary because the properties are stored in a separate object).
Tag: Gets or sets a tag for the associated SDT.
IsTemporary: Gets or sets a value that indicates whether this SDT will be removed after editing its content.
OutlineColor: Gets or sets the color that is used for visualizing the outline.
OutlineAppearance: Represents the different options for visualizing the outline of a content control.The possible values are:
- BoundingBoxes: The content is wrapped in a bounding box that may also contain a specific editor.
- Tags: The content is wrapped in design view tag.
- None: The content does not have outline visualization.
Placeholder: Gets or set the associated placeholder object.
- ShowPlaceholder: This property enables/disables the Placeholder editing behavior.
- PlaceholderText: This property holds the Placeholder text.
RunProperties: These are the properties which will be applied to the content of the control after interacting with it.This is relevant for the content controls that generate new content after an interaction, e.g. check box, combo box, drop down list, date picker, repeating section.

Content Controls with Specific Properties

CheckBox

The CheckBox content control exposes two properties CheckedState and UnCheckedState. Both properties are of type SdtCheckBoxState which allows you to set the respective character and its font. The Checked property specifies whether the checkbox is checked.

Example 1: Setting CheckBox properties

SdtCheckBoxState checkedBoxState = new SdtCheckBoxState(); 
checkedBoxState.Font = new FontFamily("Arial"); 
checkedBoxState.CharacterCode = 0x0040; 
 
SdtCheckBoxState uncheckedBoxState = new SdtCheckBoxState(); 
uncheckedBoxState.Font = new FontFamily("Arial"); 
uncheckedBoxState.CharacterCode = 0x0024; 
 
CheckBoxProperties properties = new CheckBoxProperties(); 
properties.CheckedState = checkedBoxState; 
properties.UncheckedState = uncheckedBoxState; 
properties.Checked = true;

The toggle states can be visualized with any characters specified in the properties. The following example demonstrates a complete code snippet how to insert toggled/untoggled checkboxes:

   RadFlowDocument document = new RadFlowDocument();
   RadFlowDocumentEditor editor = new RadFlowDocumentEditor(document);

   //define the characters which will visually indicate the toggle states
   SdtCheckBoxState checkedBoxState = new SdtCheckBoxState();
   checkedBoxState.Font = new FontFamily("Arial");
   checkedBoxState.CharacterCode = 0x0040;

   SdtCheckBoxState uncheckedBoxState = new SdtCheckBoxState();
   uncheckedBoxState.Font = new FontFamily("Arial");
   uncheckedBoxState.CharacterCode = 0x0024;

   CheckBoxProperties checkBoxProperties = new CheckBoxProperties();
   checkBoxProperties.CheckedState = checkedBoxState;
   checkBoxProperties.UncheckedState = uncheckedBoxState;
   checkBoxProperties.Checked = true;

   Run checkedRun = editor.InsertText("Checked: ");
   editor.MoveToInlineEnd(checkedRun);
   SdtRangeStart sdt = editor.InsertStructuredDocumentTag(checkBoxProperties);
   editor.MoveToInlineEnd(sdt);
   Run runWithCheckBox = editor.InsertText(((char)checkBoxProperties.CheckedState.CharacterCode).ToString());
   runWithCheckBox.Properties.FontFamily.LocalValue = new ThemableFontFamily(checkBoxProperties.CheckedState.Font);
   editor.MoveToInlineEnd(sdt.End);

   Run uncheckedRun = editor.InsertText(Environment.NewLine+ "UnChecked: ");
   editor.MoveToInlineEnd(uncheckedRun);
   sdt = editor.InsertStructuredDocumentTag(checkBoxProperties);
   editor.MoveToInlineEnd(sdt);
   runWithCheckBox = editor.InsertText(((char)checkBoxProperties.UncheckedState.CharacterCode).ToString());

Insert CheckBoxes

ComboBox and DropDownList

The ComboBox and DropDownList provide the user with options to choose from. The only difference is that when using ComboBox you can add a value that is not defined in the list.

Items: This property allows you to specify the predefined items.
LastValue: This property returns the currently selected value as string.
SelectedItem: This property holds the currently selected item object.
- DisplayText: This property holds the displayed in the ComboBox/DropdownList text.
- Value: This property holds the value, which can be propagated through a data-binding relation.

Example 2: Setting ComboBox properties

ComboBoxProperties properties = new ComboBoxProperties(); 
properties.Items.Add(new ListItem() { DisplayText = "Choice 1", Value = "a" }); 
properties.Items.Add(new ListItem() { DisplayText = "Choice 2", Value = "b" }); 
properties.SelectedItem = properties.Items.Where(li => li.Value == "a").FirstOrDefault();

Date

The Date content control allows you to enter a date by using a calendar. The date content control has the following properties:

DateFormat: Allows you to get/set the format string of the date. If it is omitted the default date format for the language is used.
Language: Allows you to get/set the CultureInfo object for the date format.
FullDate: The current selected date, stored as string.
Calendar: Allows you to select the calendar type.
DateMappingType: Gets or sets the data type (e.g. Date, DateTime, and Text) that is used for storing mapped date time value.

Example 3: Setting Date properties

DateProperties properties = new DateProperties(); 
properties.DateFormat = "MM/dd/yyyy H:mm"; 
properties.Language = new CultureInfo("bg-BG"); 
properties.FullDate = DateTime.Now; 
properties.Calendar = SdtCalendar.Gregorian; 
properties.DateMappingType = DateMappingType.DateTime;

Text

The Text content control allows you to enter plain text. The text content control has the following property:

IsMultiline: Gets or sets a value that indicates whether the SDT supports new lines in its content.

Example 4: Setting Text properties

TextProperties properties = new TextProperties(); 
properties.IsMultiline = true;

RepeatingSection

SectionTitle: Gets or sets the title of the section.
AllowInsertAndDeleteSections: Gets or sets a value that indicates whether the underlying sections can be modified.

Example 5: Setting RepeatingSection properties

RepeatingSectionProperties properties = new RepeatingSectionProperties(); 
properties.SectionTitle = "Title"; 
properties.AllowInsertAndDeleteSections = true;