intellij-sdk-code-samples/basics/plugin_structure/plugin_extensions_and_extension_points.html
2016-01-14 19:38:06 -08:00

207 lines
15 KiB
HTML

<!doctype html>
<html lang="en-US">
<head>
<meta charset="UTF-8">
<title>Plugin Extensions and Extension Points / IntelliJ Platform SDK DevGuide</title>
<link rel="stylesheet" href="/intellij/sdk/docs/app/css/styles.min.css">
<!-- non-retina iPad pre iOS 7 -->
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-72x72.png" sizes="72x72">
<!-- retina iPhone pre iOS 7 -->
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-114x114.png" sizes="114x114">
<!-- retina iPad pre iOS 7 -->
<link rel="apple-touch-icon" href="/intellij/sdk/docs/apple-touch-icon-144x144.png" sizes="144x144">
<link rel="apple-touch-icon-precomposed" sizes="144x144" href="/intellij/sdk/docs/apple-touch-icon-precomposed.png">
<!-- normal favicon -->
<link rel="shortcut icon" type="image/x-icon" href="/intellij/sdk/docs/favicon.ico">
<link rel="icon" type="image/png" href="/intellij/sdk/docs/favicon.png">
<link rel="stylesheet" href="/intellij/sdk/docs/styles/styles.css"></head>
<body data-id="basics/plugin_structure/plugin_extensions_and_extension_points">
<div class="wrapper">
<section class="panel _nav">
<header class="panel__header">
<div class="container">
<form class="search-box">
<label for="search-box__input" class="search-box__label">
<input type="text" class="search-box__input" id="search-box__input" placeholder="Search IntelliJ Platform SDK DevGuide">
</label>
<div class="search-box__clear" title="Clear"></div>
</form>
</div>
</header>
<nav class="panel__content">
<div class="container _nav">
<menu class="nav-tree"></menu>
</div>
<div class="container _footer panel__footer">
<p><a href="https://youtrack.jetbrains.com/issues/IJSDK">Send feedback</a></p>
<p>&copy; 2000&ndash;2016 <a href="//www.jetbrains.com">JetBrains</a> s.r.o.<br>
All rights reserved.</p>
</div>
</nav>
</section>
<main class="panel _main" role="main">
<header class="panel__header">
<div class="container">
<h3>IntelliJ Platform SDK DevGuide</h3>
<div class="shortcuts-switcher"><label for="switch-shortcuts">Keymap:</label><select id="switch-shortcuts" class="select _shortcuts" height="1">
<option data-group="primary" value="default" selected>Default</option>
<option data-group="primary" value="default_for_gnome">GNOME</option>
<option data-group="primary" value="default_for_kde">KDE</option>
<option data-group="primary" value="default_for_xwin">XWindow</option>
<option data-group="primary" value="emacs">Emacs</option>
<option data-group="primary" value="jbuilder">JBuilder</option>
<option data-group="primary" value="visual_studio">Visual Studio</option>
<option data-group="primary" value="netbeans_6.5">NetBeans 6.5</option>
<option data-group="primary" value="eclipse">Eclipse</option>
<option data-group="secondary" value="mac_os_x_10.5_">OS X 10.5+</option>
<option data-group="secondary" value="mac_os_x">OS X</option>
<option data-group="secondary" value="eclipse_mac_os_x">OS X Eclipse</option></select>
</div>
<div class="panel-trigger"></div>
</div>
</header>
<section class="panel__content">
<div class="container">
<article class="article" data-shortcut-switcher="false">
<h1>Plugin Extensions and Extension Points</h1>
<p>The <em>IntelliJ Platform</em> provides the concept of <em>extensions</em> and <em>extension points</em> that allows a plugin to interact with other plugins or with the IDE itself.</p>
<a name="extension-points" class="elem-anchor"></a>
<h2>Extension points<a href="#extension-points" class="anchor-link"><span></span></a></h2>
<p>If you want your plugin to allow other plugins to extend its functionality, in the plugin, you must declare one or several <em>extension points</em>. Each extension point defines a class or an interface that is allowed to access this point.</p>
<a name="extensions" class="elem-anchor"></a>
<h2>Extensions<a href="#extensions" class="anchor-link"><span></span></a></h2>
<p>If you want your plugin to extend the functionality of other plugins or the <em>IntelliJ Platform</em>, you must declare one or several <em>extensions</em>.</p>
<a name="how-to-declare-extensions-and-extension-points" class="elem-anchor"></a>
<h2>How to declare extensions and extension points<a href="#how-to-declare-extensions-and-extension-points" class="anchor-link"><span></span></a></h2>
<p>You can declare extensions and extension points in the plugin configuration file <code class="code highlight language-text">plugin.xml</code>, within the <code class="code highlight language-text">&lt;extensions&gt;</code> and <code class="code highlight language-text">&lt;extensionPoints&gt;</code> sections, respectively.</p>
<p><strong>To declare an extension point</strong></p>
<p>In the <code class="code highlight language-text">&lt;extensionPoints&gt;</code> section, insert a child element <code class="code highlight language-text">&lt;extensionPoint&gt;</code> that defines the extension point name and the name of a bean class or an interface that is allowed to extend the plugin functionality in the <code class="code highlight language-text">name</code>, <code class="code highlight language-text">beanClass</code> and <code class="code highlight language-text">interface</code> attributes, respectively.</p>
<p>To clarify this procedure, consider the following sample section of the plugin.xml file:</p>
<pre><code class="code-block__wrapper code-block _highlighted lang_xml"><span class="nt">&lt;extensionPoints&gt;</span>
<span class="nt">&lt;extensionPoint</span> <span class="na">name=</span><span class="s">"MyExtensionPoint1"</span> <span class="na">beanClass=</span><span class="s">"MyPlugin.MyBeanClass1"</span><span class="nt">&gt;</span>
<span class="nt">&lt;extensionPoint</span> <span class="na">name=</span><span class="s">"MyExtensionPoint2"</span> <span class="na">interface=</span><span class="s">"MyPlugin.MyInterface"</span><span class="nt">&gt;</span>
<span class="nt">&lt;/extensionPoints&gt;</span>
</code></pre>
<ul>
<li>The <code class="code highlight language-text">interface</code> attribute sets an interface the plugin that contributes to the extension point must implement.</li>
<li>The <code class="code highlight language-text">beanClass</code> attribute sets a bean class that specifies one or several properties annotated with the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/dom-openapi/src/com/intellij/util/xml/Attribute.java" data-bypass="yes" target="_blank"><span>@Attribute</span></a> annotation.</li>
</ul>
<p>The plugin that contributes to the extension point will read those properties from the <code class="code highlight language-text">plugin.xml</code> file.</p>
<p>To clarify this, consider the following sample <code class="code highlight language-text">MyBeanClass1</code> bean class used in the above <code class="code highlight language-text">plugin.xml</code> file:</p>
<pre><code class="code-block__wrapper code-block _highlighted lang_java"><span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyBeanClass1</span> <span class="kd">extends</span> <span class="n">AbstractExtensionPointBean</span> <span class="o">{</span>
<span class="nd">@Attribute</span><span class="o">(</span><span class="s">"key"</span><span class="o">)</span>
<span class="kd">public</span> <span class="n">String</span> <span class="n">key</span><span class="o">;</span>
<span class="nd">@Attribute</span><span class="o">(</span><span class="s">"implementationClass"</span><span class="o">)</span>
<span class="kd">public</span> <span class="n">String</span> <span class="n">implementationClass</span><span class="o">;</span>
<span class="kd">public</span> <span class="n">String</span> <span class="nf">getKey</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="n">key</span><span class="o">;</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="n">String</span> <span class="nf">getClass</span><span class="o">()</span> <span class="o">{</span>
<span class="k">return</span> <span class="n">implementationClass</span><span class="o">;</span>
<span class="o">}</span>
<span class="o">}</span>
</code></pre>
<p>Note that to declare an extension designed to access the <code class="code highlight language-text">MyExtensionPoint1</code> extension point, your <code class="code highlight language-text">plugin.xml</code> file must contain the <code class="code highlight language-text">&lt;MyExtensionPoint1&gt;</code> tag with the <code class="code highlight language-text">key</code> and <code class="code highlight language-text">implementationClass</code> attributes set to appropriate values (see sample below).</p>
<p><strong>To declare an extension</strong></p>
<ol>
<li>For the <code class="code highlight language-text">&lt;extensions&gt;</code> element, set the <code class="code highlight language-text">xmlns</code> (deprecated) or <code class="code highlight language-text">defaultExtensionNs</code> attribute to one of the following values:
<ul>
<li><code class="code highlight language-text">com.intellij</code>, if your plugin extends the IntelliJ Platform core functionality.</li>
<li><code class="code highlight language-text">{ID of a plugin}</code>, if your plugin extends a functionality of another plugin.</li>
</ul>
</li>
<li>Add a new child element to the <code class="code highlight language-text">&lt;extensions&gt;</code> element. The child element name must match the name of the extension point you want the extension to access.</li>
<li>Depending on the type of the extension point, do one of the following:
<ul>
<li>If the extension point was declared using the <code class="code highlight language-text">interface</code> attribute, for newly added child element, set the <code class="code highlight language-text">implementation</code> attribute to the name of the class that implements the specified interface.</li>
<li>If the extension point was declared using the <code class="code highlight language-text">beanClass</code> attribute, for newly added child element, set all attributes annotated with the <a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/xml/dom-openapi/src/com/intellij/util/xml/Attribute.java" data-bypass="yes" target="_blank"><span>@Attribute</span></a> annotations in the specified bean class.</li>
</ul>
</li>
</ol>
<p>To clarify this procedure, consider the following sample section of the <code class="code highlight language-text">plugin.xml</code> file that defines two extensions designed to access the <code class="code highlight language-text">appStarter</code> and <code class="code highlight language-text">applicationConfigurable</code> extension points in the <em>IntelliJ Platform</em> and one extension to access the <code class="code highlight language-text">MyExtensionPoint1</code> extension point in a test plugin:</p>
<pre><code class="code-block__wrapper code-block _highlighted lang_xml"><span class="c">&lt;!-- Declare extensions to access extension points in the IntelliJ Platform.
These extension points have been declared using the "interface" attribute.
--&gt;</span>
<span class="nt">&lt;extensions</span> <span class="na">defaultExtensionNs=</span><span class="s">"com.intellij"</span><span class="nt">&gt;</span>
<span class="nt">&lt;appStarter</span> <span class="na">implementation=</span><span class="s">"MyTestPackage.MyTestExtension1"</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;applicationConfigurable</span> <span class="na">implementation=</span><span class="s">"MyTestPackage.MyTestExtension2"</span> <span class="nt">/&gt;</span>
<span class="nt">&lt;/extensions&gt;</span>
<span class="c">&lt;!-- Declare extensions to access extension points in a custom plugin
The MyExtensionPoint1 extension point has been declared using *beanClass* attribute.
--&gt;</span>
<span class="nt">&lt;extensions</span> <span class="na">defaultExtensionNs=</span><span class="s">"MyPluginID"</span><span class="nt">&gt;</span>
<span class="nt">&lt;MyExtensionPoint1</span> <span class="na">key=</span><span class="s">"keyValue"</span> <span class="na">implementationClass=</span><span class="s">"MyTestPackage.MyClassImpl"</span><span class="nt">&gt;&lt;/MyExtensionPoint1&gt;</span>
<span class="nt">&lt;/extensions&gt;</span>
</code></pre>
<a name="how-to-get-the-extension-points-list" class="elem-anchor"></a>
<h2>How to get the extension points list?<a href="#how-to-get-the-extension-points-list" class="anchor-link"><span></span></a></h2>
<p>To get a list of extension points available in the <em>IntelliJ Platform</em> core, consult the <code class="code highlight language-text">&lt;extensionPoints&gt;</code> section of the following XML configuration files:</p>
<ul>
<li><a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/LangExtensionPoints.xml" data-bypass="yes" target="_blank"><span><code class="code highlight language-text">LangExtensionPoints.xml</code></span></a></li>
<li><a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml" data-bypass="yes" target="_blank"><span><code class="code highlight language-text">PlatformExtensionPoints.xml</code></span></a></li>
<li><a href="https://upsource.jetbrains.com/idea-ce/file/idea-ce-1731d054af4ca27aa827c03929e27eeb0e6a8366/platform/platform-resources/src/META-INF/VcsExtensionPoints.xml" data-bypass="yes" target="_blank"><span><code class="code highlight language-text">VcsExtensionPoints.xml</code></span></a></li>
</ul>
<a name="additional-information-and-samples" class="elem-anchor"></a>
<h2>Additional Information and Samples<a href="#additional-information-and-samples" class="anchor-link"><span></span></a></h2>
<p>For samples plugins and detailed instructions on how to create your plugin that contributes to the IDEA core, refer to Customizing the IDEA Settings Dialog and Creation of Tool Windows.</p>
<div class="last-modified">
Last modified: 15 December 2015
</div>
</article>
<section class="disqus">
<div id="disqus_thread"></div>
</section>
</div>
</section>
</main>
</div>
<script data-main="/intellij/sdk/docs/app/js/main.build" data-baseurl="/intellij/sdk/docs/" src="/intellij/sdk/docs/app/js/vendor/requirejs/require.js"></script>
</body>
</html>