Programmability for XML data store for documents

A programmability mode for interacting with data stores within a document allows real time interaction. Data for structuring information associated with a document, such as document metadata, is maintained in the data store where relationships between different pieces of data are maintained in a location distinct from the surface level view of a document. The data store exposes interfaces to the various pieces of data in the data store for allowing different applications to access and operate on one or more of the data pieces. The pieces of data may be structured according to a markup language such as the Extensible Markup Language (XML), and XML schemas may be associated with each piece of data for allowing the data store to validate the structure applied to the data based on an XML schema associated with a given piece of data.

BACKGROUND

Computer users have grown accustomed to user-friendly software applications that help them write, calculate, organize, prepare presentations, send and receive electronic mail, make music, and the like. For example, word processing applications allow users to prepare a variety of useful documents. Spreadsheet applications allow users to enter, manipulate, and organize data. Slide presentation applications allow users to create a variety of slide presentations containing text, pictures, data or other useful objects.

Documents created by such applications (e.g. word processing documents, spreadsheets, slide presentation documents), however, have limited facility for storing/transporting the contents of arbitrary metadata required by the context of the documents. For example, a solution built on top of a word processing document may require the storage of workflow data that describes various states of the document, for example, previous workflow approval states (dates, times, names), current approval states, future workflow states before completion, name and office address of document author, document changes, and the like. The options for storing this information are primarily limited to the use of document variables or existing custom object linking and embedding (OLE) document properties that have limitations. For example, no hierarchical data may be stored; character length is limited, and the like. The properties for such methods are stored in a single store, for example, an OLE properties store, which means the properties have a possibility of conflicting. Further, such stored properties have no data validation. It is difficult for users of such applications and related documents, to store arbitrary data with documents, which is a common need of many users.

SUMMARY

One or more data stores are maintained separately from a primary presentation storage within a document for storing, relating and for allowing use of arbitrary data that is associated with a computer-generated document. Data for structuring information associated with a document, such as document metadata, is maintained in a data store where relationships between different pieces of data are maintained. The data store exposes application programming interfaces (APIs) to the various pieces of data in the data store for allowing different applications to access and operate on one or more of the data pieces.

The pieces of data may be structured according to a markup language such as the Extensible Markup Language (XML). XML schemas may be associated with each piece of data, and the data store may validate the XML structure applied to the data based on an XML schema associated with a given piece of data. Programmatic access is provided to the data in its XML form while the document is being edited. Multiple client applications may access and edit the same piece of document data, and any conflicting changes to a given piece of data are resolved. Standard XML schemas (XSDs) may also be used to define the contents of any of the pieces of custom XML data associated with document metadata in order to ensure that XML data applied to the document data are valid.

DETAILED DESCRIPTION

Referring now to the drawings, in which like numerals represent like elements, various aspects of the present invention will be described. In particular,FIG. 1and the corresponding discussion are intended to provide a brief, general description of a suitable computing environment in which embodiments of the invention may be implemented.

Generally, program modules include routines, programs, components, data structures, and other types of structures that perform particular tasks or implement particular abstract data types. Other computer system configurations may also be used, including hand-held devices, multiprocessor systems, microprocessor-based or programmable consumer electronics, minicomputers, mainframe computers, and the like. Distributed computing environments may also be used where tasks are performed by remote processing devices that are linked through a communications network. In a distributed computing environment, program modules may be located in both local and remote memory storage devices.

With reference toFIG. 1, one exemplary system for implementing the invention includes a computing device, such as computing device100. In a very basic configuration, computing device100typically includes at least one processing unit102and system memory104. Depending on the exact configuration and type of computing device, system memory104may be volatile (such as RAM), non-volatile (such as ROM, flash memory, etc.) or some combination of the two. System memory104typically includes an operating system105, one or more applications106, and may include program data107. In one embodiment, application106may include a word processor application120. This basic configuration is illustrated inFIG. 1by those components within dashed line108.

A number of program modules and data files may be stored in the system memory104of the computing device100, including an operating system105suitable for controlling the operation of a networked personal computer, such as the WINDOWS operating systems from MICROSOFT Corporation of Redmond, Wash. System memory104may also store one or more program modules, such as word processor application120, and others described below. Word processor application120is operative to provide functionality for creating, editing, and processing electronic documents.

According to one embodiment of the invention, the word processor application120comprises the WORD program from MICROSOFT Corporation. It should be appreciated, however, that word processor application programs from other manufacturers may be utilized. The illustration of a word processing application is for purposes of example only and is not limiting of other types of applications that may produce and operate on documents. For example, other application programs106which are capable of processing various forms of content (e.g. text, images, pictures, etc.), such as spreadsheet application programs, database application programs, slide presentation application programs, drawing or computer-aided application programs, etc. are equally applicable. An example application program106that produces and operates on a variety of different types of documents includes OFFICE from MICROSOFT Corporation.

Throughout the specification and claims, the following terms take the meanings associated herein, unless the context of the term dictates otherwise.

The term “data” may refer to document surface level or presentation level information such as words, sentences, paragraphs and the like, as well as, supplementary information, for example, metadata, which is carried with, referred to, or used by the word processing document. This information is often large and is likely not exposed on the presentation layer of the document.

The term “presentation” refers to the visible portion of the document such as the text and layout that would appear if the document were printed.

The term “tag” refers to characters inserted in a document that delineates elements within an XML document. Each element generally includes two tags: the start tag and the end tag. It is possible to have an empty element (with no content) in which case one tag is allowed.

The terms “markup language” or “ML” refer to a language for special codes within a document that specify how parts of the document are to be interpreted by an application. In a word processor file, the markup language specifies how the text is to be formatted or laid out.

The term “element” refers to the basic unit of an XML document. The element may contain attributes, other elements, text, and other content regions for an XML document.

The term “building block” refers to a bounded and potentially labeled region in a document which serves as a container for a specific type of content entered by the user.

The term “data binding, data mapping, and data field” refer to a property on a building block which determines an XPath to the XML DOMs stored in the document where the contents of the building block should be stored.

The XML content between the tags is considered the element's “children” (or descendants). Hence other elements embedded in the element's content are called “child elements” or “child nodes” or the element. Text embedded directly in the content of the element is considered the element's “child text nodes”. Together, the child elements and the text within an element constitute that element's “content”.

The term “attribute” refers to an additional property set to a particular value and associated with the element. Elements may have an arbitrary number of attribute settings associated with them, including none. Attributes are used to associate additional information with an element that will not contain additional elements, or be treated as a text node.

“XPath” is an operator that uses a pattern expression to identify nodes in an XML document. An XPath pattern is a slash-separated list of child element names that describe a path through the XML document. The pattern “selects” elements that match the path.

The term “XML data store or data store” refers to a container within a document, such as a word processor document, a spreadsheet document, a slide presentation document, etc., which provides access for storage and modification of the data (in XML format, for example) stored in the document while the file is open. Further definition of XML data store is provided below with respect toFIG. 2.

