1. Integrating data and documents
Custom XML
Integrating data and documents
It has always been possible to create great-looking documents in many different ways. But this module covers aspects of Open XML that offer new creative options for developers. It has never been easier to integrate the worlds of data and documents.

2. Disclaimer
The information contained in this slide deck represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.
This slide deck is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.
Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this slide deck may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.
Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this slide deck. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this slide deck does not give you any license to these patents, trademarks, copyrights, or other intellectual property.
Unless otherwise noted, the example companies, organizations, products, domain names, addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, address, logo, person, place or event is intended or should be inferred.
© 2006 Microsoft Corporation. All rights reserved.
Microsoft, 2007 Microsoft Office System, .NET Framework 3.0, Visual Studio, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

3. Why Custom XML? Enables interoperability with other systems
Documents can provide a rich view of back-end data sources
Documents can update back-end data sources
Exposes business data in Open XML documents
Heterogenous systems can easily read data from documents
Business-specific semantics can be applied to document data
Separates presentation and data
Simplified programming model for all of the above
Custom XML schema support was a key design objective for Open XML: any schema can be used in Open XML documents.

4. Custom XML: Developer Options
Technology
WML
SML
PML
Custom XML Parts
Format-agnostic, very clean (only your tags)
May be non-visible
YES
Structured Document Tags (Content Controls)
Bound to custom XML parts or metadata
CustomXML Markup
Tag block-level content with custom schema
Also available in Word 2003
Custom XML Mapping
WordprocessingML: map content controls to custom Xml parts
SpreadsheetML: map cells to nodes in an external XML file
Smart Tags
Simple, familiar, was available in Word 2003
These are the general areas we’ll be covering in this module.

5. Custom XML Parts

6. Custom XML Parts Open XML Document
Pure custom data: only your tags appear in the part
Format-agnostic
WordprocessingML: relationship from main document
SpreadsheetML: relationship from workbook
PresentationML: relationship from presentation or slide
Explicit relationship from a shape on a slide
No content restrictions: any schema (or none)
Syntactical restriction: must contain well-formed XML
Open XML Document
Document body – Open XML
Custom XML parts – your schemas

7. Custom XML Part: Properties/Metadata
Information about a custom XML part is stored in a custom XML properties part
Stored via an implicit customXmlProps relationship from the custom XML part
Contains two types of information:
Part ID
Uniquely identifies a part within a document
Maintained through editing sessions
Office uses GUIDs, you can use any type of unique identifier
XML Schema references
Demo: databinding/2-customXml.docx
Can anything else be stored in the properties part?
See section of the spec, about extension lists stored as arbitrary custom XML without a visual representation; need a simple demo of this?
DEMO

8. Demo

9. Adding a custom XML part (using the SDK)
public void XLInsertCustomXml(string fileName, string customXML) {
using (SpreadsheetDocument xlPackage = SpreadsheetDocument.Open(fileName, true))
// Add a new custom XML part.
WorkbookPart workbookPart = xlPackage.WorkbookPart;
CustomXmlPart xmlPart = workbookPart.AddNewPart<CustomXmlPart>();
// Copy the XML into the new part...
using (Stream outputStream = xmlPart.GetStream())
using (StreamWriter ts = new StreamWriter(outputStream))
ts.Write(customXML); }
xlPackage.Save();

10. Structured Document Tags

11. Structured Document Tags
4/6/2017
Structured Document Tags
Smart tags and custom XML markup add semantics, but do not have any effect on presentation
Sometimes you want to affect presentation
Custom UI behaviors: data-entry restrictions, multi-select, etc.
The solution: the structured document tag <sdt>
How to speak to the relationship between content controls and structured document tags?
Note that SDTs may be nested to support complex semantics, as with custom Xml markup.

12. Structured Document Tags
4/6/2017
Structured Document Tags
A structured document tag has two sections:
SDT properties
SDT content

13. Structured Document Tag Properties <sdtPr>
4/6/2017
Structured Document Tag Properties <sdtPr>
Generic properties: Type, Title, ID, placholder text
Type-specific properties
Example: values for populating a dropdown list
Runtime behaviors (locking properties)
Whether region is editable
Whether region is deletable
<w:sdtPr>
<w:id w:val=" " />
<w:placeholder>
<w:docPart w:val="DefaultPlaceholder_ " />
</w:placeholder>
<w:showingPlcHdr />
<w:dataBinding w:prefixMappings="xmlns:ns0=' w:xpath="/ns0:Customer[1]/ns0:Name" w:storeItemID="myCustomXmlDataIdentifier" />
<w:text />
</w:sdtPr>

