Working with Content Control SDT

In Microsoft Word, you can create a form by starting with a template and adding content controls, including checkboxes, text boxes, date pickers, and drop-down lists. In Aspose.Words, a Structured Document Tag or content control from any document loaded into Aspose.Words is imported as a StructuredDocumentTag node. Structured document tags (SDT or content control) allow embedding customer-defined semantics as well as its behaviour and appearance into a document. StructuredDocumentTag can occur in a document in the following places:

• Block-level - Among paragraphs and tables, as a child of a Body, HeaderFooter, Comment, Footnote or a Shape node
• Row-level - Among rows in a table, as a child of a Table node
• Cell-level - Among cells in a table row, as a child of a Row node
• Inline-level - Among inline content inside, as a child of a Paragraph
• Nested inside another StructuredDocumentTag

Inserting Content Controls into a Document

In this version of Aspose.Words, the following types of SDT or content control can be created:

• Checkbox
• DropDownList
• ComboBox
• Date
• BuildingBlockGallery
• Group
• Picture
• RichText
• PlainText

The following code example demonstrates how to create content control of type checkbox.

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

sdtCheckBox = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.CHECKBOX, aw.markup.MarkupLevel.INLINE)
builder.insert_node(sdtCheckBox)
            
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.check_box_type_content_control.docx", aw.SaveFormat.DOCX)

The following code example demonstrates how to create content control of type rich text box.

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()

sdtRichText = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.RICH_TEXT, aw.markup.MarkupLevel.BLOCK)

para = aw.Paragraph(doc)
run = aw.Run(doc)
run.text = "Hello World"
run.font.color = drawing.Color.green
para.runs.add(run)
sdtRichText.child_nodes.add(para)
doc.first_section.body.append_child(sdtRichText)

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.rich_text_box_content_control.docx")

The following code example demonstrates how to create content control of the type combo box.

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()

sdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.COMBO_BOX, aw.markup.MarkupLevel.BLOCK)
sdt.list_items.add(aw.markup.SdtListItem("Choose an item", "-1"))
sdt.list_items.add(aw.markup.SdtListItem("Item 1", "1"))
sdt.list_items.add(aw.markup.SdtListItem("Item 2", "2"))
doc.first_section.body.append_child(sdt)

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.combo_box_content_control.docx")

How to update Content Controls

This section explains how to update the values of SDT or content control programmatically. 

The following code example shows how to set the current state of the checkbox:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")
            
# Get the first content control from the document.
sdtCheckBox = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()

if (sdtCheckBox.sdt_type == aw.markup.SdtType.CHECKBOX) :
    sdtCheckBox.checked = True

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.current_state_of_check_box.docx")

The following code example shows how to modify content controls of type plain text box, drop-down list and picture:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")

for sdt in doc.get_child_nodes(aw.NodeType.STRUCTURED_DOCUMENT_TAG, True) :
    sdt = sdt.as_structured_document_tag()

    if (sdt.sdt_type == aw.markup.SdtType.PLAIN_TEXT) :
        
        sdt.remove_all_children()
        para = sdt.append_child(aw.Paragraph(doc)).as_paragraph()
        run = aw.Run(doc, "new text goes here")
        para.append_child(run)
        
    elif (sdt.sdt_type == aw.markup.SdtType.DROP_DOWN_LIST) :
        
        secondItem = sdt.list_items[2]
        sdt.list_items.selected_value = secondItem
        
    elif (sdt.sdt_type == aw.markup.SdtType.PICTURE) :
        
        shape = sdt.get_child(NodeType.shape, 0, True).as_shape()
        if (shape.has_image) :
            shape.image_data.set_image(docs_base.images_dir + "Watermark.png")
            
doc.save(docs_base.artifacts_dir + "WorkingWithSdt.modify_content_controls.docx")

You can download the sample file of these examples from Aspose.Words GitHub.

Binding Content Control to Custom XML Parts

You can bind content controls with XML data (custom XML part) in Word documents.

The following code example shows how to bind content control to custom XML parts:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
xmlPart = doc.custom_xml_parts.add(str(uuid.uuid4()), "<root><text>Hello, World!</text></root>")

sdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.BLOCK)
doc.first_section.body.append_child(sdt)

sdt.xml_mapping.set_mapping(xmlPart, "/root[1]/text[1]", "")

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.bind_sd_tto_custom_xml_part.doc")

XMLMapping of Structured Document Tag Range

You can get the mapping of this structured document tag range to XML data in a custom XML part of the current document using the StructuredDocumentTagRangeStart.xml_mapping property. However, the set_mapping method can be used to map a structured document tag range to XML data.

The following code example shows how to set XML mapping:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Multi-section structured document tags.docx")