FIG. 2is a block diagram illustrating a relationship between one or more client applications and one or more data stores and the contents of the data store(s). Generally described, one or more data stores are maintained separately from a primary presentation storage within a document for storing, relating and for allowing use of arbitrary data that is associated with a computer-generated document. Data for structuring information associated with a document, such as document metadata, is maintained in a data store where relationships between different pieces of data are maintained. The data store exposes application programming interfaces (APIs) to the various pieces of data in the data store for allowing different applications to access and operate on one or more of the data pieces. As used herein, the terms “data consumers,” “applications” and “processes” may be used interchangeably unless the context clearly dictates otherwise.

The pieces of data may be structured according to a markup language such as the Extensible Markup Language (XML). XML schemas may be associated with each piece of data, and the data store may validate the XML structure applied to the data based on an XML schema associated with a given piece of data. The data stores may contain any number of arbitrary data items, for example metadata, structured according to the Extensible Markup Language (XML). Accordingly, document solution providers may store arbitrary metadata as XML with a given document and have that information processed by a given solution having access to the data upon the occurrence of an event such as when data is removed or loaded to the data store and/or when the document is opened/edited/saved by a user.

Programmatic access may also be provided to the data in its XML form while the document is being edited. According to one embodiment, a standard mechanism is provided that is familiar to solution developers via which the data may be accessed and modified programmatically while the document is open. This programmatic access mimics standard XML interfaces. Programmatic access to the data is provided via application programming interfaces to one or more editing client applications (for example, document editing or creating applications and/or third party application add-in solutions, and the like). Accordingly, multiple client applications may access and edit the same piece of document data, and any conflicting changes to a given piece of data are resolved. “Side effects” to any given change may be made (for example, in response to setting a company name to “Microsoft,” changing a stock symbol to “MSFT”). In addition, changes to data and any associated side effects may be “bundled” by the data store so that undoing one or more changes reverses all related changes. This assists in removing the burden of development from the solution itself to ensure that it has reversed all changes when the user initiates an undo of the original change from the document surface, for example, by pressing an Undo command.

Standard XML schemas (XSDs) may also be used to define the contents of any of the pieces of custom XML data associated with document metadata in order to ensure that XML data applied to the document data are valid. These schemas may be attached to any instance of XML data stored in the document, and the data store will disallow any change to the XML data that would result in the XML structure (that is, the XML tags as opposed to their contents) of that data from becoming invalid. This helps to ensure that the solution developer can attach a specific piece of XML metadata to a document and ensure that the XML data will continue to be structurally “correct” according to the associated schema, regardless of which data consumers (for example, add-ins) are used to modify that data.

Referring now toFIG. 2, the document data220includes XML structure data and associated document data representing the surface or presentation level view of a document. For example the document data220may include XML structure (e.g., heading tags, body tags, conclusion tags) and associated surface view data (e.g., words, sentences, paragraphs) of a word processing document, spreadsheet document, slide presentation document, and the like.

The data store208is a document data repository for storing one or more pieces of structured data associated with one or more types of data associated with a given document. Although only one data store is illustrated, more than one data store may be utilized. The metadata1225(structured data item) may include XML structure data and associated data for a first piece of metadata associated with the document. For example, the metadata1225may include XML structure data (e.g., date tags, name tags, etc.) listing the document author, date of document creation, date of document last change/save, and the like. The metadata2230(structured data item) may include XML structure data (tags) and associated metadata representing a second piece of metadata associated with the document. As should be understood, the metadata1and metadata2are for purposes of example and are not limiting of the variety and number of different types of data that may be maintained in the data store208in association with a given document. For example, as described herein, arbitrary data may be structured and added to the document by one or more software applications as desired by solution providers or users having access to the document data.

A schema file240,245may be optionally attached to each piece of data stored in the data store208for dictating the syntax and validation rules associated with Extensible Markup Language (XML) data applied to each piece of data225,230. XML schema files provide a way to describe and validate data in an XML environment. A schema file states what XML markup data, including elements and attributes, are used to describe content in an XML document, and the schema file defines XML markup syntax, including where each element is allowed, what types of content are allowed within an element and which elements can appear within other elements. The use of schema files ensures that the document (or individual piece of data in this case) is structured in a consistent and predictable manner. Schema files240,245may be created by a user and generally supported by an associated markup language, such as XML.

This schematization of the document allows the data store to provide the ability to “guarantee” the structural validity of the document by rejecting any change that violates a given schema file at the data store level. According to an embodiment, the data store208utilizes a schema validation module260for validating XML structure added to or changes made to a given piece of data against an associated schema file. For example, if a document creator or editor makes XML structural changes to a given piece of data, for example, the metadata1, wherein the editor adds or removes a given XML tag, the data store208will utilize the schema validation module to check the XML structural changes against the associated schema file to ensure the validity of the change. If the change is not valid, an error can be generated to the editor. As is understood, such control of the XML structure applied to a given piece of data allows for structural consistency and predictability which is especially important for allowing client and third party applications to interact with associated data.

The data store208provides one or more application programming interfaces (API)270which can be accessed by client applications205(e.g., word processing applications, spreadsheet applications, slide presentation applications, etc.), as well as, third party applications210,215via the object models (OM) of the respective applications205,210,215. These APIs allow client applications and third party applications to load any existing XML file into a given document's data store208, thus ensuring that that data is now part of the document and will travel within that document for its lifetime (e.g., through opening/editing/saving/renaming/etc.) or until the data is deleted from the data store. According to one embodiment, the data in the data store is available in its XML format even when a source application for a given piece of data225,230is closed or is otherwise not available. That is, a given piece of data225,230may be accessed via the APIs270by other applications (other than a source application). As described below, the APIs also allow client and third party applications to make changes to the XML markup data applied to the data items225,230.

Once XML data225,230is loaded into the data store for association with a document220, it can be manipulated as standard XML using the data store interfaces designed to provide similar methods to existing XML editing interfaces in order to leverage developers' existing knowledge of the XML programming standard. This allows users to perform standard XML operations on XML data added to the data store for a document, such as adding elements and attributes, removing elements and attributes, changing the value of existing elements/attributes, and reading the values of any existing part of the associated XML tree. Using these XML standard operations, solutions may store structured complex metadata with a document subject to none of the previous restrictions on the length/size of the data or structure of the data, which enables the use of this XML data store for significantly more structured solutions than prior solutions. For example, a third party application215may be written for locating and extracting document author names and document creation dates from a number of documents by reading the metadata1225added to the data store208for each document. The example third party application may be an application programmed for making a list of document author names and document creation dates for all documents created by a given organization. In accordance with embodiments of the present invention, the third party application may utilize the XML structure applied to the metadata1for efficiently locating and extracting the desired data. For example, the third party application may be written to parse the XML structure of the metadata1file to locate XML tags, such as <docauthor> and <doccreationdate> for obtaining and using data associated with those tags. As should be appreciated, the forgoing is just one example of the many ways one or more applications may interact with structured data that is associated with the document via the data store208.

In addition, the data store208provides any number of API interfaces270to any individual piece of XML data220,225,230(also known as a store item) to enable multiple applications205,210,215to work with the same piece of data. For example, several solutions, such as a client application (e.g., word processing application) and third party application solutions (e.g., the application described above), may work with the same set of document properties (e.g., properties contained in the metadata2230file). Using the data store208, each of these applications receives separate access to the desired XML data230through their own data store API interface270for allowing each application to communicate with the data via its own OM without having to deal with the complexity of having multiple data consumers accessing the same piece of data.

