Node sets

Home > Reference Manual > Description of Add ins and Add in Roots > Node sets

Node sets allows grouping a set of extension node declarations and give an identifier to that group (the node set). Once a node set is declared, it can be referenced from several extension points which use the same extension node structure. Extension node sets also allow declaring recursive extension nodes, that is, extension nodes with a tree structure.

Extension node sets can only be declared and used in XML manifests.

Extension node sets are declared using the ExtensionNodeSet element, and they look almost like an extension point, but instead of a path, they have an identifier. Node sets can be referenced from extension nodes using a ExtensionNodeSet element with the same ID. For example:

<Addin>
	...
	<!-- Declares the extension node set -->
	<ExtensionNodeSet id="ToolbarNodeSet">
		<ExtensionNode name="ToolButton" type="..." />
		<ExtensionNode name="ToolSeparator" type="..." />
	</ExtensionNodeSet> 
	
	<!-- An extension point using the node set -->
	<ExtensionPoint path="/TextEditor/ToolbarButtons" name="...">
		<Description>...</Description>
		<ExtensionNodeSet id="ToolbarNodeSet"/>
	</ExtensionPoint>
	...
</Addin>

ExtensionNodeSet references can be used anywhere an extension node can be declared, so they can also be used to specify the children accepted by an extension node. It is also possible to reference more than one extension set from the same extension point or extension node.

Another example: the following set of declarations might be used to create extension points for the menus of the text editor:

<Addin namespace="TextEditor" id="Core" version="1.0">
	...
	<!-- Declares the extension node set -->
	<ExtensionNodeSet id="MenuNodeSet">
		<ExtensionNode name="MenuItem" type="TextEditor.MenuItemNode" />
		<ExtensionNode name="MenuSeparator" type="TextEditor.MenuSeparatorNode" />
		<ExtensionNode name="Menu" type="TextEditor.SubmenuNode">
			<!-- This is a recursive reference to the node set -->
			<ExtensionNodeSet id="MenuNodeSet" />
		</ExtensionNode>
	</ExtensionNodeSet> 

	<!-- An extension point using the node set -->
	<ExtensionPoint path="/TextEditor/MainMenu">
		<Description>Menu for the main window</Description>
		<ExtensionNodeSet id="MenuNodeSet" />
	</ExtensionPoint>

	<!-- Another extension point using the node set -->
	<ExtensionPoint path="/TextEditor/DocumentContextMenu">
		<Description>Context menu for the document being edited</Description>
		<ExtensionNodeSet id="MenuNodeSet"/>
	</ExtensionPoint>
	...
</Addin>

There are two good reasons for using a node set in this example:

• An application may have several menus, so it makes sense to be able to reuse the same structure of nodes for all menus.
• Menus are hierarchical. Menus can contain submenus with the same structure. This recursive definition can only be done using node sets. Notice that the Menu item in MenuNodeSet is recursively referencing the same node set.

Here are some sample extensions for the above extension points:

<Addin namespace="TextEditor" id="Core" version="1.0">
	...
	<Extension path="/TextEditor/MainMenu">
		<MenuItem Label="Open" />
		<Menu Label="New">
			<MenuItem Label="Document" />
			<MenuItem Label="Document" />
		</Menu>
		<MenuItem Label="Save" />
		<MenuSeparator/>
		<MenuItem Label="Exit" />
	</Extension>

	<Extension path="/TextEditor/DocumentContextMenu">
		<MenuItem Label="Cut" />
		<MenuItem Label="Copy" />
		<MenuItem Label="Paste" />
		<MenuSeparator/>
		<MenuItem Label="Options" />
	</Extension>
	...
</Addin>