14. Other Control Types In addition to plain text: Rich Text Date Picker
Picture
Combobox
Dropdown List
Document Building Block
Demo: Dropdown.docx

15. Can’t be done in the Word UI.
Data Binding

16. Demo

17. Data Binding: Bringing It All Together
2-way synchronization between:
Content controls (data in structured document tags)
Custom XML nodes (data in your schema)
Content Controls
Custom XML part
Data Binding
Interactive data-driven documents
See DataBinding folder, readme.txt.
Note Dropdown.docx in demo folder if needed.

18. Data Binding Basics
To bind a custom Xml node to a structured document tag:
Add a <dataBinding> element to the structured document tag properties <sdtPr>
<dataBinding> specifices a custom Xml part (by Custom XML Data Identifier) and an Xpath to a specific node within that part
Custom XML Data Identifier? What’s that?
The custom XML part has a properties part
Implicit relationship in customXmlPart.xml.rels
The properties part specifies a Custom XML Data Identifier
Custom Xml Data Identifier:
Per the spec, should be a GUID
If you use a well-formed GUID then Word leaves it alone, but if you use some other identifier then Word will replace it with a GUID on next save.
You may omit the GUID altogether, if there's only one custom Xml part.
DEMO these two concepts?
DEMO

19. Demo

20. Data Binding Syntax <dataBinding> element inside <sdtPr>
Document body
StoreItemId = Custom Xml Data Identifier
<datastoreItem>
Custom Xml Properties
ItemID = Custom Xml Data identifier
Custom Xml part Relationship to custom Xml Properties
Key concepts:
The structured document tag is linked to the custom Xml properties via a hard-coded Custom Xml Data Identifier.
The custom Xml part (the data) is related to the custom Xml properties part by a relationship of type customXmlProps.
<w:dataBinding w:prefixMappings="xmlns:ns0=' w:xpath="/ns0:Customer[1]/ns0:Name" w:storeItemID="myCustomXmlDataIdentifier"/>

21. Content Control Toolkit
Open-source developer tool
Automatically generates parts, relationships, and markup to bind custom XML parts to content controls
Use to create data-bound documents with no programming
Use as a learning tool, to generate markup for use in custom solutions
This is a useful learning tool for developers, and it also addresses something that’s missing from the Office UI: a way to create databinding between content controls and custom XML parts.
Demo:
-Open the step-2 document from the previous demo (DataBinding), which has a custom XML part and a content control but no data binding
Drag an XML node to the content control, then save the document
Open the document as a ZIP, and show the databinding markup that was created
DEMO

22. Macros and custom XML
Office 2007 has strong object-model support for custom XML parts
VBA macros can be used to enable additional types of data binding beyond built-in capabilities
DEMO

23. Demo

24. Custom XML Markup

25. Custom XML Markup Basics
4/6/2017
Custom XML Markup Basics
Allows embedding the structure from any XML schema into a WordprocessingML document
Custom XML elements may have custom attributes
Open XML consumers/producers preserve your attributes
Open XML Document
Document Body (start part)
Unstructured content
Tagged content
etc …
Sections of content tagged with your custom schema

26. Where can Custom Xml Markup appear?
Custom XML markup can appear at two levels
Block level (around and/or sibling to paragraphs)
Inline (around and/or sibling to runs)
Custom XML markup may be nested
Complex multi-level data semantics may be used

27. Custom XML Markup Example
4/6/2017
Custom XML Markup Example
Note that outer tag is around a multi-paragraph section, inner tag is around a single run.
Demo: tag content with a schema (shiporders.xsd) through the Word UI, show the customXml elements that are created.
DEMO

28. Demo

29. Custom XML Markup: Why <customXml>?
4/6/2017
Custom XML Markup: Why <customXml>?
Why not just embed the custom XML directly in the WordprocessingML document?
Answer: this way, your custom schema doesn’t need to support WordprocessingML within it
This abstraction provides the flexibility to support any schema in custom XML markup

30. This section is lifted verbatim from Ecma presentations – need to decide how to cover this topic.
Brief coverage may be good – not much time for this module.
Custom XML Mapping

