Extensions

Home > Reference Manual > Description of Add ins and Add in Roots > Extensions

Extensions can be declared using:

• The [Mono.Addins.ExtensionNode] attribute
• Any custom attribute declared in an extension point using the ExtensionAttributeType property.
• An XML manifest.

Declaration using Mono.Addins.ExtensionNode

The Mono.Addins.ExtensionNode attribute can be applied to a type or to an assembly:

• When applied to a type, it declares a type extension. The extension point being extended is determined by looking at the base types and some properties of the attribute:
• The extension point matching the path provided in the Path property (if provided)
• Any extension point bound to base classes or interfaces implemented by the type. If there are several types bound to extension point, the Type property can be used to specify the desired extension point.
• When applied to an assembly, it declares a generic extension. In this case, it is mandatory to specify the path of the extension point being extended in the Path property

Mono.Addins.ExtensionNode has the following properties (all are optional):

Property	Description
Path	Path of the extension point being extended. Mandatory when the attribute is applied to an assembly.
Id	Identifier of the node.
InsertBefore	Identifier of the node before which this node has to be inserted.
InsertAfter	Identifier of the node after which this node has to be inserted.
Type	When the attribute is applied to a type that implements several base types bound to extension points, this property can be used to specify the base type for which we want to create an extension.
NodeName	Name of the extension node being created. Rarely used.

The following example declares an extension for a simple extension point bound to the ICommand interface:

[Extension]
public class HelloCommand: ICommand
{
	public void Run ()
	{
		Console.WriteLine ("Hello World");
	}
}

The same example, but using a specific extension point path:

[Extension (Path="/Commands/SpecialCommands")]
public class HelloCommand: ICommand
{
	public void Run () { ... }
}

Declaration using a Custom Extension Attribute

Extension points can define custom attributes to be used to declare their extensions. Such custom attributes must subclass Mono.Addins.CustomExtensionAttribute, which has the following properties (all optional):

Property	Description
Id	Identifier of the node.
InsertBefore	Identifier of the node before which this node has to be inserted.
InsertAfter	Identifier of the node after which this node has to be inserted.

In addition, the custom attribute can define its own properties, which can be used to specify extension metadata.

Here is an example of custom attributes being used to define some buttons in a toolbar extension point:

[assembly:ToolButton (Id="OpenCmd", Icon="open.png" Label="Open File")]
[assembly:ToolButton (Id="NewCmd", InsertAfter="OpenCmd" Icon="new.png" Label="New File")]
[assembly:ToolSeparator (Id="Separator1", InsertAfter="NewCmd")]
[assembly:ToolButton (Id="CloseCmd", InsertAfter="Separator1" Label="Close")]

Declaration using an XML manifest

Given the sample extension point described in the previous section, the following extension would then be correct in an add-in:

<Addin namespace="TextEditor" id="Core" version="1.0" ...>
	...
	<Extension path="/TextEditor/ToolbarButtons">
		<ToolButton id="New" icon="gtk-new" />
		<ToolButton id="Open" icon="gtk-open" />
		<ToolSeparator id="FileSectionSeparator"/>
		<ToolButton id="Cut" icon="gtk-cut" />
		<ToolButton id="Copy" icon="gtk-copy" />
		<ToolButton id="Paste" icon="gtk-paste" />
	</Extension>
	...
</Addin>

Extensions are registered using the Extension element:

<Addin>
	...
	<Extension path = "...">
		<SomeNode id="..." insertafter="..." insertbefore="..." .../>
		...
	</Extension>
	...	
</Addin>

The following table describes the attributes and elements shown above:

XML	Description
/Addin/Extension	Registers extension nodes to an extension point.
/Addin/Extension/@path	Path of the extension point where the nodes will be registered.
/Addin/Extension/{any}	An extension node. The name is defined by the extension point.
/Addin/Extension/{any}/@id	Identifier of the node. It's optional, but needed if the node will be referenced from other nodes.
/Addin/Extension/{any}/@insertafter	Identifier of the node after which this node has to be placed.
/Addin/Extension/{any}/@insertbefore	Identifier of the node before which this node has to be placed.
/Addin/Extension/{any}/@{any}	Node-specific attributes.

The kind of nodes that may be added to an Extension element depend on the extension point being extended (see previous section).

Notice that the previous example extension is declared in the TextEditor add-in root. It is allowed because the extension point being extended is declared in the same root.

Extension nodes may have an ID. Specifying the ID is optional but needed if the node has to be referenced by other nodes or from the host. It is recommended to use namespace-qualified node IDs, to avoid name collision.

The insertafter and insertbefore attributes can be used to specify the relative location of a node. The nodes referenced in those attributes must be defined either in the add-in root being extended, or in any add-in on which this add-in depends. Here is an example:

<Addin namespace="TextEditor">
	...
	<Dependencies>
		<Addin id="Core" version="1.0" />
	</Dependencies>
	...
	<Extension path = "/TextEditor/ToolbarButtons">
		<ToolButton id="Save" insertafter="Open" insertbefore="FileSectionSeparator" icon="gtk-save"/>
	</Extension>
	...	
</Addin>

The add-in engine ensures that if insertafter is specified, the node will be inserted after the specified node, and before any other node defined in the same extension. So, in this example, the insertbefore attribute would not be needed. Notice that other nodes in other add-ins may require to be inserted after the same node, so there is no guarantee that the node will be placed ''just after'' the specified node, only that it will be placed somewhere after it.