bundles/org.eclipse.pde.doc.user/guide/pde_schema_editor.htm - gerrit/platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><HTML>
 <HEAD>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. 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">
 <title>Extension point schema editor</title>
 </head>

 <BODY BGCOLOR="#ffffff">

 <h2>Extension point schema editor</h2>
 <p>You can open the extension point schema editor in two ways: as a by-product of
 creating a new extension point or by opening an existing extension point
 schema.&nbsp; By
 convention, new schemas have the same name as the extension point id with a <b>.exsd</b> file extension. They are placed in
 <b>schema</b> directory in your plug-in directory tree.&nbsp;&nbsp;</p>
 <p>When a new extension point is created in the PDE, the initial schema file will also be
 created and the schema editor will be opened for editing. You can define the schema
 right away, or close it and do it later. Making a complete
 extension point schema allows PDE to offer automated assistance to the users
 of your extension point.</p>
 <p>The PDE schema editor is based on the same concepts as the plug-in manifest
 editor.&nbsp; It has two form pages and one source page.&nbsp; Since XML schema is verbose and
 can be hard
 to read in its source form, you should use the form pages for most of the
 editing.&nbsp; The source page is useful for reading the resulting source code.</p>
 <h3>Example: Creating schema for the &quot;Sample Parsers&quot; extension point</h3>
 <p>We previously created the &quot;Sample Parsers&quot; extension point and the
 initial schema. We can now open the schema by going into the <b>schema</b>
 folder of our project and double-clicking on the <b>parsers.exsd</b> file.&nbsp;
 This will open the schema editor.</p>
 <p>We want to do the following:</p>
 <ol>
   <li>Define the valid XML elements and attributes for the extension point.</li>
   <li>Define the grammar (content model).</li>
   <li>Provide documentation snippets that will be merged into a reference
     document.</li>
 </ol>
 <p>Every extension point schema starts with a declaration of the
 &quot;extension&quot;
 element.&nbsp; We will add a new XML element called &quot;parser.&quot;</p>
 <ol>
   <li>Press the button <b>New Element</b> in the <b>Extension Points Elements</b>
     section.</li>
   <li>Move to the Properties view and change its name from &quot;New_Element&quot;
     to &quot;parser&quot;</li>
   <li>While the new element is still selected, press the <b>New Attribute</b>
     button. This will create &quot;new_attribute&quot; as its child. Change its <b>
     name</b> to &quot;id&quot; and <b>use</b> to &quot;required&quot; in the property sheet.</li>
   <li>While still in the property sheet, press the button &quot;Clone this
     attribute&quot; available on the local tool bar. This will create a copy of
     the attribute.&nbsp; This is useful because it allows us to quickly define all the
     attributes without leaving the property sheet.</li>
   <li>Change the name of the new attribute into &quot;name.&quot;</li>
   <li>Clone the attribute again. This time, change the name to &quot;class.&quot;&nbsp; This attribute will be used to represent a fully
     qualified name of the Java class that must implement a specific Java
     interface. We need to specify this so that PDE can later take advantage of
     it. Change <b>kind</b> from &quot;string&quot; to &quot;java.&quot;&nbsp;
     Set the <b>basedOn</b> property
     to <b>com.example.xyz.IParser</b>.&nbsp; (This interface does not exist yet, but we will
     make it later.)</li>
 </ol>
 <p>So far, the schema editor should look like this:</p>
 <p align="center">
 <img border="0" src="images/schema-1.png" alt="Extension point schema editor - Definition page" ></p>
 <p align="left">We will now add an additional attribute that takes values from
 a discrete list of choices.&nbsp; This means we need to create an enumeration restriction of
 the base <b>string</b>  type.&nbsp; In addition, we will set a default value for the
 attribute.</p>
 <ol>
   <li>
     While the &quot;parser&quot; element is selected, press&nbsp;
     the <b>New Attribute</b>
     button. Change its name in the property sheet to &quot;mode.&quot;</li>
   <li>
     Click in the value cell of the &quot;restriction&quot; property
     to bring the restriction dialog up.&nbsp;</li>
   <li>
     Change the restriction type from &quot;none&quot; to
     &quot;enumeration.&quot;</li>
   <li>
     Add the following three choices: &quot;never,&quot; &quot;always,&quot;
     and &quot;manual.&quot;&nbsp; (These are our three hypothetical modes for
     the parser extension.)</li>
 </ol>
 <p align="left">The restriction dialog should look like
 this:</p>
 <p align="center">
 <img border="0" src="images/restriction-dialog.png" alt="Type restriction dialog" ></p>
 <p align="left">When the dialog is closed, change the &quot;use&quot; attribute to
 &quot;default&quot; and &quot;value&quot; attribute to &quot;always.&quot;&nbsp;
 This establishes the default value.&nbsp; Note that the status line shows an error message as you are typing the value,
 since it restricts valid values to the three enumeration choices. Once you
 finish typing, the error message should go away because &quot;always&quot; is a
 valid value.</p>
 <p align="left">Now that we have defined all of the elements and attributes, we need to
 define grammar. Our goal is to define that the &quot;extension&quot; element can have any
 number of &quot;parser&quot; elements as children.&nbsp;</p>
 <ol>
   <li>
     Select the &quot;extension&quot; element. Its initial content model shows
     an empty sequence compositor.</li>
   <li>
     Select the sequence compositor and select <b>New-&gt;Reference-&gt;parser</b>
     from the popup menu. This will add the parser reference to
     the sequence compositor.</li>
   <li>
     The default cardinality of references is [1,1] which means
     that there can be exactly one &quot;parser&quot; element. That is not quite what we
     wanted. We select the &quot;parser&quot; reference and change the <b>maxOccurs</b> to &quot;unbounded.&quot;</li>
 </ol>
 <p align="left">After defining the grammar, the DTD approximation
 below the grammar section shows what the grammar for the selected element would
 look like in DTD.&nbsp; This information is provided to help
 developers who are still more comfortable with DTDs than XML schemas.</p>
 <p align="center">
 <img border="0" src="images/schema-2.png" alt="Extension point schema editor - element grammar" ></p>
 <p align="left">Now that we have defined valid elements, attributes and grammar,
 we need to provide some information about the extension point. There are two
 types of schema
 documentation snippets:</p>
 <ul>
   <li>
     Documentation about elements and attributes</li>
   <li>
     Documentation about the extension point usage, API, etc.</li>
 </ul>
 <p align="left">The first snippet type is provided in the Definition page of
 the schema manifest. As you select elements and attributes, you can add short
 text about them in the &quot;Description&quot; section. The expected format is raw HTML (as
 with Javadoc) and the text will be copied as-is into the final reference
 document.</p>
 <ol>
   <li>
     Select the &quot;id&quot; attribute of the
     &quot;parser&quot; element and type the
     following in the Description editor:<br>
     a unique name that will be used to
     reference this parser.</li>
   <li>
     Select the &quot;name&quot; attribute and
     add the following text:<b><br>
     </b>
     a translatable name that will be used for presenting this parser in the UI.</li>
   <li>
     Select the &quot;class&quot; attribute and
     add the following text (note the HTML tags):<b><br>
     </b>
     a fully qualified name of the Java class that implements &lt;samp&gt;com.example.xyz.IParser&lt;/samp&gt;
     interface.</li>
   <li>
     Select the &quot;mode&quot; attribute and
     add the following:<b><br>
     </b>
     an optional flag that indicates how often this parser instance will run
     (default is &lt;samp&gt;always&lt;/samp&gt;).</li>
 </ol>
 <p align="left">We now have to provide a short text description of the extension point
 itself. In order to do that, we switch to the Documentation page:</p>
 <ol>
   <li>
     You should now be on the &quot;Overview&quot; tab.
     In the text editor and add the following text:<br>
     <p style="color:#4444CC; position:relative; left:25px">
     This extension point is used to plug in
     additional parsers.
     The parsers actually do not work - we have just used
     them as an example of extension point schema.<br>
     </p>
     Press <b>Apply</b>.</li>
   <li>
     Click on the  &quot;Examples&quot; tab and add the following text:<br>
 <p style="color:#4444CC; position:relative; left:25px">
 The following is an example of the extension point usage:
 <font color="#4444CC"><pre>
    &lt;p&gt;
    &lt;pre&gt;
       &lt;extension point=&quot;com.example.xyz.parsers&quot;&gt;
          &lt;parser
             id=&quot;com.example.xyz.parser1&quot;
             name=&quot;Sample Parser 1&quot;
             class=&quot;com.example.xyz.SampleParser1&quot;&gt;
          &lt;/parser&gt;
       &lt;/extension&gt;
    &lt;/pre&gt;
    &lt;/p&gt;
 </pre>
 </font>
 </p>
     <p>Press <b>Apply</b>.</p>
   </li>
   <li>Select the &quot;API Information&quot; tab and add the following text:<br>
   <p style="color:#4444CC; position:relative; left:25px">
     Plug-ins that want to extend this extension point must implement &lt;samp&gt;com.example.xyz.IParser&lt;/samp&gt;
     interface.<br>
   </p>
     Press <b>Apply</b>.</li>
   <li>Select the &quot;Supplied Implementation&quot; tab and add the following text:<b><br>
     </b>
     <p style="color:#4444CC; position:relative; left:25px">
     XYZ Plug-in provides default implementation of the parser.
     </p>
     Press <b>Apply</b>.<i>
     <br>
     </i></li>
 </ol>
 <blockquote><i>Note: Special consideration has to be taken when providing examples.
 Normally, PDE would treat the provided text as raw HTML and would not respect new
 line and white space greater than one character (i.e. ignorable white space). This
 is to be expected when regular text is concerned, but is extremely annoying when
 providing examples, where tabbing and vertical alignment is significant if the
 example is to look good. PDE has a compromise for this situation: if it detects
 the HTML tag &lt;pre&gt;, it will take the content as-is (preserving all characters
 without modification) until closing tag &lt;/pre&gt; is seen. This is why we can
 provide an example like the above and be confident that it will look good in the final
 reference document.</i></blockquote>
 <p>You may have already noticed that as you type documentation, more and more
 elements in the editor Outline view acquire a &quot;pen&quot; image overlay. This little
 indicator tells you that the element in question has some text associated with
 it - a quick way to check if the documentation is missing somewhere in the
 document.</p>
 <p align="center">
 <img border="0" src="images/schema-outline.png" alt="Extension point schema editor outline"></p>
 <p>Once we have finished with the documentation, we can take a look at the
 reference documentation. You can do it in two ways. All the time during your
 work, you can preview the reference document by selecting Preview Reference
 Document item from the pop-up menu. Alternatively, you can set up PDE
 preferences (Preferences&gt;Plug-in Development&gt;Compilers, under Schema tab) to
 automatically create reference documentation on each schema file change.
 Regardless of the method to create it, the resulting document for
 this example would look like <a href="parsers.htm">this</a>.</p>


 </body>

 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><HTML>
	<HEAD>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. 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">
	<title>Extension point schema editor</title>
	</head>

	<BODY BGCOLOR="#ffffff">

	<h2>Extension point schema editor</h2>
	<p>You can open the extension point schema editor in two ways: as a by-product of
	creating a new extension point or by opening an existing extension point
	schema.  By
	convention, new schemas have the same name as the extension point id with a <b>.exsd</b> file extension. They are placed in
	<b>schema</b> directory in your plug-in directory tree.  </p>
	<p>When a new extension point is created in the PDE, the initial schema file will also be
	created and the schema editor will be opened for editing. You can define the schema
	right away, or close it and do it later. Making a complete
	extension point schema allows PDE to offer automated assistance to the users
	of your extension point.</p>
	<p>The PDE schema editor is based on the same concepts as the plug-in manifest
	editor.  It has two form pages and one source page.  Since XML schema is verbose and
	can be hard
	to read in its source form, you should use the form pages for most of the
	editing.  The source page is useful for reading the resulting source code.</p>
	<h3>Example: Creating schema for the "Sample Parsers" extension point</h3>
	<p>We previously created the "Sample Parsers" extension point and the
	initial schema. We can now open the schema by going into the <b>schema</b>
	folder of our project and double-clicking on the <b>parsers.exsd</b> file.
	This will open the schema editor.</p>
	<p>We want to do the following:</p>
	<ol>
	<li>Define the valid XML elements and attributes for the extension point.</li>
	<li>Define the grammar (content model).</li>
	<li>Provide documentation snippets that will be merged into a reference
	document.</li>
	</ol>
	<p>Every extension point schema starts with a declaration of the
	"extension"
	element.  We will add a new XML element called "parser."</p>
	<ol>
	<li>Press the button <b>New Element</b> in the <b>Extension Points Elements</b>
	section.</li>
	<li>Move to the Properties view and change its name from "New_Element"
	to "parser"</li>
	<li>While the new element is still selected, press the <b>New Attribute</b>
	button. This will create "new_attribute" as its child. Change its <b>
	name</b> to "id" and <b>use</b> to "required" in the property sheet.</li>
	<li>While still in the property sheet, press the button "Clone this
	attribute" available on the local tool bar. This will create a copy of
	the attribute.  This is useful because it allows us to quickly define all the
	attributes without leaving the property sheet.</li>
	<li>Change the name of the new attribute into "name."</li>
	<li>Clone the attribute again. This time, change the name to "class."  This attribute will be used to represent a fully
	qualified name of the Java class that must implement a specific Java
	interface. We need to specify this so that PDE can later take advantage of
	it. Change <b>kind</b> from "string" to "java."
	Set the <b>basedOn</b> property
	to <b>com.example.xyz.IParser</b>.  (This interface does not exist yet, but we will
	make it later.)</li>
	</ol>
	<p>So far, the schema editor should look like this:</p>
	<p align="center">
	<img border="0" src="images/schema-1.png" alt="Extension point schema editor - Definition page" ></p>
	<p align="left">We will now add an additional attribute that takes values from
	a discrete list of choices.  This means we need to create an enumeration restriction of
	the base <b>string</b> type.  In addition, we will set a default value for the
	attribute.</p>
	<ol>
	<li>
	While the "parser" element is selected, press
	the <b>New Attribute</b>
	button. Change its name in the property sheet to "mode."</li>
	<li>
	Click in the value cell of the "restriction" property
	to bring the restriction dialog up. </li>
	<li>
	Change the restriction type from "none" to
	"enumeration."</li>
	<li>
	Add the following three choices: "never," "always,"
	and "manual."  (These are our three hypothetical modes for
	the parser extension.)</li>
	</ol>
	<p align="left">The restriction dialog should look like
	this:</p>
	<p align="center">
	<img border="0" src="images/restriction-dialog.png" alt="Type restriction dialog" ></p>
	<p align="left">When the dialog is closed, change the "use" attribute to
	"default" and "value" attribute to "always."
	This establishes the default value.  Note that the status line shows an error message as you are typing the value,
	since it restricts valid values to the three enumeration choices. Once you
	finish typing, the error message should go away because "always" is a
	valid value.</p>
	<p align="left">Now that we have defined all of the elements and attributes, we need to
	define grammar. Our goal is to define that the "extension" element can have any
	number of "parser" elements as children. </p>
	<ol>
	<li>
	Select the "extension" element. Its initial content model shows
	an empty sequence compositor.</li>
	<li>
	Select the sequence compositor and select <b>New->Reference->parser</b>
	from the popup menu. This will add the parser reference to
	the sequence compositor.</li>
	<li>
	The default cardinality of references is [1,1] which means
	that there can be exactly one "parser" element. That is not quite what we
	wanted. We select the "parser" reference and change the <b>maxOccurs</b> to "unbounded."</li>
	</ol>
	<p align="left">After defining the grammar, the DTD approximation
	below the grammar section shows what the grammar for the selected element would
	look like in DTD.  This information is provided to help
	developers who are still more comfortable with DTDs than XML schemas.</p>
	<p align="center">
	<img border="0" src="images/schema-2.png" alt="Extension point schema editor - element grammar" ></p>
	<p align="left">Now that we have defined valid elements, attributes and grammar,
	we need to provide some information about the extension point. There are two
	types of schema
	documentation snippets:</p>
	<ul>
	<li>
	Documentation about elements and attributes</li>
	<li>
	Documentation about the extension point usage, API, etc.</li>
	</ul>
	<p align="left">The first snippet type is provided in the Definition page of
	the schema manifest. As you select elements and attributes, you can add short
	text about them in the "Description" section. The expected format is raw HTML (as
	with Javadoc) and the text will be copied as-is into the final reference
	document.</p>
	<ol>
	<li>
	Select the "id" attribute of the
	"parser" element and type the
	following in the Description editor:<br>
	a unique name that will be used to
	reference this parser.</li>
	<li>
	Select the "name" attribute and
	add the following text:<b><br>
	</b>
	a translatable name that will be used for presenting this parser in the UI.</li>
	<li>
	Select the "class" attribute and
	add the following text (note the HTML tags):<b><br>
	</b>
	a fully qualified name of the Java class that implements <samp>com.example.xyz.IParser</samp>
	interface.</li>
	<li>
	Select the "mode" attribute and
	add the following:<b><br>
	</b>
	an optional flag that indicates how often this parser instance will run
	(default is <samp>always</samp>).</li>
	</ol>
	<p align="left">We now have to provide a short text description of the extension point
	itself. In order to do that, we switch to the Documentation page:</p>
	<ol>
	<li>
	You should now be on the "Overview" tab.
	In the text editor and add the following text:<br>
	<p style="color:#4444CC; position:relative; left:25px">
	This extension point is used to plug in
	additional parsers.
	The parsers actually do not work - we have just used
	them as an example of extension point schema.<br>
	</p>
	Press <b>Apply</b>.</li>
	<li>
	Click on the "Examples" tab and add the following text:<br>
	<p style="color:#4444CC; position:relative; left:25px">
	The following is an example of the extension point usage:
	<font color="#4444CC"><pre>
	<p>
	<pre>
	<extension point="com.example.xyz.parsers">
	<parser
	id="com.example.xyz.parser1"
	name="Sample Parser 1"
	class="com.example.xyz.SampleParser1">
	</parser>
	</extension>
	</pre>
	</p>
	</pre>
	</font>
	</p>
	<p>Press <b>Apply</b>.</p>
	</li>
	<li>Select the "API Information" tab and add the following text:<br>
	<p style="color:#4444CC; position:relative; left:25px">
	Plug-ins that want to extend this extension point must implement <samp>com.example.xyz.IParser</samp>
	interface.<br>
	</p>
	Press <b>Apply</b>.</li>
	<li>Select the "Supplied Implementation" tab and add the following text:<b><br>
	</b>
	<p style="color:#4444CC; position:relative; left:25px">
	XYZ Plug-in provides default implementation of the parser.
	</p>
	Press <b>Apply</b>.<i>
	<br>
	</i></li>
	</ol>
	<blockquote><i>Note: Special consideration has to be taken when providing examples.
	Normally, PDE would treat the provided text as raw HTML and would not respect new
	line and white space greater than one character (i.e. ignorable white space). This
	is to be expected when regular text is concerned, but is extremely annoying when
	providing examples, where tabbing and vertical alignment is significant if the
	example is to look good. PDE has a compromise for this situation: if it detects
	the HTML tag <pre>, it will take the content as-is (preserving all characters
	without modification) until closing tag </pre> is seen. This is why we can
	provide an example like the above and be confident that it will look good in the final
	reference document.</i></blockquote>
	<p>You may have already noticed that as you type documentation, more and more
	elements in the editor Outline view acquire a "pen" image overlay. This little
	indicator tells you that the element in question has some text associated with
	it - a quick way to check if the documentation is missing somewhere in the
	document.</p>
	<p align="center">
	<img border="0" src="images/schema-outline.png" alt="Extension point schema editor outline"></p>
	<p>Once we have finished with the documentation, we can take a look at the
	reference documentation. You can do it in two ways. All the time during your
	work, you can preview the reference document by selecting Preview Reference
	Document item from the pop-up menu. Alternatively, you can set up PDE
	preferences (Preferences>Plug-in Development>Compilers, under Schema tab) to
	automatically create reference documentation on each schema file change.
	Regardless of the method to create it, the resulting document for
	this example would look like <a href="parsers.htm">this</a>.</p>


	</body>

	</html>