Another thing to note about the pink tags displayed in Word’s “Data only” view is that they can be made invisible. Although the XML Structure task pane (which we’ll introduce later) includes a checkbox for turning “Show XML Tags” on and off, there is also a quick keystroke command that will do the trick. Ctrl-Shift-X toggles this option on and off. For example, if you hit Ctrl-Shift-X after opening the document we saw in Figure 4-11, then the tags will disappear, leaving the view shown in Figure 4-12.

Figure 4-12. The “Data only” view with “Show XML tags” turned off

The only difference between Figure 4-11 and Figure 4-12 is that the “Show XML tags” option is turned off in Figure 4-12; otherwise, all of the document formatting is identical.

Word’s generic “Data only” view and our press-release-specific “Elegant” view both contain custom XML tags. The primary visible difference between them is that “Show XML tags” is turned on in the “Data only” view but turned off in the “Elegant” view. If a particular document does not dictate whether the option should be turned on or off, then Word defaults to the last setting chosen within the Word application. For this reason, both stylesheets explicitly specify the intended setting, using the w:showXMLTags literal result element inside the w:docPr element. Here is the relevant excerpt from XML2WORD.XSL, Word’s default “Data only” stylesheet:

            <!-- set Word document properties for raw XML - save as raw XML and
show XML tags in the document -->
            <w:docPr>
                <w:view w:val="web" />
                <w:removeWordSchemaOnSave w:val="on" />
                <w:showXMLTags w:val="on" />
            </w:docPr>

As you can see, the w:showXMLTags option has the explicit value of on. In contrast, the “Elegant” stylesheet for press releases, pr2word.xsl, explicitly turns this document option off:

      <w:docPr>
        <!-- ... -->
        <w:showXMLTags w:val="off"/>
      </w:docPr>

Just to prove that the custom XML elements really are present in the “Elegant” press release view, Figure 4-13 shows what the view would look like if a user turned “Show XML tags” on, for example, by pressing Ctrl-Shift-X.

Figure 4-13. The “Elegant” press release view after turning “Show XML tags” on

In the merged representation of custom XML and WordprocessingML that we saw in Example 4-3, there were only block-level custom tags, i.e., custom XML elements that occurred as siblings and parents of w:p (or w:tbl) elements. As it happens, custom XML elements may also occur at other places within the WordprocessingML document hierarchy. They may occur as “inline,” or run-level, elements (siblings and parents of w:r elements), row-level elements (siblings and parents of w:tr elements), and cell-level elements (siblings and parents of w:tc elements). In each case, they behave slightly differently. In this section, we’ll examine block-level and run-level custom tags. See “Table Rows and Repeating Elements” later for a discussion of row-level and cell-level custom tags.

Run-level custom tags are necessary to support multiple elements within the same paragraph. Whenever mixed content is needed, run-level tags are necessary. Word renders run-level tags slightly differently than their block-level, row-level, and cell-level counterparts. Instead of labeling both the start and end tags, Word labels only the start tag and colors both the start and end tags solid pink. Figure 4-14 shows a close up of Word’s block-level and run-level tags in an excerpt from our original press release template (with “Show XML tags” turned on).

Figure 4-14. Block-level versus run-level tags

The contact element is a block-level tag. It contains two paragraphs and itself is contained within a table cell, which, like the main document body, is a legal block-level context. The firstName, lastName, phone, and date elements are all run-level tags.

Example 4-4 shows the WordprocessingML that corresponds to the visual excerpt in Figure 4-14. We’ve left out some details for now (particularly having to do with styles and editing restrictions) so that it would be easy to follow the basic structure. All of the custom tags within this excerpt are highlighted.

        <w:tbl>
          <!-- ... -->
          <w:tr>
            <w:tc>
              <w:tcPr><!-- ... --></w:tcPr>
              <ns0:contact>
                <w:p>
                  <w:r>
                    <w:t>Contact: </w:t>
                  </w:r>
                  <ns0:firstName w:placeholder="[First]">
                    <w:r>
                      <w:t/>
                    </w:r>
                  </ns0:firstName>
                  <w:r>
                    <w:t> </w:t>
                  </w:r>
                  <ns0:lastName w:placeholder="[Last]"/>
                    <w:r>
                      <w:t/>
                    </w:r>
                  </ns0:lastName>
                </w:p>
                <w:p>
                  <w:r>
                    <w:t>Phone: </w:t>
                  </w:r>
                  <ns0:phone w:placeholder="[xxx-xxx-xxxx]"/>
                    <w:r>
                      <w:t/>
                    </w:r>
                  </ns0:phone>
                </w:p>
              </ns0:contact>
            </w:tc>
            <w:tc>
              <w:tcPr><!-- ... --></w:tcPr>
              <w:p>
                <w:r>
                  <w:t>FOR IMMEDIATE RELEASE</w:t>
                </w:r>
              </w:p>
              <w:p>
                <ns0:date w:placeholder="[YYYY-MM-DD]"/>
                  <w:r>
                    <w:t/>
                  </w:r>
                </ns0:date>
              </w:p>
            </w:tc>
          </w:tr>
        </w:tbl>

