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

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   <head>
     <meta name="copyright" content=
     "Copyright (c) IBM Corporation and others 2000, 2011. 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=utf-8" />
     <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" type="text/javascript">
 </script>
     <title>
       Content extensions
     </title>

     <style type="text/css">
 /*<![CDATA[*/
     span.c1 {color: blue}
     /*]]>*/
     </style>
   </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="my_anchor"/&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;
       <span class="c1">&lt;anchor id="image_format_list"/&gt;</span>
    &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="org.eclipse.help.contentExtension"&gt;
       &lt;contentExtension
             file="path/to/extension.xml"/&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="docs/mydoc.xhtml#mycontent"
             path="/component_a_plugin/docs/doc_with_anchor.xhtml#anchorId"&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="docs/mydoc.xml#myelement"
             path="/plugin.id/path/doc.xml#elementId"&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 XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<meta name="copyright" content=
	"Copyright (c) IBM Corporation and others 2000, 2011. 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=utf-8" />
	<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" type="text/javascript">
	</script>
	<title>
	Content extensions
	</title>

	<style type="text/css">
	/<![CDATA[/
	span.c1 {color: blue}
	/]]>/
	</style>
	</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 -->
	<span class="c1"><anchor id="image_format_list"/></span>
	</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>