4.10 Document Protection

Microsoft Office Word 2003 introduces some powerful new document protection features. While these features are not specifically XML-related, they can help to make custom XML editing solutions in Word more robust. There are two kinds of document protection options: editing restrictions and formatting restrictions. Our press release template relies heavily on both kinds of restrictions.

4.10.1 Editing Restrictions

Editing restrictions let you protect a document in various ways for example, by making it read-only or by allowing comments only. You can also make exceptions to the overall document policy for particular regions of the document. Our press release template protects the entire document as read-only but designates particular areas of the document as unrestricted. These areas correspond exactly to the custom XML leaf elements embedded in the WordprocessingML template. By restricting user changes to the text within XML leaf nodes, you can ensure that users won't inadvertently alter the template's boilerplate text, or worse, delete a custom XML element.

The global policy is set using the w:documentProtection element inside the w:docPr element:

  <w:docPr>     <!-- ... -->     <w:documentProtection w:edit="read-only" w:formatting="on"                           w:enforcement="on"/>     <!-- ... -->   </w:docPr>

This element specifies that the document is read-only, that formatting restrictions are also turned on, and that all such restrictions are currently being enforced. The w:documentProtection element also takes an optional w:unprotectPassword attribute which contains a hex-encoded password key. In that case, users will not be able to remove the document protection without entering the correct password. The onload stylesheet for our press release template, pr2word.xsl, turns document protection on by generating a w:documentProtection element just like the one shown above.

Individual exceptions to a document's read-only policy are represented in the body of the WordprocessingML document using the w:permStart and w:permEnd elements. Example 4-8 shows an excerpt of our press release template's onload stylesheet, pr2word.xsl. Both the custom XML elements and the w:permStart and w:permEnd elements are highlighted.

Example 4-8. Document protection boundaries and custom XML elements

            <w:tbl>               <w:tblPr>                 <w:tblW w:w="0" w:type="auto"/>                 <w:tblInd w:w="475" w:type="dxa"/>               </w:tblPr>               <w:tblGrid>                 <w:gridCol w:w="5303"/>                 <w:gridCol w:w="4590"/>               </w:tblGrid>               <w:tr>                 <w:tc>                   <w:tcPr>                     <w:tcW w:w="5303" w:type="dxa"/>                   </w:tcPr>                   <ns1:contact>                     <w:p>                       <w:pPr>                         <w:pStyle w:val="Contact"/>                       </w:pPr>                       <w:r>                         <w:t>Contact: </w:t>                       </w:r>                       <ns1:firstName w:placeholder="[First]">                         <w:permStart w: w:edGrp="everyone"/>                         <w:r>                           <w:t>                             <xsl:value-of                            select="/ns1:pressRelease/ns1:contact/ns1:firstName"/>                           </w:t>                         </w:r>                         <w:permEnd w:/>                       </ns1:firstName>                       <w:r>                         <w:t>                           <xsl:text> </xsl:text>                         </w:t>                       </w:r>                       <ns1:lastName w:placeholder="[Last]">                         <w:permStart w: w:edGrp="everyone"/>                         <w:r>                           <w:t>                             <xsl:value-of                             select="/ns1:pressRelease/ns1:contact/ns1:lastName"/>                           </w:t>                         </w:r>                         <w:permEnd w:/>                       </ns1:lastName>                       <w:r>                         <w:t>                           <xsl:text> </xsl:text>                         </w:t>                       </w:r>                     </w:p>                     <w:p>                       <w:pPr>                         <w:pStyle w:val="Contact"/>                       </w:pPr>                       <w:r>                         <w:t>Phone: </w:t>                       </w:r>                       <ns1:phone w:placeholder="[xxx-xxx-xxxx]">                         <w:permStart w: w:edGrp="everyone"/>                         <w:r>                           <w:t>                             <xsl:value-of                                select="/ns1:pressRelease/ns1:contact/ns1:phone"/>                           </w:t>                         </w:r>                         <w:permEnd w:/>                       </ns1:phone>                     </w:p>                   </ns1:contact>                 </w:tc>                 <w:tc>                   <w:tcPr>                     <w:tcW w:w="4590" w:type="dxa"/>                   </w:tcPr>                   <w:p>                     <w:pPr>                       <w:pStyle w:val="Date"/>                     </w:pPr>                     <w:r>                       <w:t>FOR IMMEDIATE RELEASE</w:t>                     </w:r>                   </w:p>                   <w:p>                     <w:pPr>                       <w:pStyle w:val="Date"/>                     </w:pPr>                     <ns1:date w:placeholder="[YYYY-MM-DD]">                       <w:permStart w: w:edGrp="everyone"/>                       <w:r>                         <w:t>                           <xsl:value-of select="/ns1:pressRelease/ns1:date"/>                         </w:t>                       </w:r>                       <w:permEnd w:/>                     </ns1:date>                   </w:p>                 </w:tc>               </w:tr>             </w:tbl>