In order to allow for these multiple data consuming applications205,210,215to access the same data, the data store208notifies each of these applications when any part of the XML data is changed by another application so that a given application may respond to that change (both internally to its own process and externally by other changes to the same data). When one application requests a change to a given data item, that request is automatically sent to all other applications to allow other applications to decide how or if to respond to the requested change. According to one embodiment, this is accomplished by allowing each application to register to “listen” to any part of the XML data to which it has an interface so that a given application solution/program only receives those messages which are pertinent to its own logic. For example, one type of application210may wish to register to listen to all changes made to a given XML data in order to provide detailed business logic capabilities to a third party solution, but another type of application215may wish to only listen to changes to one or two specific XML elements within the same data because its logic does not care about changes to any other part of the XML data.

According to this embodiment, the multiple applications205,210,215may access and edit the same piece of document data, and any conflicting changes to a given piece of data are resolved. For example, “side effects” to any given change may be made when one change by one application causes a side effect change by another application. For example, a first application210may be tasked with extracting company names from one or more data items225,230associated with a given document for translating those names into corresponding stock symbols, if available, for compiling a list of company stock symbols related to a given document. If a second application215causes a given company name in a given piece of metadata to be added or to be changed, for example, changing a company name from “Company ABC” to “Company XYZ,” the first application may listen to this change for automatically updating its list of stock symbols to include the stock symbol for “Company XYZ” instead of “Company ABC.” In addition, such changes and any associated side effects may be bundled by the data store208so that undoing one or more changes reverses all related changes.

FIG. 3illustrates a system diagram showing the interaction between the internal and external data consumers with the XML data stores. As illustrated, system300includes a data store302including a presentation layer304, XML stores 1-N (306) that each includes an error store and an undo store, a global change store308, an optional global undo store310, an internal broker312that is coupled to internal data consumers 1-N314and an external broker316that is coupled to external data consumers 1-N318.

Using the XML Data Store(s)306, documents have the ability to contain any number of arbitrary data items (as long as each conforms to standard XML syntax). Arbitrary metadata may be stored as XML within a document and that information may be automatically round-tripped when the document is opened/edited/saved by the user.

As discussed above, programmatic access to this data is provided via an API that may be utilized while the document is being edited, providing a standard mechanism familiar to solution developers via which this information can be accessed and modified programmatically while the document is open. According to one embodiment, this programmatic access is designed to mimic standard XML interfaces. Using the API, data can be added/removed while the application, such as a word processing application, is running; data can be populated within a store item (a part within the data store); data can be manipulated using standard XML constructs; schemas can be associated with any arbitrary XML data in the data store; schemas can be added/removed/changed once associated with the data store item; and XML changes can be evented to any listening clients. As illustrated, the API comprises an external broker316that provides an interface for the external data consumers318and an internal broker312that provides an interface for any internal data consumers314that interact with the data store302.

Manipulations to data store302may occur in real time. As discussed above, the data stores306may contain one or more types of data. For example, a company might have one data store that they're using to store all the different types of data they want to store within a single data store, while another company might want to store data different types of data across different data stores.

A data consumers318may register for events that relate to actions concerning the data stores306. For example, a data consumer may register to receive an event when any type of change is made to one or more data stores. Another data consumer may register for changes that have happened to a certain element or set of elements within a data store. Common events include, loading a data store, adding to a data store and deleting from a data store. When the event occurs, each data consumer that has registered may react to the change while the state of the data stores is maintained consistently. Many times, a data consumer will not perform any actions when a change is made. At other times, the data consumer will perform some action(s) in response to the event. For example, a data consumer may make some other changes to the data store in response to the change such as, in response to a title change, updating headers within the document. The data consumer may also perform some other operations that do not affect the document. For example, if stock ticker symbol is inserted, the data consumer may retrieve data that is associated with that stock symbol even though all of the retrieved data may not be displayed within the document at the presentation layer. The data consumer may also reject the change. For example, if data consumer 1 receives a change they do not accept, that data consumer may return a flag to the broker indicating that the change is not accepted. Whenever a change is not accepted, the change is rolled back, along with any side effects, such that the change never occurred. Each XML store306may utilize its undo store to undo the changes it has made. Alternatively, the global undo store310may be utilized to undo the changes made across the data stores. Imagine there are three data consumers that are interested in what's happening to document properties, so each of these data consumers have registered to receive an event relating to a change of the properties. When a change is made, the data store determines each data consumer that has registered and informs each of them of the change in a predetermined order. Each data consumer, in turn, may perform some action in response to the change. If the change, or any of the changes made by the registered data consumers as a result of the change, are not accepted by any one of the data consumers, all of the changes relating to the initial change are undone.

The external broker application programming interface layer316provides access to the data store302by the external data consumers318and allows third-party clients to interact with the data store302just as the internal data consumers that are associated with the application interact with the data store. Each of the XML data stores306within the data store302are provided with a unique ID for identification purposes. This helps in locating the XML data stores306.

At any point a data consumer may add a schema that is used to validate the data within a data store. So now any other third-party code that comes along and tries to change the data, the first thing that the data store will do is determine whether the change makes sense with the provided schema. Once a schema is attached, the broker becomes a validating object.

The data stores may also receive more than one element at a time. Providing the data (XML) as one particular stream may help satisfy the schema in some situations. For example, suppose that an attached schema says that if stock data exists it must have at least two companies. If the stock data were added one by one it would not be valid.

A single pass is used to validate the data. Instead of making two passes which can result in a change being made to the data store, the validation is performed before the data is committed to the data store. This helps to prevent a data consumer from introducing errors into the data store.

FIGS. 4 and 5illustrate a process for handling events relating to a data store. When reading the discussion of the routines presented herein, it should be appreciated that the logical operations of various embodiments are implemented (1) as a sequence of computer implemented acts or program modules running on a computing system and/or (2) as interconnected machine logic circuits or circuit modules within the computing system. The implementation is a matter of choice dependent on the performance requirements of the computing system implementing the invention. Accordingly, the logical operations illustrated and making up the embodiments of the described herein are referred to variously as operations, structural devices, acts or modules. These operations, structural devices, acts and modules may be implemented in software, in firmware, in special purpose digital logic, and any combination thereof.

FIG. 4illustrates a process for handling events that are associated with a data store. Generally, when the data store receives a change request from a data consumer, that change is sent to all of the registered data consumers to allow them to reject the change, or to request side-effects (other XML changes) as a result of the change.

After a start operation, the process flows to operation410, where a data consumer registers for any event(s) that it is interested in receiving. The events may relate to adding data to the data store, removing data from the data store, making a change to data in the data store, and the like. The event may be attached to global changes or specific changes to elements that are stored within one or more of the data stores. For example, one data consumer may want to know when any change is made, whereas another client may only be interested in a change to one specific value within the data store.

Moving to decision operation420, a determination is made as to whether an event has occurred. The event relates to a change to the data store. For example, as discussed above, the event may include adding, removing, or making some other change to the data store. For example, the change may be to add a node to the data store. When an event has not occurred, the process returns to decision operation420. When an event has occurred, the process flows to operation430.