# Construct an XML part that contains data and add it to the document's CustomXmlPart collection.
xmlPartId = str(uuid.uuid4())
xmlPartContent = "<root><text>Text element #1</text><text>Text element #2</text></root>"
xmlPart = doc.custom_xml_parts.add(xmlPartId, xmlPartContent)
print(xmlPart.data.decode("utf-8"))

# Create a StructuredDocumentTag that will display the contents of our CustomXmlPart in the document.
sdtRangeStart = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG_RANGE_START, 0, True).as_structured_document_tag_range_start()

# If we set a mapping for our StructuredDocumentTag,
# it will only display a part of the CustomXmlPart that the XPath points to.
# This XPath will point to the contents second "<text>" element of the first "<root>" element of our CustomXmlPart.
sdtRangeStart.xml_mapping.set_mapping(xmlPart, "/root[1]/text[2]", None)

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.structured_document_tag_range_start_xml_mapping.docx")

Clear Contents of a Content Control

You can clear the contents of a content control with displaying a placeholder. StructuredDocumentTag.clear method clears contents of this structured document tag and displays a placeholder if it is defined. However, It is not possible to clear the contents of a content control if it has revisions. If a content control has no placeholder, five spaces are inserted like in MS Word (except repeating sections, repeating section items, groups, check-boxes, citations). If a content control is mapped to custom XML, the referenced XML node is cleared.

The following code example shows how to clear the content of content control:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")

sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
sdt.clear()

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.clear_contents_control.doc")

Change Content Control Background and Border Colors

The StructuredDocumentTag.color property allows you to get or set the color of content control. The color affects content control in two situations:

1. MS Word highlights the background of the content control when the mouse moves over the content control. This helps to identify the content control. The color of highlighting is a bit “softer” than the color. For example, MS Word highlights the background with the pink color, when color is red.
2. When you interact (editing, picking etc) with the content control, the border of content control is colored with the color.

The following code example shows how to change the color of content control:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")

sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
sdt.color = drawing.Color.red

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.set_content_control_color.docx")

How to Set Style to Format Text Typed into the Content Control

If you want to set the style of content control, you can use StructuredDocumentTag.style or StructuredDocumentTag.style_name properties. When you type the text into content control in the output document, the typed text will have the style “Quote”.

Note that only Linked and Character styles can be applied to content control. An exception (“Cannot apply this style to the SDT”) is thrown when a style that exists but is not Linked or Character style is being applied.

The following code example shows how to set the style of content control:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document(docs_base.my_dir + "Structured document tags.docx")

sdt = doc.get_child(aw.NodeType.STRUCTURED_DOCUMENT_TAG, 0, True).as_structured_document_tag()
style = doc.styles.get_by_style_identifier(aw.StyleIdentifier.QUOTE)
sdt.style = style

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.set_content_control_style.docx")

Working with Repeating Section Content Control

The repeating section content control allows repeating the content contained within it. Using Aspose.Words, the structured document tag nodes of the repeating section and repeating section item types can be created and for this purpose, SdtType enumeration type provides REPEATING_SECTION_ITEM property.

The following code example shows how to bind a repeating section content control to a table:

# For complete examples and data files, please go to https://github.com/aspose-words/Aspose.Words-for-Python-via-.NET
doc = aw.Document()
builder = aw.DocumentBuilder(doc)

xmlPart = doc.custom_xml_parts.add("Books",
    "<books><book><title>Everyday Italian</title><author>Giada De Laurentiis</author></book>" +
    "<book><title>Harry Potter</title><author>J K. Rowling</author></book>" +
    "<book><title>Learning XML</title><author>Erik T. Ray</author></book></books>")

table = builder.start_table()

builder.insert_cell()
builder.write("Title")

builder.insert_cell()
builder.write("Author")

builder.end_row()
builder.end_table()

repeatingSectionSdt =aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.REPEATING_SECTION, aw.markup.MarkupLevel.ROW)
repeatingSectionSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book", "")
table.append_child(repeatingSectionSdt)

repeatingSectionItemSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.REPEATING_SECTION_ITEM, aw.markup.MarkupLevel.ROW)
repeatingSectionSdt.append_child(repeatingSectionItemSdt)

row = aw.tables.Row(doc)
repeatingSectionItemSdt.append_child(row)

titleSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.CELL)
titleSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book[1]/title[1]", "")
row.append_child(titleSdt)

authorSdt = aw.markup.StructuredDocumentTag(doc, aw.markup.SdtType.PLAIN_TEXT, aw.markup.MarkupLevel.CELL)
authorSdt.xml_mapping.set_mapping(xmlPart, "/books[1]/book[1]/author[1]", "")
row.append_child(authorSdt)

doc.save(docs_base.artifacts_dir + "WorkingWithSdt.creating_table_repeating_section_mapped_to_custom_xml_part.docx")