Once again, the namespace prefix (ns0) is an automatically generated prefix mapped to the namespace URI for our press release schema. The ns0:contact element is a block-level element, in that it is a parent of w:p elements and could have w:p (or w:tbl) element siblings. The ns0:firstName, ns0:lastName, ns0:phone, and ns0:date elements are all run-level elements, in that they are contained in run-level contexts—as children of w:p elements and as siblings of w:r elements. They themselves also contain w:r elements. Although all of these elements occur inside a table, none of them happen to occur as row-level or cell-level elements.

Another thing that Example 4-4 shows is how placeholders for custom XML elements are represented in WordprocessingML. The placeholder text is a property of the element instance itself, represented by the w:placeholder attribute. Placeholder text is only visible on an element field when the “Show XML tags” option is turned off, when the element is a leaf node (i.e., it contains no other custom XML tags), and when the element is currently empty of any text content. Figure 4-15 shows what the placeholder text looks like for this excerpt, after turning “Show XML tags” back off.

Figure 4-15. Placeholder text

Placeholder text can be applied to any custom XML tag, whether block-level, run-level, row-level, or cell-level.

Without the help of Smart Documents, end users normally won’t be able to create or delete custom XML elements (let alone attributes) in a reliable and user-friendly way. Instead, they are limited to filling out static templates of fixed XML elements. For the most part, this scenario is what our press release example illustrates. However, you can enable end users to edit a repeating list of XML elements without invoking Smart Document technology by exploiting a special property of row-level custom XML tags.

Here’s how it works. Given a table row that has a row-level custom tag applied to it, the user can create new rows in the table, complete with custom tags, simply by hitting the Tab key. This is easiest to explain by example. Consider the WordprocessingML document in Example 4-5. It contains a table with one row and two cells, each of which are contained within custom XML elements. Appropriately named, the myRow element is a row-level tag, and the myCell1 and myCell2 elements are cell-level tags.

<?xml version="1.0"?>
<?mso-application progid="Word.Document"?>
<w:wordDocument xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml">
   
  <w:body>
    <myRoot>
      <w:p/>
      <w:tbl>
        <myRow>
          <w:tr>
            <myCell1>
              <w:tc>
                <w:tcPr>
                  <w:tcW w:w="4000" w:type="dxa"/>
                </w:tcPr>
                <w:p/>
              </w:tc>
            </myCell1>
                  <myCell2>
              <w:tc>
                <w:tcPr>
                  <w:tcW w:w="4000" w:type="dxa"/>
                </w:tcPr>
                <w:p/>
              </w:tc>
            </myCell2>
          </w:tr>
        </myRow>
      </w:tbl>
      <w:p/>
    </myRoot>
  </w:body>
   
</w:wordDocument>

Figure 4-16 shows that the user can easily create new rows in this document just by hitting the Tab key at the end of each row. Each new row is contained within a myRow element, and each row contains myCell1 and myCell2 elements. The final product you deliver to end users, of course, will have “Show XML tags” turned off, and will probably include some meaningful labels, etc.

Figure 4-16. Using table rows to create repeating elements

This behavior also holds true for cell-level custom tags regardless of whether they are contained in a custom row-level tag. For example, if we removed the myRow tags from Example 4-5, the myCell1 and myCell2 elements would still repeat when the user inserts a new row into the table. Even block-level custom tags inside table cells exhibit this behavior—provided that the initial block-level custom tag contains the entire content of the table cell, i.e., it has no sibling w:p or w:tbl elements. Run-level tags in table cells never behave this way; they are never automatically replicated on table row insertion.

When a new row is created, the newly created XML element automatically adopts the same placeholder text that the original had. However, custom XML attributes (which, as we’ll see, are represented as literal attributes on custom XML elements) are not replicated.

You can leverage the unique behavior of custom tags and table rows to allow end users to create new instances of a repeating element type declared in your schema. Unfortunately, apart from the visible schema violation flags, the definitions in your schema have no effect on the behavior of the table. If a custom XML tag is wired to a table row or cell in one of the ways described above, then Word will replicate that tag on row insertion, regardless of how the element is declared in the schema.