At operation430, the change is relayed to each of the data consumers that have registered for the change. According to one embodiment, each data consumer is notified in a predetermined order. For example, the order may be based on the order of registration of the data consumers.

Transitioning to operation440, a response is obtained from each of the data consumers that have received the event notification. Each of the clients may accept or reject the change. The responses determine whether or not the change will be committed to the data store.

Moving to decision operation450, a determination is made as to whether any of the data consumers rejected the change to the data store. When the change has been rejected by any of the data consumers, the process moves to block460, where any changes that were made in response to the change are rolled back as if no change had ever taken place.

When all of the notified clients accept the change, the process flows to operation470where the change is optionally validated and then the process flows to operation480where the change is committed to the appropriate data store.

The original data consumer that initiated the change then receives notification that the change has been accepted (operation490). The process then moves to an end block and returns to processing other actions.

FIG. 5illustrates a process for handling an event that includes side effects. Generally, when the data store receives a change request from a data consumer, that change is sent to all of the registered clients to allow them to reject the change, or to request side-effects (other XML changes) as a result of the change. For example, a client may be informed of a change to one item within the data store and as a result of the change, the data consumer makes another change to the data store. When a change is requested as a side-effect, then the process is slightly different from the process illustrated inFIG. 4.

After a start operation, the process flows to operation510, where a client initiates a side-effect change to the data store as a result of the change that is currently being accepted or rejected.

Transitioning to operation520, this side-effect change is queued but not executed. In other words, the side-effect change does not immediately execute within the data store. Based on this fact, alternatives for the events include:

Force node operations (e.g. add, replace)Makes result of nodeto return a void rather than a node andoperations consistentdocument that it's a request, not an actionNo performance hitClear story for the factthat if you want tomanipulate a node, youdo so in it's AfterAddeventReflect the fact that caller is ‘requesting’ aMakes result of nodechange instead of making oneoperations consistentNo performance hitPerform the necessary changes for eachReturn a live node tocaller, then undo them when the callerthe callerreturnsReturn a disconnected (read: not yetReturn a node from acommitted node) when changes are madechange in all casesin an eventMaintain a separate DOM for the OMReturn a live node toclientthe caller

Moving to decision operation530, a determination is made as to whether any of the data consumers rejected the original change to the data store.

When the change has been rejected by any of the data consumers, the process moves to block540, where any changes that were made in response to the change and any side-effect changes that are queued are rolled back as if no change had ever taken place.

When the clients have accepted the original change, the process flows to operation550, where the change is optionally validated and then the process flows to operation560where the original change is committed to the appropriate data store.

The process then moves to operation570, where the side-effect changes are executed one at a time within the data store. Each side-effect change may then be accepted or rejected by any of the registered clients. When any of the side effect changes are rejected all of the changes that were made are rolled back as if none of the changes were ever made.

The process then moves to an end block and returns to processing other actions.

The following are example code segments that illustrate some of the common functionality exposed via the data store OM:

The first example illustrates adding a stream to the data store:

Dim oStream As CustomXMLPart

The second example illustrates locating a data store.

Dim oStream As CustomXMLPart

The third example illustrates adding a subtree to a data store.

According to one embodiment, the following are exemplary functions that are associated with the API.Events on CustomXMLNodeEvents may occur on CustomXMLNode as well as just the document level.

Parameters: NewNode: A CustomXMLNode object corresponding to the node just added to the CustomXMLNode. Note: This node may have children (if a subtree was just added to the document). InUndoRedo: A Boolean returning TRUE if the node was added as part of an Undo/Redo action by the user, FALSE otherwise.

This event fires whenever XML nodes are about to be added to the current document. If the add operation involves a subtree of an XML document being added into the CustomXMLNode, this event is fired once for the topmost node in the change. This event fires once for each change messaged to the data store, so side effects of the change represented by this event also trigger the event.

Parameters: OldNode: A CustomXMLNode object corresponding to the node which was just removed from the CustomXMLPart. Note #1: This node may have children (if a subtree is being removed from the document). Note #2: This node will be a ‘disconnected’ node in that a query may be made down from the node, but cannot go up—it appears to exist alone (i.e. it's a document element w/ the same OwnerStream). OldParentNode: A CustonXMLNode object corresponding to the former parent node of OldNode. OldNextSibling: A CustomXMLNode object corresponding to the former next sibling of OldNode. InUndoRedo: A Boolean returning TRUE if the node was added as part of an Undo/Redo action by the user, FALSE otherwise.

This event fires whenever XML nodes are deleted from the current item in the data store. If the delete operation involves a subtree of the XML document in the CustomXMLPart, fire this event once for the topmost node in the change. This event fires once for each change messaged to the data store, so side effects of the change represented by this event also trigger the event.

Parameters: OldNode: A CustomXMLNode object corresponding to the node which was just removed from the CustomXMLPart. Note #1: This node may have children (if a subtree is being removed from the document). Note #2: This node will be a ‘disconnected’ node in that a query may be made down from the node, but does not go up—it appears to exist alone (i.e. it's a document element w/ the same OwnerStream). NewNode: A CustomXMLNode object corresponding to the node just added to the CustomXMLPart. Note: This node may have children (if a subtree was just added to the document). InUndoRedo: A Boolean returning TRUE if the node was added as part of an Undo/Redo action by the user, FALSE otherwise.

This event fires whenever XML nodes are replaced in the data store. If the replace operation involves a subtree of the XML document in the CustomXMLPart, fire this event once for the topmost node in the change. This event fires once for each change messaged to the data store, so side effects of the change represented by this event also trigger the event.

CustomXMLParts( ): Points to the collection of all the data store items available in the file including the OLE document properties and WSS properties streams.

CustomXMLPrefixMappings: Object representing all of the prefix mappings for the current part.

AddNamespace(Prefix As String, NamespaceURI As String) As Void

Parameters: Prefix: A String representing the prefix to add to the prefix mapping list. NamespaceURI: A String representing the namespace to assign to the newly added prefix.

Count As Long: Returns the number of prefix mappings in the collection.

Parameters: Index: A Long representing the index of the desired schema in the collection.

Returns the requested CustomXMLPrefixMapping from the collection. Default member of this object.

LookupNamespace(Prefix As String) As String

Parameters: Prefix: A String representing a prefix in the prefix mapping list. Allows the developer to get the namespace corresponding to the specified prefix. If a namespace is not assigned to the requested prefix, returns “ ”.

LookupPrefix(NamespaceURI As String) As String

Parameters: NamespaceURI: A String representing a namespace in the prefix mapping list.

Allows the developer to get a prefix corresponding to the specified namespace. If a prefix is not assigned to the requested namespace, returns “ ”. If there are multiple prefixes specified in the namespace manager return the first one that matches the supplied namespace.

CustomXMLPrefixMapping: Object representing a prefix mapping.

Prefix As String: Returns the prefix for this prefix mapping.

NamespaceURI As String: Returns the namespace for this prefix mapping.

CustomXMLSchema: Object representing a schema which is part of a schema collection.

