Version 3.2 - Last revised May 9, 2006
The manifest markup definitions below make use of various naming tokens and identifiers. To eliminate ambiguity, here are some production rules for these [are referenced in text below]. In general, all identifiers are case-sensitive.
SimpleToken := sequence of characters from ('a-z','A-Z','0-9','_')
ComposedToken := SimpleToken | (SimpleToken '.' ComposedToken)
QualifiedId := ComposedToken '.' SimpleToken
ExtensionId := SimpleToken | QualifiedId
ExtensionPointId := SimpleToken | QualifiedId
ExtensionPointReference := SimpleToken | QualifiedId
The remainder of this section describes the plugin.xml file structure as a series of DTD fragments. File plugin.dtd presents the DTD definition in its entirety.
<?xml encoding="US-ASCII"?> <?eclipse version="3.2"?> <!ELEMENT plugin (extension-point*, extension*)>
The <plugin> element defines the body of the manifest. It optionally contains declarations of any new extension points being introduced by the plug-in, as well as configuration of functional extensions (configured into extension points defined by other plug-ins, or introduced by this plug-in).
The XML DTD construction rule element* means zero or more occurrences of the element; element? means zero or one occurrence of the element; and element+ (used below) means one or more occurrences of the element. Based on the <plugin> definition above, this means, for example, that a plug-in containing no extension point declarations or extension configurations is valid (for example, common libraries that other plug-ins depend on). Similarly, a plug-in containing only extension configurations and no extension points of its own is also valid (for example, configuring classes delivered in other plug-ins into extension points declared in other plug-ins).
The Eclipse architecture is based on the notion of configurable extension points. The platform itself predefines a set of extension points that cover the task of extending the platform and desktop (for example, adding menu actions, contributing embedded editor). In addition to the predefined extension points, each supplied plug-in can declare additional extension points. By declaring an extension point the plug-in is essentially advertising the ability to configure the plug-in function with externally supplied extensions. For example, the Page Builder plug-in may declare an extension point for adding new Design Time Controls (DTCs) into its builder palette. This means that the Page Builder has defined an architecture for what it means to be a DTC and has implemented the code that looks for DTC extensions that have been configured into the extension points.
<!ELEMENT extension-point EMPTY> <!ATTLIST extension-point name CDATA #REQUIRED id CDATA #REQUIRED schema CDATA #IMPLIED >
The <extension-point> element has the following attributes:
Actual extensions are configured into extension points (predefined, or newly declared in this plug-in) in the <extension> section. The configuration information is specified as well-formed XML contained between the <extension> and </extension> tags. The platform does not specify the actual form of the configuration markup (other than requiring it to be well-formed XML). The markup is defined by the supplier of the plug-in that declared the extension point. The platform does not actually interpret the configuration markup. It simply passes the configuration information to the plug-in as part of the extension point processing (at the time the extension point logic queries all of its configured extensions).
<!ELEMENT extension ANY> <!ATTLIST extension point CDATA #REQUIRED id CDATA #IMPLIED name CDATA #IMPLIED >
The <extension> element has the following attributes:
Important: The content of the <extension> element is declared using the ANY rule. This means that any well-formed XML can be specified within the extension configuration section (between <extension> and </extension> tags).
Fragments are used to increase the scope of a plug-in. An example would be to incorporate data such as messages or labels in another language.
<?xml encoding="US-ASCII"?> <?eclipse version="3.2"?> <!ELEMENT fragment (extension-point*, extension*)>
The <extension-point>, and <extension> components of a fragment will be logically added to the hosting plug-in.
Special processing was added to support backward compatibility for ExtensionId and ExtensionPointId that used to contain dots ('.') prior to the version 3.2. Depending on the version specified in the <?eclipse version?> tag:
This rule applies only to the ExtensionId and ExtensionPointId that contain dot ('.') character(s).