bundles/org.eclipse.platform.doc.isv/guide/ua_dynamic_extensions.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <meta http-equiv="Content-Style-Type" content="text/css">
 <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
 <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
 <title>Content extensions</title>
 </head>
 <body>

 <h2>Content extensions</h2>

 <p>
 A content extension is either a contribution of content into a known anchor (similar to an
 extension into an extension point), or the replacement of an existing element in a document.
 </p>

 <h3>Contributing into anchors</h3>

 <p>
 Anchor elements (e.g. <code>&lt;anchor id=&quot;my_anchor&quot;/&gt;</code>) can be specified
 in any user assistance XML document, and represent places at which other components are allowed
 to extend this document. Specifying an anchor is as simple as adding the element in your markup.
 </p>

 <p>
 To contribute content into an anchor, you must write the content to be added in a separate XML
 file and hook it into the platform using one of two extension points. For <a
 href="ua_help.htm">help</a> or <a href="ua_cheatsheet.htm">cheat sheet</a> content, you must
 use the <a href="../reference/extension-points/org_eclipse_help_contentExtension.html"><code>
 org.eclipse.help.contentExtension</code></a> extension point. For <a href="ua_intro.htm">welcome
 (intro)</a> extensions, use
 <a href="../reference/extension-points/org_eclipse_ui_intro_configExtension.html"><code>
 org.eclipse.ui.intro.configExtension</code></a>. The table of contents markup also allows the
 special constructs <a href="ua_help_content_nested.htm"><code>link</code></a> and <a
 href="ua_help_content_nested.htm"><code>link_to</code></a> which perform a similar function
 to includes and contributions, but perform the additional operation of merging extra documents
 to index for searching.
 </p>

 <p>
 For example, let's say component A's documentation provides a listing of file formats it
 supports. If component B extends A's support to several more formats, you can place an
 anchor in A's list, and extend the list from B. For example:
 </p>

 <pre>
    &lt;p&gt;The following list shows the supported formats:&lt;/p&gt;
    &lt;ul&gt;
       &lt;li&gt;Portable Network Graphics (.png)&lt;/li&gt;
       &lt;li&gt;Joint Photographic Experts Group (.jpeg)&lt;/li&gt;
       &lt;li&gt;Graphical Interchange Format (.gif)&lt;/li&gt;

       &lt;!-- Extra formats go here --&gt;
       <font color="blue">&lt;anchor id="image_format_list"/&gt;</font>
    &lt;/ul&gt;
 </pre>

 <p>
 Then component B can make a contribution to the anchor to add more formats
 to the list by specifying the following extension:
 </p>

 <pre>
    &lt;extension point=&quot;org.eclipse.help.contentExtension&quot;&gt;
       &lt;contentExtension
             file=&quot;path/to/extension.xml&quot;/&gt;
    &lt;/extension&gt;
 </pre>

 <p>
 Where the file <code>path/to/extension.xml</code> might contain:
 </p>

 <pre>
    &lt;contentExtension&gt;
       &lt;contribution
             content=&quot;docs/mydoc.xhtml#mycontent&quot;
             path=&quot;/component_a_plugin/docs/doc_with_anchor.xhtml#anchorId&quot;&gt;
       &lt;/contribution&gt;
    &lt;/contentExtension&gt;
 </pre>

 <p>
 The element with the <code>id</code> attribute <code>mycontent</code> in document
 <code>docs/mydoc.xhtml</code> would contain the content you wish to contribute
 into the anchor. The result will be that when the user views the document, the extra content
 will appear at the anchor as though it was explicitly added into the original document.
 </p>

 <h3>Replacing content</h3>

 <p>
 Any XML element in a user assistance document that has an <code>id</code> attribute that is
 unique to that document can be replaced with any other element.
 </p>

 <p>
 As with contributions into anchors, to replace an element, you must write the new element to
 replace with in a separate XML file and hook it into the platform using one of two extension
 points. For <a href="ua_help.htm">help</a> or <a href="ua_cheatsheet.htm">cheat sheet</a> content,
 you must use the <a href="../reference/extension-points/org_eclipse_help_contentExtension.html">
 <code>org.eclipse.help.contentExtension</code></a> extension point. For <a href="ua_intro.htm">
 welcome (intro)</a> extensions, use
 <a href="../reference/extension-points/org_eclipse_ui_intro_configExtension.html"><code>
 org.eclipse.ui.intro.configExtension</code></a>.
 </p>

 <p>
 The only difference with replacements as opposed to contributions into anchors is the name of the
 XML element used in the markup; use the <code>replacement</code> element instead of
 <code>contribution</code> (or <code>replacementContent</code> in the case of welcome). For example:
 </p>

 <pre>
    &lt;contentExtension&gt;
       &lt;replacement
             content=&quot;docs/mydoc.xml#myelement&quot;
             path=&quot;/plugin.id/path/doc.xml#elementId&quot;&gt;
       &lt;/replacement&gt;
    &lt;/contentExtension&gt;
 </pre>

 <p>
 (Note the markup is different for welcome, as specified in the <a
 href="../reference/extension-points/org_eclipse_ui_intro_configExtension.html"><code>
 org.eclipse.ui.intro.configExtension</code></a> extension point)
 </p>

 <h3>Path format</h3>

 <p>
 The format of the <code>path</code> attribute is <code>/pluginId/path/file.xml#elementId</code>,
 except welcome where it is <code>pageId/path/to/elementId</code> where the pageId is the welcome
 page id, and all other path segments are ids of container elements like groups, leading to the
 target element.
 </p>

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
	<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
	<title>Content extensions</title>
	</head>
	<body>

	<h2>Content extensions</h2>

	<p>
	A content extension is either a contribution of content into a known anchor (similar to an
	extension into an extension point), or the replacement of an existing element in a document.
	</p>

	<h3>Contributing into anchors</h3>

	<p>
	Anchor elements (e.g. <code><anchor id="my_anchor"/></code>) can be specified
	in any user assistance XML document, and represent places at which other components are allowed
	to extend this document. Specifying an anchor is as simple as adding the element in your markup.
	</p>

	<p>
	To contribute content into an anchor, you must write the content to be added in a separate XML
	file and hook it into the platform using one of two extension points. For <a
	href="ua_help.htm">help</a> or <a href="ua_cheatsheet.htm">cheat sheet</a> content, you must
	use the <a href="../reference/extension-points/org_eclipse_help_contentExtension.html"><code>
	org.eclipse.help.contentExtension</code></a> extension point. For <a href="ua_intro.htm">welcome
	(intro)</a> extensions, use
	<a href="../reference/extension-points/org_eclipse_ui_intro_configExtension.html"><code>
	org.eclipse.ui.intro.configExtension</code></a>. The table of contents markup also allows the
	special constructs <a href="ua_help_content_nested.htm"><code>link</code></a> and <a
	href="ua_help_content_nested.htm"><code>link_to</code></a> which perform a similar function
	to includes and contributions, but perform the additional operation of merging extra documents
	to index for searching.
	</p>

	<p>
	For example, let's say component A's documentation provides a listing of file formats it
	supports. If component B extends A's support to several more formats, you can place an
	anchor in A's list, and extend the list from B. For example:
	</p>

	<pre>
	<p>The following list shows the supported formats:</p>
	<ul>
	<li>Portable Network Graphics (.png)</li>
	<li>Joint Photographic Experts Group (.jpeg)</li>
	<li>Graphical Interchange Format (.gif)</li>

	<!-- Extra formats go here -->
	<font color="blue"><anchor id="image_format_list"/></font>
	</ul>
	</pre>

	<p>
	Then component B can make a contribution to the anchor to add more formats
	to the list by specifying the following extension:
	</p>

	<pre>
	<extension point="org.eclipse.help.contentExtension">
	<contentExtension
	file="path/to/extension.xml"/>
	</extension>
	</pre>

	<p>
	Where the file <code>path/to/extension.xml</code> might contain:
	</p>

	<pre>
	<contentExtension>
	<contribution
	content="docs/mydoc.xhtml#mycontent"
	path="/component_a_plugin/docs/doc_with_anchor.xhtml#anchorId">
	</contribution>
	</contentExtension>
	</pre>

	<p>
	The element with the <code>id</code> attribute <code>mycontent</code> in document
	<code>docs/mydoc.xhtml</code> would contain the content you wish to contribute
	into the anchor. The result will be that when the user views the document, the extra content
	will appear at the anchor as though it was explicitly added into the original document.
	</p>

	<h3>Replacing content</h3>

	<p>
	Any XML element in a user assistance document that has an <code>id</code> attribute that is
	unique to that document can be replaced with any other element.
	</p>

	<p>
	As with contributions into anchors, to replace an element, you must write the new element to
	replace with in a separate XML file and hook it into the platform using one of two extension
	points. For <a href="ua_help.htm">help</a> or <a href="ua_cheatsheet.htm">cheat sheet</a> content,
	you must use the <a href="../reference/extension-points/org_eclipse_help_contentExtension.html">
	<code>org.eclipse.help.contentExtension</code></a> extension point. For <a href="ua_intro.htm">
	welcome (intro)</a> extensions, use
	<a href="../reference/extension-points/org_eclipse_ui_intro_configExtension.html"><code>
	org.eclipse.ui.intro.configExtension</code></a>.
	</p>

	<p>
	The only difference with replacements as opposed to contributions into anchors is the name of the
	XML element used in the markup; use the <code>replacement</code> element instead of
	<code>contribution</code> (or <code>replacementContent</code> in the case of welcome). For example:
	</p>

	<pre>
	<contentExtension>
	<replacement
	content="docs/mydoc.xml#myelement"
	path="/plugin.id/path/doc.xml#elementId">
	</replacement>
	</contentExtension>
	</pre>

	<p>
	(Note the markup is different for welcome, as specified in the <a
	href="../reference/extension-points/org_eclipse_ui_intro_configExtension.html"><code>
	org.eclipse.ui.intro.configExtension</code></a> extension point)
	</p>

	<h3>Path format</h3>

	<p>
	The format of the <code>path</code> attribute is <code>/pluginId/path/file.xml#elementId</code>,
	except welcome where it is <code>pageId/path/to/elementId</code> where the pageId is the welcome
	page id, and all other path segments are ids of container elements like groups, leading to the
	target element.
	</p>

	</body>
	</html>