Delete As Void: Deletes this schema from the schema collection. If this is done to a schema in a collection which is already validated or attached to a stream (a live collection of sorts), then fail with an error message: “This schema cannot be deleted, as the schema collection is currently in use.”

Location As String: Returns a string which represents the location of this schema on the user's machine.

NamespaceURI As String: Returns the target namespace of this schema, “ ” if none is specified by the XSD.

Reload As Void: Reloads this schema from disk, which translates to re-touching the copy of this schema on disk to: update its location (if the SL has changed) and ensure it's still a valid schema. If this is done to a schema in a collection which is already validated or tied to a stream (a live collection of sorts), then fail with an error message: “This schema cannot be reloaded, as the schema collection is currently in use.”

CustomXMLSchemaCollection( ): Object representing a collection of schemas (which are/will be attached to a stream).

Parameters: NamespaceURI: A String representing the namespace of the schema to be added to the collection. If the schema exists in the Schema Library, retrieve it out of there. Alias: A String representing the alias of the schema to be added to the collection. If the alias exists in the SL, find it using this argument. FileName: A String representing the location on disk where the schema can be found. If this parameter is specified, not only add the schema to the collection, add it to the SL. InstallForAllUsers: A Boolean representing whether, in the case where adding the schema to the Schema Library, the SL keys should be written to HKLM (for all users) or HKCU (for just the current user). Defaults to False (writing to HKCU).