31. XML Mapping Overview Your custom schema / XML added to a workbook
XML elements & attributes ‘mapped’ to cells & Tables
Store a copy of the schema in the workbook
SpreadsheetML document
Open XML parts
Sheet data
Tables
Embedded schema
Mapped to cells
Mapped to table columns
Import
XML data file

32. Example Note: Table object Single cells mapped Map object name
XML structure is visualized

33. How It All Ties Together
Schema
Table1
Cell 1
SchemaId
mapId
mapId
Map Object
mapId
mapId
Table 2
Cell 2

34. Custom XML Source
A cache of the user schemas added to the workbook (xmlmaps.xml)
Nodes mapped to tables (table1.xml)
Nodes mapped to single cells (tableSingleCells1.xml)

35. xmlMaps.xml … … … … <MapInfo> holds schemas and map objects
@SelectionNamespaces ties the prefix to the actual namespace
identifies the schema collection
identifies the map object
@Name is the friendly name of the map object
@RootElement is the name of the root element of the XML instance (schemas can define more than one root node)
@SchemaID identifies which schemas the map uses
@ShowImportExportValidationErrors indicates that when an XML instance is imported or exported, the schema should be used to validate the instance, and schema errors should be shown to the user
@AutoFit indicates that after refresh, all the cells should be ‘best fitted’
@Append means that when refreshed, don’t discard existing data, but append new data to it.
@PreserveSortAFLayout indicates whether to keep filters on (Tables)
@PreserveFormat indicates whether to keep the cell formatting applied or re-apply based on schema data type
(not sure yet about how DataBindingLoadMode is used) …

36. Table1.xml
xmlColumnPr is specifically for Tables that are bound to XML
@mapId ties the table back to the map object
@xpath ties the column or cell to a specific schema element (XML instance xpath, not schema xpath)
@xmlDataType indicates the data type of the column (used for import data interpretation and cell formatting)

37. tableSingleCells.xml
<singleXmlCell> is top level object (like the Table)
<xmlCellPr> is like the table column-level properties
<xmlPr> is like the table column xml properties

38. Demo

39. Custom XML Mapping Example
Map the Schema
Open a blank Excel spreadsheet.
On the Data ribbon choose From Other Sources / From XML Data Import.
Find the XML file you just saved and double-click it.
Import your Data
Following the prompts to map to the SML schema and import the data to the worksheet.
Export the Results
Right-click the list under the XML flyout and choose Export…
Map your schema
Open a blank Excel spreadsheet and go to the Data ribbon. Choose From Other Sources / From XML Data Import. Find the XML file you just saved and double-click it. You’ll see this dialog box:
Click OK. That will open another dialog box (see below). Just click OK again. You’ll see the data created by the XML. But you want to see the XML schema. That’s easy. At this point you are looking at the following worksheet:
To add the XML viewing pane open the Customize Quick Access Toolbar menu and select More Commands. Then select All Commands from the pull-down menu. Scroll down the list until you see XML. Double-click XML then click OK. This will bring you back to the Excel worksheet.
Click the XML button on the Quick Access Toolbar.
Click Source and your XML schema tree will appear in a new pane at the right of the screen. Try clicking the various elements of the schema tree to see what happens on the worksheet.
Import your data
Now that the nodes have been mapped, tell Excel to import the data. Right click the data region of the worksheet, select XML from the pop-up menu, and pick Refresh XML data (see below). That will import any new data from your XML file.
Now that the list is mapped to the XML schema, if you have XML files that adhere to your schema you can choose to import multiple XML files at once. For instance, to import two XML files simultaneously, make a copy of the XML file you saved to the desktop, open it in notepad and make some changes. Right-click the data area again and select XML from the pop-up menu. Pick Import from the next menu and select both XML files and hit OK. Now both sets of data are imported into the list.
Export the results
Exporting data is easy. Right click the list again and this time under the XML flyout choose Export... You can choose to export to a brand new XML file, or to overwrite one of the imported files. This example shows how easy it is to bring your own XML data into Excel, work on it, and then output it back into it's original XML schema.
One common use of this functionality is when there are two schemas. The first schema is used to import a huge data set that comes from a web service or other external data source. Using the XML mapping functionality, bring that data into Excel, then run whatever models you want to on the data. The second schema is used to map the results of the model in Excel and use that to export the results as XML. This allows Excel to serve as a very powerful transformation tool with a rich user interface.

41. LAB: Custom XML