The w:edGrp attribute of each w:permStart element indicates that "everyone" is allowed to edit the given region. (The value of "everyone" means that there are no restrictions. Other values may be groups defined on the local machine or network.) The w:id attributes on the w:permStart and w:permEnd elements maintain the association between the start and end elements of each range. The editable regions are carefully placed directly inside the custom XML elements, so that users may edit the contents of the XML tags but may not move or delete the XML elements themselves.

The excerpt in Example 4-8 also illustrates how data is pulled from the source document into the merged XML and WordprocessingML editing view through the use of an xsl:value-of instruction inside each custom XML leaf element.

4.10.2 Formatting Restrictions

Formatting restrictions enable you to restrict formatting to a selection of zero or more styles. This also means that users will not be able to apply direct formatting, such as italic or bold. Unlike editing restrictions, you cannot designate different regions of the document to have different formatting restrictions. The restricted selection of styles is a global setting for the entire document.

Formatting restrictions are enabled when the w:formatting and w:enforcement attributes of the w:documentProtection element both have the value on (as shown above), and when the w:defLockedState attribute of the w:latentStyles element (inside the top-level w:styles element) also has the value on:

    <w:latentStyles w:defLockedState="on" w:latentStyleCount="156"/>

Individual styles defined within the document are either locked or available, depending on the presence of the w:locked element in the style's w:style definition. If w:locked is present (and not explicitly off), it means that the style is locked and cannot be used. If not, then the style is among the limited selection of styles that the user can apply. Note that the document may already contain paragraphs or runs that use locked styles. That is okay; users just won't be able to create new runs or paragraphs that use those styles. (Note that the w:defLockedState attribute sets the "default locked state" only for the built-in styles; it does not affect styles defined within the document, whose locked state is determined solely based on the presence of the w:locked element.)

In our press release template, there are three styles available for the user to apply: a paragraph style called "Body Text," a character style called "Lead-in Emphasis," and a character style called "No formatting." All of these are used for the body text of the press release. The "Lead-in Emphasis" style is used normally only for the first phrase of the first paragraph, as a traditional all-caps lead-in to the content of the press release. The "No formatting" style is based on the built-in "Default Paragraph Font" style and does not include any additional formatting. Its purpose is to let the user conveniently turn off the "Lead-in Emphasis" style after they are done typing the lead-in text.

You may be wondering, "Why use styles at all when the WordprocessingML markup is just going to get stripped out when the document is saved?" The answer is that our press release template uses an onsave XSLT stylesheet to convert a run having the "Lead-in Emphasis" style to an actual leadIn element in the saved XML document. Similarly, the onload XSLT stylesheet converts a leadIn element in a newly opened press release XML document to a run having the "Lead-in Emphasis" style. By defining these mappings, our imaginary IT department is able to support a limited form of mixed content editing without having to invoke Smart Document programming.