This method allows the developer to add one or more schemas to a schema collection to be added to a stream in the data store, as well as to the Schema Library. It can be invoked with the following sets of parameters (in case of conflict, attempt to use the parameters in the following order): [NamespaceURI],[Alias],FileName,[InstallForAllUsers] (adds a schema to the schema library if one doesn't exist for that namespace). Just the NamespaceURI (looks up the XSD from the schema library). Just the Alias (looks up the XSD from the schema library).

AddCollection(SchemaCollection As CustomXMLSchemas( )) As Void

Parameters: SchemaCollection: A CustomXMLSchemas( ) object representing a collection of schemas to be imported into the current collection.

Adds an already existing collection to the current collection. If namespaces collide during the import (for example, if a.xsd is already linked to “fooNamespace” but the incoming collection has b.xsd for the same namespace), the incoming collection wins.

Count As Long: Returns the number of schemas in the collection.

Parameters: Index: A Variant indicating the desired item in the collection. It can be either of: a String representing the target namespace of the desired schema; or a Long representing the index of the desired schema in the collection.

Returns the requested CustomXMLSchema from the collection. Default member of this object.

NamespaceURI(Index as Long) As String

Parameters: Index: A Long representing the index of the schema in the collection.

Returns the target namespace of the specified member of the schema collection.

Validate As Boolean: Returns a Boolean representing whether the schemas in the collection validated or not. Also this is when the Includes are traversed for each schema in the collection and add them to the schemas which requested them.

CustomXMLParts( ): Collection representing a set of CustomXMLPart objects.

Parameters: XML: An optional String representing the XML to add to the newly created CustomXMLPart. SchemaCollection: An optional CustomDataSchemaCollection( ) object representing the set of schemas to be used to validate this stream.

Allows the user to add a new CustomXMLPart to the file. If the XML in the XML parameter is not well-formed, fail and throw an error: “To add content to this stream, it must be valid, well-formed XML.” If the user provides a SchemaCollection: Validate it (if it hasn't already been validated). Throw any MSXML parsing errors received back to the OM client and fail to add the stream. Check if the XML parameter can be loaded into a DOM. If not, fail and throw an error: “To add content to a stream, it must be valid, well-formed XML.” Attach the schema collection to the DOM and try to validate the instance document. If it doesn't validate, fail and throw the XML parsing error received back at the OM client and do not add a stream to the collection.

If the user does NOT provide a SchemaCollection: Check if the XML parameter can be loaded into a DOM. If not, fail and throw an error: “To add content to a stream, it must be valid, well-formed XML.” Look at the list of namespaces referenced in the XML file. Find those schemas from the SL and infer a schema collection for them. Try to validate the resulting schema collection. If it doesn't validate, still add the stream to the collection, but it is not associated with any schema collection and is hence not validated. Attach the schema collection to the DOM and try to validate the instance document. If it doesn't validate, fail and throw the XML parsing error received back at the OM client and do not add a stream to the collection. If it doesn't validate, still add the stream to the collection, but it is not associated with any schema collection and is hence not validated. Providing an empty SchemaCollection will be an explicit action that is taken to mean “never validate this stream.”

Count As Long: Returns the number of custom data streams in the collection.

Parameters: Index: A Variant, which can be one of the following two types: a Long representing the index of the desired CustomXMLPart in the collection; or a String representing the root namespace of the desired CustomXMLPart in the collection. If more than one part matches this root namespace, the first match in index order will be returned.

This is the default member of the CustomXMLParts object, and it returns a CustomXMLPart object corresponding to the requested object.

Parameters: ID: A String containing the ID for the data store item which should be returned from the collection.

Allows the developer to grab a specific item from the data store using its ID. If a store item with this ID does not exist, returns Nothing.

Parameters: NamespaceURI: A String representing the root namespace of the desired items from the data store's collection.

Returns all of the data store items whose root namespace matches the requested entry. If no streams with this root namespace exist, returns an empty CustomXMLParts( ) collection.

Parameters: NewStream: A CustomXMLPart object contained the stream that was just added.

This event fires whenever a new stream is added to the data store. If multiple streams are added, the event fires once for each new stream. If the stream was added with XML content (using the appropriate .Add method), then this event should not fire until the item is populated with that content.

Parameters: OldStream: A CustomXMLPart object contained the stream that is about to be deleted from the data store.

This event fires whenever a stream is removed from the data store. If multiple streams are removed, the event fires once for each stream that was deleted. Also flag this stream as ‘about to be deleted’ such that read-only operations on it are valid (e.g. querying for nodes, checking values, etc.) but write operations fail with an error message: “This operation cannot be performed on a stream that is about to be deleted.”

CustomXMLPart: Object representing a single XML stream in the data store.

AddNode([Name As String], [NamespaceURI As String], Parent As CustomXMLNode, [NextSibling As CustomXMLNode],[NodeType As msoCustomXMLNodeType],[NodeValue As String]) As Void

Parameters: Name: A String that represents the base name of the node to be added to the XML DOM. Namespace: An optional String that represents the namespace of the node to be added to the XML DOM. Required to add nodes of type msoCustomXMLNodeElement or msoCustomXMLNodeAttribute, ignored otherwise. Parent: A CustomXMLNode representing the node under which this node should be added. If adding an attribute, denotes the element that the attribute should be added to. NextSibling:An optional CustomXMLNode representing the node which should become the next sibling of the new node. If not specified, the node is added to the end of the parent node's children. Ignored for additions of type msoXMLNodeAttribute. If NextSibling is not a child of parent, return an error: “This node cannot be added because the next sibling node is not a child of the parent node.” NodeType: An optional msoCustomXMLNodeType that specifies the type of node to create. If not specified, then assumed to be msoCustomXMLNodeElement. NodeValue: An optional String which is used to set the value of the node for nodes which allow text. If the node doesn't allow text, the parameter is ignored.

A generic method for adding an XML node to a data store item. Parent is required and NodeType defaults to msoXMLNodeElement. If the resulting addition would be structurally invalid, fail with an error message: “This operation cannot be performed because it would result in a structurally invalid data stream.” If the namespace is not in the schema references collection, fail and provide error message: “To add this element, you must first attach its schema to the data stream.”

Gets the root element of the stream. If the stream is empty, returns Nothing.

Delete As Void: Deletes the current CustomXMLPart from the data store. If the user attempts to delete the core properties part, fails with: “This custom XML part is required for Office to function properly and cannot be deleted.”

ID As String: Returns a string containing the GUID assigned to the current CustomXMLPart.

Load(FilePath As String) As Boolean

Parameters: FilePath: A String object corresponding to the file on the user's machine (or network, etc.) from which the XML for this CustomXMLPart should be loaded.

Allows the template author to populate a CustomXMLPart from a previously existing file on their machine. Returns TRUE if the load was successful, FALSE if not (which includes the case where structure enforcement is turned on and the XML is structurally invalid or the case where the XML was not valid and/or well-formed). Once the DOM is loaded, fails with “This DOM cannot be loaded twice.”

LoadXML(XML As String) As Boolean

Parameters: XML: A String object corresponding to the XML with which this CustomXMLPart should be loaded.

Allows the template author to populate a CustomXMLPart from a string of XML. Returns TRUE if the load was successful, FALSE if not (which includes the case where structural enforcement is turned on and the XML is structurally invalid or the case where the XML is not valid and/or well-formed). Once the DOM is loaded, fails with “This DOM cannot be loaded twice.”

NamespaceURI As String: Returns a string containing the full namespace URI for the root node of the current CustomXMLPart. If the stream is empty (created but no nodes added), returns “ ”.

SchemaCollection As CustomXMLSchemaCollection( ): Gets/sets a CustomXMLSchemaCollection( ) collection representing the set of schemas attached to this stream. If the user provides a SchemaCollection: validate it (if it hasn't already been validated). Throw any parsing errors received back to the client and fail to add the stream; and attach the schema collection to the DOM and try to validate the instance document. If it doesn't validate, fail and throw the parsing error received back at the client and do not change the schema collection on the stream.

Gets the set of namespace prefix mappings used against the current CustomXMLPart. When the document is opened, this is automatically populated with the contents of the prefix mappings embedded in the data store item, but it can be edited/added to/deleted from by the template author. According to one embodiment, changes to this parameter are not saved with the document, however.

Parameters: XPath: A String containing the XPath expression to evaluate against the DOM. The prefix mappings for this XPath are retrieved from the associated namespace manager. If the XPath doesn't resolve, pass through whatever error was generated.

This method allows the developer to get back a set of nodes from within the DOM.

Parameters: XPath: A String containing the XPath expression to evaluate against the DOM. The prefix mappings for this XPath are retrieved from the associated namespace manager. If the XPath doesn't resolve, pass through whatever error was generated.

This method allows the developer to get back a single node from within the DOM.

XML As String: Returns the XML representation of the current CustomXMLPart.

Parameters: NewNode: A CustomXMLNode object corresponding to the node just added to the CustomXMLPart. Note: This node may have children (if a subtree was just added to the document). InUndoRedo: A Boolean returning TRUE if the node was added as part of an Undo/Redo action by the user, FALSE otherwise.

This event fires whenever XML nodes are about to be added to the current document. If the add operation involves a subtree of XML document being added into the CustomXMLPart, fire this event once for the topmost node in the change. This event fires once for each change messaged to the data store, so side effects of the change represented by this event also trigger the event.

Parameters: OldNode: A CustomXMLNode object corresponding to the node which was just removed from the CustomXMLPart. Note #1: This node may have children (if a subtree is being removed from the document). Note #2: This node will be a ‘disconnected’ node in that a query can be made down from the node, but does not go up—it appears to exist alone (i.e. it's a document element w/the same OwnerStream). OldParentNode: A CustomXMLNode object corresponding to the former parent node of OldNode. OldNextSibling: A CustomXMLNode object corresponding to the former next sibling of OldNode. InUndoRedo: A Boolean returning TRUE if the node was added as part of an Undo/Redo action by the user, FALSE otherwise.

This event fires whenever XML nodes are deleted from the current item in the data store. If the delete operation involves a subtree of the XML document in the CustomXMLPart, fire this event once for the topmost node in the change. This event fires once for each change messaged to the data store, so side effects of the change represented by this event also trigger the event.

Parameters: OldNode: A CustomaXMLNode object corresponding to the node which was just removed from the CustomXMLPart. Note #1: This node may have children (if a subtree is being removed from the document). Note #2: This node will be a ‘disconnected’ node in that a query can be made down from the node, but cannot go up—it appears to exist alone (i.e. it's a document element w/the same OwnerStream). NewNode: A CustomXMLNode object corresponding to the node just added to the CustomXMLPart. Note: This node may have children (if a subtree was just added to the document). InUndoRedo: A Boolean returning TRUE if the node was added as part of an Undo/Redo action by the user, FALSE otherwise.

This event fires whenever XML nodes are replaced in the data store. If the replace operation involves a subtree of the XML document in the CustomXMLPart, this event is fired once for the topmost node in the change. This event fires once for each change messaged to the data store, so side effects of the change represented by this event also trigger the event.

CustomXMLNodes( ): A collection representing a set of CustomXMLNode objects in the current document.

Count As Long: Returns the number of CustomXMLNodes in the collection.

Parameters: Index: A Long representing the index of the desired CustomXMLNode in the collection.

This is the default member of the CustomXMLNodes object, and it returns an CustomXMLNode object corresponding to the requested item in the collection.

Parameters: Name: An optional String that represents the base name of the element to be added to the XML DOM. Namespace: An optional String that represents the namespace of the element to be added to the XML DOM. Required to add nodes of type msoCustomXMLNodeElement or msoCustomXMLNodeAttribute, ignored otherwise. NodeType: An optional msoCustomXMLNodeType that specifies the type of node to create. If not specified, assumed to be msoCustomXMLNodeElement. NodeValue: An optional String which is used to set the value of the node for nodes which allow text. If the node doesn't allow text, the parameter is ignored.

Allows the developer to add a single node as the last child under the context element in the tree, if the context node is of type msoXMLNodeElement. If it is not, then the method fails with an error: “You cannot append children to comments, processing instructions, or attributes.” Also block any case where the node that would be added is an attribute that already exists: “An attribute of the same name already exists on the current element.”

AppendChildSubtree(XML As String) As Void

Parameters: XML: A String representing the subtree to add to the XML DOM. This XML must be a well-formed XML document (incl. namespace declarations, single root node, etc.). If it is not, fail with an error: “To add an XML subtree to your document, it must contain valid, well-formed XML.”

Allows the developer to add an existing well-formed XML subtree as the last child under the context element in the DOM, if the context node is of type msoXMLNodeElement. If it is not, then the method fails with an error: “You cannot append children to comments, processing instructions, or attributes.”

Attributes As CustomXMLNodes( ): Returns a CustomXMLNodes collection representing the attributes on the current element.

BaseName As String: This is the default member of CustomXMLNode. It returns the base name of the node without the namespace prefix, if one exists in the DOM.

ChildNodes As CustomXMLNodes: Returns a CustomXMLNodes collection which contains all of the elements which are children of the current node.

Delete As Void: Deletes the current node from the XML DOM (including all of its children, if any). If the resulting deletion would be structurally invalid, fail with an error message: “This operation cannot be performed because it would result in a structurally invalid DOM.”

FirstChild As CustomXMLNode: Returns a CustomXMLNode object corresponding to the first child element of the current node. If the node has no element children (or if it isn't of type msoCustomXMLNodeElement itself), returns Nothing.

HasChildNodes As Boolean: Returns a Boolean that is True if the current node has child element nodes, False otherwise. This will return false when CustomXMLNode isn't of NodeType msoCustomXMLNodeElement.

Parameters: Name: A String that represents the base name of the element to be added to the XML DOM. Namespace: An optional String that represents the namespace of the element to be added to the XML DOM. Required to add nodes of type msoCustomXMLNodeElement or msoCustomXMLNodeAttribute, ignored otherwise. NodeType: An optional msoCustomXMLNodeType that specifies the type of node to create. If not specified, assumed to be msoCustomXMLNodeElement. NodeValue: An optional String which is used to set the value of the node for nodes which allow text. If the node doesn't allow text, the parameter is ignored. NextSibling: An optional CustomXMLNode object that specifies the node before which the new XML element should be added to the tree.

Inserts a new child node into the tree at the specified location. If BeforeNode is not present when adding a node of type msoCustomXMLNodeElement, msoCustomXMLNodeComment, or msoCustomXMLNodeProcessingInstruction, the node is added to the end of the list. If added for type msoCustomXMLNodeAttribute, it is ignored. If NextSibling is not a child of the context node, then the method fails with: “This XML node cannot be added because the next sibling element must be a child of the context element.” If the resulting addition would be structurally invalid (and schema enforcement is turned on) fail with an error message: “This operation cannot be performed because it would result in a structurally invalid DOM.” Also block any case where the node that would be added is an attribute that already exists: “An attribute of the same name already exists on the current element.”

InsertSubtreeBefore(XML As String, [NextSibling as CustomXMLNode]) As Void

Parameters: XML: A String representing the subtree to add to the XML DOM. This XML must be a well-formed XML document (incl. namespace declarations, single root node, etc.). If it is not, fail with an error: “To add an XML subtree to your document, it must contain valid, well-formed XML.” NextSibling: An optional CustomXMLNode object that specifies the node before which the new XML element should be added to the tree.

Inserts the specified XML subtree into the child nodeset at the specified location. If NextSibling is not a child of the context node, then the method fails with: “This XML node cannot be added because the next sibling must be a child of the context element.” If the resulting addition would be structurally invalid, fail with an error message: “This operation cannot be performed because it would result in a structurally invalid DOM.”

LastChild As CustomXMLNode: Returns a CustomXMLNode object corresponding to the last child element of the current node. If the node has no child elements (or if it isn't of type msoCustomXMLNodeElement itself), returns Nothing.

NamespaceURI As String [read-only]

Returns a String corresponding to the namespace of the current node. If the node is of type msoCustomXMLNodeComment msoCustomXMLNodeProcessingInstruction, returns “ ”.

NextSibling As CustomXMLNode: Returns the next sibling node (element, comment, or processing instruction) of the current node. If the node is the last sibling at its level, returns Nothing.

NodeType As msoCustomXMLNodeType: Returns a msoCustomXMLNodeType constant representing the type of the current node.

NodeValue As String: Gets/sets the text inside of nodes contain just text (i.e. text nodes, comments, processing instructions, attributes). For elements, fails with: “You cannot set the NodeValue parameter for element nodes.”

OwnerDocument As Variant: Returns the Document/Workbook/Presentation object representing the Word document associated with this node.

OwnerStream As CustomXMLPart: Returns the CustomXMLPart object representing the data store item associated with this node.

PreviousSibling As CustomXMLNode: Returns the previous sibling node (element, comment, or processing instruction) of the current node. If the node is the first sibling at its level, returns Nothing.

ParentNode As CustomXMLNode: Returns the parent element node of the current node. If the node is at the root level, returns Nothing.

RemoveChild(Child As CustomXMLNode) As Void

Parameters: Child: A CustomXMLNode object that represents the child node of the context node to be deleted. If this node is not a child of the context node, fail with the error message: “This node cannot be removed because it is not a child of the current element.”

Removes the specified child node from the stream. If the resulting DOM would be structurally invalid, fail with an error message: “This operation cannot be performed because it would result in a structurally invalid DOM.”

Parameters: OldNode: A CustomXMLNode representing the child node to be replaced. Name: A String that represents the base name of the element to be added to the XML DOM. Namespace: An optional String that represents the namespace of the element to be added to the XML DOM. Required to add nodes of type msoCustomXMLNodeElement or msoCustomXMLNodeAttribute, ignored otherwise. NodeType: An optional msoCustomXMLNodeType that specifies the type of node to create. If not specified, assumed to be msoCustomXMLNodeElement. NodeValue: An optional String which is used to set the value of the node for nodes which allow text. If the node doesn't allow text, the parameter is ignored.

Removes the specified child node (and its subtree) from the stream, and replaces it with the node specified in the same location. If the OldNode is not a child of the context node, fail with an error message: “OldNode must be a child of the current node.” If the resulting replacement would be structurally invalid, fail with an error message: “This operation cannot be performed because it would result in a structurally invalid DOM.” Also block any case where the node that would be added is an attribute that already exists: “An attribute of the same name already exists on the current element.”

ReplaceChildSubtree(XML As String, OldNode As CustomXMLNode) As Void

Parameters: OldNode: A CustomXMLNode representing the child node to be replaced. XML: A String representing the subtree to add to the XML DOM. This XML must be a well-formed XML document (incl. namespace declarations, single root node, etc.). If it is not, fail with an error: “To add an XML subtree to your document, it must contain valid, well-formed XML.”

Removes the specified node (and its subtree) from the stream, and replaces it in the same location with the XML subtree specified. If the OldNode is not a child of the context node, fail with an error message: “OldNode must be a child of the current node.” If the resulting replacement would be structurally invalid, fail with an error message: “This operation cannot be performed because it would result in a structurally invalid DOM.”

Parameters: XPath: A String containing the XPath expression to evaluate against the DOM. The prefix mappings for this XPath are retrieved from the NamespaceManager property. If the XPath doesn't resolve, pass through whatever error there was (a la this method on the Document object today with embedded XML).

This method allows the developer to get back a set of nodes from within the data store item.

Parameters: XPath: A String containing the XPath expression to evaluate against the DOM. The prefix mappings for this XPath are retrieved from the NamespaceManager property. If the XPath doesn't resolve, pass through whatever error there was (a la this method on the Document object today with embedded XML).

This method allows the developer to get back a single node from within the data store item.

Text As String: Gets/sets the text for the current node. Unlike MSXML, setting this on a node replaces the contents of that node with the specified string—for example, setting it to “test” on a non-leaf element <foo> where foo's contents look like:

Will not fail, but it will result in a different message internally to the data store, and externally to the clients of the data store. If the resulting replacement would be structurally invalid, fail with an error message: “This operation cannot be performed because it would result in a structurally invalid DOM.”

XML As String: Returns the raw XML representation of the current node and its children (if any).

XPath As String: Returns a String with the canonicalized XPath for the current node. If the node is no longer in the DOM (it was deleted), fails with: “This node has been deleted from the associated custom XML part.”

New Enums:

msoCustomXMLDataNodeType represents the types of XML nodes available msoCustomXMLNodeAttribute represents an XML attribute node.msoCustomXMLNodeCData represents a CDATA node.msoCustomXMLNodeComment represents an XML comment node.msoCustomXMLNodeDocument represents an XML document (/) node.msoCustomXMLNodeElement represents an XML element node.msoCustomXMLNodeProcessingInstruction represents an XML processing instruction node. msoCustornXMLNodeText represents a text node.

Parameters: Child: A CustomXMLNode object that represents the child node of the context node to be deleted. If this node is not a child of the context node, fail with the error message: “This node cannot be removed because it is not a child of the current element.” Name: A String that represents the base name of the element to be added to the XML DOM. Namespace: An optional String that represents the namespace of the element to be added to the XML DOM. Required to add nodes of type msoXMLNodeElement or msoXMLNodeAttribute, ignored otherwise. NodeType: An optional msoXMLNodeType that specifies the type of node to create. If not specified, assumed to be msoXMLNodeElement. NodeValue: An optional String which is used to set the value of the node for nodes which allow text. If the node doesn't allow text, the parameter is ignored.

Removes the specified child node (and its subtree) from the stream, and replaces it with the node specified in the same location. If the resulting deletion would be structurally invalid (and schema enforcement is turned on) fail with an error message: “This operation cannot be performed because it would result in a structurally invalid DOM.”

XMLNamespace: The object representing a single unique namespace in the Schema Library.

AttachToCustomXMLPart(CustomXMLPart As Variant) As Void

Parameters: CustomXMLPart: A Variant, which can be either the CustomXMLPart object for the desired stream, or the index of that steam in the CustomXMLParts collection.

Attaches the schema for this XML namespace to the given CustomXMLPart.

XMLSchemaReference: The object representing a single unique namespace referenced in the current document.

Delete( ) As Void: Removes the namespace—as well as all elements in that namespace—from the CustomXMLPart. However, in this case the data store may reject this operation because structural schema enforcement is enabled and removing these elements would result in a structurally invalid DOM. In this case, fail and throw an error: “This operation cannot be performed while schema enforcement is enabled, because the resulting stream would be structurally invalid.”

Parameters: Name: A String that represents the base name of the element to be added to the XML DOM. Namespace: An optional String that represents the namespace of the element to be added to the XML DOM. Required to add nodes of type msoXMLNodeElement or msoXMLNodeAttribute, ignored otherwise. Parent: An optional CustomXMLNode representing the node under which this node should be added. If called off of the CustomXMLNodes collection returned by the Attributes property, then assumed to be the parent node of the attributes. If called in any other case, then this parameter is specified or returns an error: “You must specify a parent node to add this node to your document.” NextSibling:An optional CustomXMLNode representing the node which should become the next sibling of the new node. If not specified, the node is added to the end of the parent node's children. Ignored for additions of type msoXMLNodeAttribute. If NextSibling is not a child of parent, return an error: “This node cannot be added because the next sibling node is not a child of the parent node.” NodeType: An optional msoXMLNodeType that specifies the type of node to create. If not specified, assumed to be msoXMLNodeElement unless called off of the Attributes property, then assumed to be msoXMLNodeAttribute. NodeValue: An optional String which is used to set the value of the node for nodes which allow text. If the node doesn't allow text, the parameter is ignored.

A generic method for adding an XML node to a data store item. If called off of an CustomXMLNodes object returned by the Attributes property, then the Parent has a default of the parent node and the NodeType has a default of msoXMLNodeAttribute. In all other cases, Parent is required and NodeType defaults to msoXMLNodeElement. If the resulting addition would be structurally invalid (and schema enforcement is turned on) fail with an error message: “This operation cannot be performed while schema enforcement is turned on, because it would result in a structurally invalid data stream.” If the namespace is not in the schema references collection, fail and error message: “To add this element, you must first attach its schema to the data stream.”

CustomDataXMLSchemaReferences( ): Collection representing all of the unique namespaces identified in the CustomXMLPart. Note: By default, populate this with an entry for each namespace declared in the XML file.

Parameters: NamespaceURI: A String containing the namespace defined by the schema to add to the schema collection. Alias: A String containing an alias to write when adding this schema to the schema library. FileName: A String containing the path to the schema that should be added to the schema library. InstallForAllUsers: A Boolean determining whether the Schema Library keys should be added to HKCU (the default) or HKLM

This method adds a schema reference. To do this, add the appropriate namespace declaration to the root element of the CustomXMLPart if it is not already defined in the file. At open time, all declared namespaces are used to populate this collection.

EnforceStructure As Boolean: Gets and sets a Boolean which corresponds to whether the data store should enforce structural validity on the associated CustomXMLPart according to its schema. If the user attempts to set this property to TRUE while the contents of the CustomXMLPart are not valid, return an error: “Schema enforcement cannot be turned on while the contents of this data stream are structurally invalid.”

Count As Long: Returns the number of namespaces currently referenced in this CustomXMLPart.

Parameters: Index: A Variant, which can be one of the following two types: A Long representing the index of the desired CustomDataXMLSchemaReference in the collection; and a String representing the namespace of the desired CustomDataXMLSchemaReference in the collection.

This is the default member of the CustomDataXMLSchemaReferences object, and it returns an XMLSchemaReference object corresponding to the requested object.

Validate( ) As Void: This method validates the entire stream against all schemas in the CustomDataXMLSchemaReferences collection. Errors are reported on the individual nodes (see the ValidationStatus property)/

Parameters: NewCustomXMLNode: A CustomXMLNode object corresponding to the node just added to the CustomXMLPart. Note: This node may have children (if a subtree was just added to the document). InUndoRedo: A Boolean returning TRUE if the node was added as part of an Undo/Redo action by the user, FALSE otherwise.

This event fires whenever XML nodes are about to be added to the current document. If the add operation involves a subtree of XML document being added into the CustomXMLPart, fire this event once for the topmost node in the change. This event fires once for each change messaged to the data store, so side effects of the change represented by this event also trigger the event.

Parameters: OldCustomXMLNode: A CustomXMLNode object corresponding to the node about to be removed from the CustomXMLPart. Note: This node may have children (if a subtree is being removed from the document). InUndoRedo: A Boolean returning TRUE if the node was added as part of an Undo/Redo action by the user, FALSE otherwise.

This event fires whenever XML nodes are deleted from the current item in the data store. If the delete operation involves a subtree of the XML document in the CustomXMLPart, fire this event once for the topmost node in the change. This event fires once for each change messaged to the data store, so side effects of the change represented by this event also trigger the event. If the event handler tries to modify anything that would be under this node, fail with an error message: “This change is not allowed because this node is about to be deleted.”